The Env class abstracts operating system functionality including file system operations, thread management, and system time. It allows RocksDB to be portable across different platforms and enables custom implementations for specialized environments.
Getting the Default Env
Default
Returns the default environment suitable for the current operating system. The result belongs to RocksDB and must never be deleted.
Returns a pointer to the default environment.
File Operations
NewSequentialFile
virtual Status NewSequentialFile(
const std::string& fname,
std::unique_ptr<SequentialFile>* result,
const EnvOptions& options
);
Path to the file to open.
result
std::unique_ptr<SequentialFile>*
Output parameter for the created file object.
Options for opening the file (direct I/O, mmap, etc.).
Returns OK on success, or an error status if the file cannot be opened.
NewRandomAccessFile
virtual Status NewRandomAccessFile(
const std::string& fname,
std::unique_ptr<RandomAccessFile>* result,
const EnvOptions& options
);
NewWritableFile
virtual Status NewWritableFile(
const std::string& fname,
std::unique_ptr<WritableFile>* result,
const EnvOptions& options
);
NewDirectory
virtual Status NewDirectory(
const std::string& name,
std::unique_ptr<Directory>* result
);
File System Operations
FileExists
virtual Status FileExists(const std::string& fname);
Returns OK if the file exists, NotFound if it doesn’t exist.
GetChildren
virtual Status GetChildren(
const std::string& dir,
std::vector<std::string>* result
);
DeleteFile
virtual Status DeleteFile(const std::string& fname);
CreateDir
virtual Status CreateDir(const std::string& dirname);
CreateDirIfMissing
virtual Status CreateDirIfMissing(const std::string& dirname);
DeleteDir
virtual Status DeleteDir(const std::string& dirname);
GetFileSize
virtual Status GetFileSize(
const std::string& fname,
uint64_t* file_size
);
RenameFile
virtual Status RenameFile(
const std::string& src,
const std::string& target
);
LinkFile
virtual Status LinkFile(
const std::string& src,
const std::string& target
);
File Locking
LockFile
virtual Status LockFile(
const std::string& fname,
FileLock** lock
);
Path to the file to lock. May be created if it doesn’t exist.
Output parameter for the lock object.
Returns OK if the lock was acquired, or an error if another process holds the lock.
UnlockFile
virtual Status UnlockFile(FileLock* lock);
Thread Management
Schedule
virtual void Schedule(
void (*function)(void* arg),
void* arg,
Priority pri = LOW,
void* tag = nullptr,
void (*unschedFunction)(void* arg) = nullptr
);
Argument passed to the function.
Thread pool priority: BOTTOM, LOW, HIGH, USER.
StartThread
virtual void StartThread(
void (*function)(void* arg),
void* arg
);
SetBackgroundThreads
virtual void SetBackgroundThreads(
int number,
Priority pri = LOW
);
GetBackgroundThreads
virtual int GetBackgroundThreads(Priority pri = LOW);
Time Functions
NowMicros
virtual uint64_t NowMicros();
Current time in microseconds.
NowNanos
virtual uint64_t NowNanos();
GetCurrentTime
virtual Status GetCurrentTime(int64_t* unix_time);
virtual void SleepForMicroseconds(int micros);
GetHostName
virtual Status GetHostName(char* name, uint64_t len);
GetAbsolutePath
virtual Status GetAbsolutePath(
const std::string& db_path,
std::string* output_path
);
GetFreeSpace
virtual Status GetFreeSpace(
const std::string& path,
uint64_t* diskfree
);
EnvOptions
struct EnvOptions {
bool use_mmap_reads = false;
bool use_mmap_writes = true;
bool use_direct_reads = false;
bool use_direct_writes = false;
bool allow_fallocate = true;
bool set_fd_cloexec = true;
uint64_t bytes_per_sync = 0;
bool strict_bytes_per_sync = false;
bool fallocate_with_keep_size = true;
size_t compaction_readahead_size = 0;
size_t writable_file_max_buffer_size = 1024 * 1024;
RateLimiter* rate_limiter = nullptr;
};
Use O_DIRECT for reading data.
Use O_DIRECT for writing data.
Incrementally sync files to disk while writing. 0 means no incremental sync.
Write Life Time Hints
enum WriteLifeTimeHint {
WLTH_NOT_SET = 0,
WLTH_NONE,
WLTH_SHORT,
WLTH_MEDIUM,
WLTH_LONG,
WLTH_EXTREME
};
Thread Priorities
enum Priority {
BOTTOM,
LOW,
HIGH,
USER,
TOTAL
};
Lowest priority for background operations.
Default priority for most background operations.
High priority for operations like flush.
Example
#include "rocksdb/env.h"
using namespace ROCKSDB_NAMESPACE;
// Get default environment
Env* env = Env::Default();
// Create a directory
Status s = env->CreateDirIfMissing("/tmp/testdb");
assert(s.ok());
// Check if file exists
s = env->FileExists("/tmp/testdb/CURRENT");
if (s.IsNotFound()) {
// File doesn't exist
}
// Get file size
uint64_t file_size;
s = env->GetFileSize("/tmp/testdb/000001.sst", &file_size);
// Schedule background work
env->Schedule([](void* arg) {
// Background task
}, nullptr, Env::LOW);
// Get current time
uint64_t now_micros = env->NowMicros();
FileSystem API
For more fine-grained control, use the FileSystem interface:
const std::shared_ptr<FileSystem>& GetFileSystem() const;
- IOOptions for per-request hints
- Temperature-aware file creation
- Async I/O support
- Better error reporting with IODebugContext
See Also