Struct CreateBackupOptions 

pub struct CreateBackupOptions { /* private fields */ }

Options for a single call to BackupEngine::create_new_backup_with_options or BackupEngine::create_new_backup_with_metadata.

Wraps rocksdb::CreateBackupOptions.

Callback ownership

rocksdb_create_backup_options_set_progress_callback and rocksdb_create_backup_options_set_exclude_files_callback take a bare void* state with no destructor argument. db/c.cc stores it in rocksdb_create_backup_options_t::progress_state / exclude_files_state and copies it into a C++ lambda by value. rocksdb_create_backup_options_destroy is just delete options, so the C API never frees the state. This type therefore owns the closures: it frees them when it is dropped, and frees the previous one when a setter is called a second time.

The C++ lambda captures the state pointer by value rather than the options wrapper, so the state must stay alive for the whole backup, not merely until the FFI call returns. Backup creation is synchronous and borrows these options for its duration, so holding the closures in this type is enough.

Implementations

impl CreateBackupOptions

pub fn set_flush_before_backup(&mut self, val: bool)

If true, flush the memtables before taking the backup, so that writes that never reached a WAL are not lost. A flush always happens when 2PC is enabled.

Default: false

pub fn get_flush_before_backup(&self) -> bool

Returns the current flush_before_backup setting.

pub fn set_atomic_flush(&mut self, val: bool)

If true, flush all column families atomically, giving cross column family consistency without WAL files. Combined with BackupEngineOptions::backup_log_files = false this makes it safe to skip backing up WALs for a multi column family database.

Only takes effect when flush_before_backup is also true.

Default: false

pub fn get_atomic_flush(&self) -> bool

Returns the current atomic_flush setting.

pub fn set_decrease_background_thread_cpu_priority(&mut self, val: bool)

If false, background_thread_cpu_priority is ignored. If true, the priority of the copy threads can be lowered. Raising it has no effect, since the threads start at CpuPriority::KNormal.

Default: false

pub fn get_decrease_background_thread_cpu_priority(&self) -> bool

Returns the current decrease_background_thread_cpu_priority setting.

pub fn set_background_thread_cpu_priority(&mut self, val: CpuPriority)

CPU priority for the threads that copy files during the backup. Only used when Self::set_decrease_background_thread_cpu_priority is true.

Default: CpuPriority::KNormal

pub fn get_background_thread_cpu_priority(&self) -> CpuPriority

Returns the current background_thread_cpu_priority setting.

pub fn set_progress_callback<F>(&mut self, callback: F)

where F: Fn() + Send + Sync + 'static,

Registers a closure that RocksDB calls every BackupEngineOptions::callback_trigger_interval_size bytes copied.

The closure is called from the copy threads, not the thread that started the backup. RocksDB serialises the calls behind a mutex, but every copy thread holds a copy of the callback at the same time, so it must be Send + Sync. 'static is required because these options store the closure without borrowing from the caller.

Calling this again replaces and frees the previously registered closure. See the type level docs for why this type owns it.

A panic out of the closure aborts the process, because a Rust panic cannot unwind through the C boundary.

pub fn set_exclude_files_callback<F>(&mut self, callback: F)

where F: Fn(&[u8]) -> bool + Send + Sync + 'static,

Registers a closure that decides which shared files to leave out of the backup. It is called once per candidate file with the file name relative to the backup directory, and returning true excludes that file.

This is an advanced feature. RocksDB trusts the caller to keep the excluded files somewhere the database can still be restored from, for example an alternate backup directory. Restoring such a backup needs those files supplied through RestoreOptions::alternate_dirs, which the C API does not expose, so from this crate the only recovery path is RestoreMode::KKeepLatestDbSessionIdFiles, which opportunistically looks for the missing files in the existing database directory.

Only shared files are ever offered to the closure, so this needs share_table_files and share_files_with_checksum to be true. It also needs schema_version to be at least 2, otherwise creating the backup fails with Invalid argument: exclude_files_callback requires schema_version >= 2.

db/c.cc calls this on the thread driving the backup, but the bound matches Self::set_progress_callback so that both closures have the same requirements.

Calling this again replaces and frees the previously registered closure. A panic out of the closure aborts the process.

Trait Implementations

impl Default for CreateBackupOptions

fn default() -> Self

Returns the “default value” for a type.

impl Drop for CreateBackupOptions

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.