Env - RocksDB

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

static Env* Default();

Returns the default environment suitable for the current operating system. The result belongs to RocksDB and must never be deleted.

Env*

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
);

Creates a sequentially-readable file.

const std::string&

Path to the file to open.

std::unique_ptr<SequentialFile>*

Output parameter for the created file object.

const EnvOptions&

Options for opening the file (direct I/O, mmap, etc.).

Status

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
);

Creates a random access read-only file.

NewWritableFile

virtual Status NewWritableFile(
  const std::string& fname,
  std::unique_ptr<WritableFile>* result,
  const EnvOptions& options
);

Creates a writable file, deleting any existing file with the same name.

NewDirectory

virtual Status NewDirectory(
  const std::string& name,
  std::unique_ptr<Directory>* result
);

Creates a directory object for fsync operations.

File System Operations

FileExists

virtual Status FileExists(const std::string& fname);

Checks if a file exists.

Status

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
);

Lists children of a directory.

DeleteFile

virtual Status DeleteFile(const std::string& fname);

Deletes the named file.

CreateDir

virtual Status CreateDir(const std::string& dirname);

Creates a directory. Returns error if it already exists.

CreateDirIfMissing

virtual Status CreateDirIfMissing(const std::string& dirname);

Creates a directory if it doesn’t exist.

DeleteDir

virtual Status DeleteDir(const std::string& dirname);

Deletes a directory.

GetFileSize

virtual Status GetFileSize(
  const std::string& fname,
  uint64_t* file_size
);

Gets the size of a file.

RenameFile

virtual Status RenameFile(
  const std::string& src,
  const std::string& target
);

Renames a file.

LinkFile

virtual Status LinkFile(
  const std::string& src,
  const std::string& target
);

Creates a hard link.

File Locking

LockFile

virtual Status LockFile(
  const std::string& fname,
  FileLock** lock
);

Locks a file to prevent concurrent access by multiple processes.

const std::string&

Path to the file to lock. May be created if it doesn’t exist.

FileLock**

Output parameter for the lock object.

Status

Returns OK if the lock was acquired, or an error if another process holds the lock.

UnlockFile

virtual Status UnlockFile(FileLock* lock);

Releases a file lock.

Thread Management

Schedule

virtual void Schedule(
  void (*function)(void* arg),
  void* arg,
  Priority pri = LOW,
  void* tag = nullptr,
  void (*unschedFunction)(void* arg) = nullptr
);

Schedules a function to run in a background thread pool.

void (*)(void* arg)

Function to execute.

void*

Argument passed to the function.

Priority

Thread pool priority: BOTTOM, LOW, HIGH, USER.

StartThread

virtual void StartThread(
  void (*function)(void* arg),
  void* arg
);

Starts a new thread.

SetBackgroundThreads

virtual void SetBackgroundThreads(
  int number,
  Priority pri = LOW
);

Sets the number of background worker threads for a priority level.

GetBackgroundThreads

virtual int GetBackgroundThreads(Priority pri = LOW);

Gets the number of background threads for a priority level.

Time Functions

NowMicros

virtual uint64_t NowMicros();

Returns the current time in microseconds since some fixed point.

uint64_t

Current time in microseconds.

NowNanos

virtual uint64_t NowNanos();

Returns the current time in nanoseconds. Should return monotonic time points.

GetCurrentTime

virtual Status GetCurrentTime(int64_t* unix_time);

Gets seconds since Unix epoch (1970-01-01 00:00:00 UTC).

SleepForMicroseconds

virtual void SleepForMicroseconds(int micros);

Sleeps for the specified number of microseconds.

System Information

GetHostName

virtual Status GetHostName(char* name, uint64_t len);

Gets the current host name.

GetAbsolutePath

virtual Status GetAbsolutePath(
  const std::string& db_path,
  std::string* output_path
);

Converts a relative path to an absolute path.

GetFreeSpace

virtual Status GetFreeSpace(
  const std::string& path,
  uint64_t* diskfree
);

Gets the amount of free disk space.

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;
};

bool

Use O_DIRECT for reading data.

bool

Use O_DIRECT for writing data.

uint64_t

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
};

Hints about expected lifetime of data for storage optimization.

Thread Priorities

enum Priority {
  BOTTOM,
  LOW,
  HIGH,
  USER,
  TOTAL
};

Priority

Lowest priority for background operations.

Priority

Default priority for most background operations.

Priority

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;

The FileSystem interface provides additional features like:

IOOptions for per-request hints
Temperature-aware file creation
Async I/O support
Better error reporting with IODebugContext

​Getting the Default Env

​Default

​File Operations

​NewSequentialFile

​NewRandomAccessFile

​NewWritableFile

​NewDirectory

​File System Operations

​FileExists

​GetChildren

​DeleteFile

​CreateDir

​CreateDirIfMissing

​DeleteDir

​GetFileSize

​RenameFile

​LinkFile

​File Locking

​LockFile

​UnlockFile

​Thread Management

​Schedule

​StartThread

​SetBackgroundThreads

​GetBackgroundThreads

​Time Functions

​NowMicros

​NowNanos

​GetCurrentTime

​SleepForMicroseconds

​System Information

​GetHostName

​GetAbsolutePath

​GetFreeSpace

​EnvOptions

​Write Life Time Hints

​Thread Priorities

​Example

​FileSystem API

​See Also

Getting the Default Env

Default

File Operations

NewSequentialFile

NewRandomAccessFile

NewWritableFile

NewDirectory

File System Operations

FileExists

GetChildren

DeleteFile

CreateDir

CreateDirIfMissing

DeleteDir

GetFileSize

RenameFile

LinkFile

File Locking

LockFile

UnlockFile

Thread Management

Schedule

StartThread

SetBackgroundThreads

GetBackgroundThreads

Time Functions

NowMicros

NowNanos

GetCurrentTime

SleepForMicroseconds

System Information

GetHostName

GetAbsolutePath

GetFreeSpace

EnvOptions

Write Life Time Hints

Thread Priorities

Example

FileSystem API

See Also