rocksdb/
env.rs

1use std::sync::Arc;
2
3use libc::{self, c_int};
4
5use crate::{ffi, Error};
6
7/// An Env is an interface used by the rocksdb implementation to access
8/// operating system functionality like the filesystem etc. Callers
9/// may wish to provide a custom Env object when opening a database to
10/// get fine gain control; e.g., to rate limit file system operations.
11///
12/// All Env implementations are safe for concurrent access from
13/// multiple threads without any external synchronization.
14///
15/// Note: currently, C API behinds C++ API for various settings.
16/// See also: `rocksdb/include/env.h`
17#[derive(Clone)]
18pub struct Env(pub(crate) Arc<EnvWrapper>);
19
20pub(crate) struct EnvWrapper {
21    pub(crate) inner: *mut ffi::rocksdb_env_t,
22}
23
24impl Drop for EnvWrapper {
25    fn drop(&mut self) {
26        unsafe {
27            ffi::rocksdb_env_destroy(self.inner);
28        }
29    }
30}
31
32impl Env {
33    /// Returns default env
34    pub fn new() -> Result<Self, Error> {
35        let env = unsafe { ffi::rocksdb_create_default_env() };
36        if env.is_null() {
37            Err(Error::new("Could not create mem env".to_owned()))
38        } else {
39            Ok(Self(Arc::new(EnvWrapper { inner: env })))
40        }
41    }
42
43    /// Returns a new environment that stores its data in memory and delegates
44    /// all non-file-storage tasks to base_env.
45    pub fn mem_env() -> Result<Self, Error> {
46        let env = unsafe { ffi::rocksdb_create_mem_env() };
47        if env.is_null() {
48            Err(Error::new("Could not create mem env".to_owned()))
49        } else {
50            Ok(Self(Arc::new(EnvWrapper { inner: env })))
51        }
52    }
53
54    /// Returns a new environment which wraps and takes ownership of the provided
55    /// raw environment.
56    ///
57    /// # Safety
58    ///
59    /// Ownership of `env` is transferred to the returned Env, which becomes
60    /// responsible for freeing it. The caller should forget the raw pointer
61    /// after this call.
62    ///
63    /// # When would I use this?
64    ///
65    /// RocksDB's C++ [Env](https://github.com/facebook/rocksdb/blob/main/include/rocksdb/env.h)
66    /// class provides many extension points for low-level database subsystems, such as file IO.
67    /// These subsystems aren't covered within the scope of the C interface or this crate,
68    /// but from_raw() may be used to hand a pre-instrumented Env to this crate for further use.
69    ///
70    pub unsafe fn from_raw(env: *mut ffi::rocksdb_env_t) -> Self {
71        Self(Arc::new(EnvWrapper { inner: env }))
72    }
73
74    /// Sets the number of background worker threads of a specific thread pool for this environment.
75    /// `LOW` is the default pool.
76    ///
77    /// Default: 1
78    pub fn set_background_threads(&mut self, num_threads: c_int) {
79        unsafe {
80            ffi::rocksdb_env_set_background_threads(self.0.inner, num_threads);
81        }
82    }
83
84    /// Sets the size of the high priority thread pool that can be used to
85    /// prevent compactions from stalling memtable flushes.
86    pub fn set_high_priority_background_threads(&mut self, n: c_int) {
87        unsafe {
88            ffi::rocksdb_env_set_high_priority_background_threads(self.0.inner, n);
89        }
90    }
91
92    /// Sets the size of the low priority thread pool that can be used to
93    /// prevent compactions from stalling memtable flushes.
94    pub fn set_low_priority_background_threads(&mut self, n: c_int) {
95        unsafe {
96            ffi::rocksdb_env_set_low_priority_background_threads(self.0.inner, n);
97        }
98    }
99
100    /// Sets the size of the bottom priority thread pool that can be used to
101    /// prevent compactions from stalling memtable flushes.
102    pub fn set_bottom_priority_background_threads(&mut self, n: c_int) {
103        unsafe {
104            ffi::rocksdb_env_set_bottom_priority_background_threads(self.0.inner, n);
105        }
106    }
107
108    /// Wait for all threads started by StartThread to terminate.
109    pub fn join_all_threads(&mut self) {
110        unsafe {
111            ffi::rocksdb_env_join_all_threads(self.0.inner);
112        }
113    }
114
115    /// Lowering IO priority for threads from the specified pool.
116    pub fn lower_thread_pool_io_priority(&mut self) {
117        unsafe {
118            ffi::rocksdb_env_lower_thread_pool_io_priority(self.0.inner);
119        }
120    }
121
122    /// Lowering IO priority for high priority thread pool.
123    pub fn lower_high_priority_thread_pool_io_priority(&mut self) {
124        unsafe {
125            ffi::rocksdb_env_lower_high_priority_thread_pool_io_priority(self.0.inner);
126        }
127    }
128
129    /// Lowering CPU priority for threads from the specified pool.
130    pub fn lower_thread_pool_cpu_priority(&mut self) {
131        unsafe {
132            ffi::rocksdb_env_lower_thread_pool_cpu_priority(self.0.inner);
133        }
134    }
135
136    /// Lowering CPU priority for high priority thread pool.
137    pub fn lower_high_priority_thread_pool_cpu_priority(&mut self) {
138        unsafe {
139            ffi::rocksdb_env_lower_high_priority_thread_pool_cpu_priority(self.0.inner);
140        }
141    }
142}
143
144unsafe impl Send for EnvWrapper {}
145unsafe impl Sync for EnvWrapper {}
rocksdb/env.rs

rocksdb/
env.rs
