Trait rocks::listener::EventListener

pub trait EventListener {
    fn on_flush_completed(&mut self, db: &DBRef, flush_job_info: &FlushJobInfo) { ... }
    fn on_flush_begin(&mut self, db: &DBRef, flush_job_info: &FlushJobInfo) { ... }
    fn on_table_file_deleted(&mut self, info: &TableFileDeletionInfo) { ... }
    fn on_compaction_completed(&mut self, db: &DBRef, ci: &CompactionJobInfo) { ... }
    fn on_table_file_created(&mut self, info: &TableFileCreationInfo) { ... }
    fn on_table_file_creation_started(
        &mut self, 
        info: &TableFileCreationBriefInfo
    ) { ... }
    fn on_memtable_sealed(&mut self, info: &MemTableInfo) { ... }
    fn on_column_family_handle_deletion_started(
        &mut self, 
        handle: &ColumnFamilyHandle
    ) { ... }
    fn on_external_file_ingested(
        &mut self, 
        db: &DBRef, 
        info: &ExternalFileIngestionInfo
    ) { ... }
    fn on_background_error(
        &mut self, 
        reason: BackgroundErrorReason, 
        bg_error: Error
    ) -> Result<()> { ... }
    fn get_compaction_event_listener(
        &mut self
    ) -> Option<&mut dyn CompactionEventListener> { ... }
}

EventListener class contains a set of call-back functions that will be called when specific RocksDB event happens such as flush. It can be used as a building block for developing custom features such as stats-collector or external compaction algorithm.

Note that call-back functions should not run for an extended period of time before the function returns, otherwise RocksDB may be blocked. For example, it is not suggested to do DB::CompactFiles() (as it may run for a long while) or issue many of DB::Put() (as Put may be blocked in certain cases) in the same thread in the EventListener callback. However, doing DB::CompactFiles() and DB::Put() in another thread is considered safe.

[Threading] All EventListener callback will be called using the actual thread that involves in that specific event. For example, it is the RocksDB background flush thread that does the actual flush to call EventListener::OnFlushCompleted().

[Locking] All EventListener callbacks are designed to be called without the current thread holding any DB mutex. This is to prevent potential deadlock and performance issue when using EventListener callback in a complex way. However, all EventListener call-back functions should not run for an extended period of time before the function returns, otherwise RocksDB may be blocked. For example, it is not suggested to do DB::CompactFiles() (as it may run for a long while) or issue many of DB::Put() (as Put may be blocked in certain cases) in the same thread in the EventListener callback. However, doing DB::CompactFiles() and DB::Put() in a thread other than the EventListener callback thread is considered safe.

FIXME: how to hold CFHandle ref

Provided methods

fn on_flush_completed(&mut self, db: &DBRef, flush_job_info: &FlushJobInfo)

A call-back function to RocksDB which will be called whenever a registered RocksDB flushes a file. The default implementation is no-op.

Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

fn on_flush_begin(&mut self, db: &DBRef, flush_job_info: &FlushJobInfo)

A call-back function to RocksDB which will be called before a RocksDB starts to flush memtables. The default implementation is no-op.

Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

fn on_table_file_deleted(&mut self, info: &TableFileDeletionInfo)

A call-back function for RocksDB which will be called whenever a SST file is deleted. Different from OnCompactionCompleted and OnFlushCompleted, this call-back is designed for external logging service and thus only provide string parameters instead of a pointer to DB. Applications that build logic basic based on file creations and deletions is suggested to implement OnFlushCompleted and OnCompactionCompleted.

Note that if applications would like to use the passed reference outside this function call, they should make copies from the returned value.

fn on_compaction_completed(&mut self, db: &DBRef, ci: &CompactionJobInfo)

A call-back function for RocksDB which will be called whenever a registered RocksDB compacts a file. The default implementation is a no-op.

Note that this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

Arguments

• db: a pointer to the rocksdb instance which just compacted a file.

• ci: a reference to a CompactionJobInfo struct. ci is released after this function is returned, and must be copied if it is needed outside of this function.

fn on_table_file_created(&mut self, info: &TableFileCreationInfo)

A call-back function for RocksDB which will be called whenever a SST file is created. Different from OnCompactionCompleted and OnFlushCompleted, this call-back is designed for external logging service and thus only provide string parameters instead of a pointer to DB. Applications that build logic basic based on file creations and deletions is suggested to implement OnFlushCompleted and OnCompactionCompleted.

Historically it will only be called if the file is successfully created. Now it will also be called on failure case. User can check info.status to see if it succeeded or not.

Note that if applications would like to use the passed reference outside this function call, they should make copies from these returned value.

fn on_table_file_creation_started(&mut self, info: &TableFileCreationBriefInfo)

A call-back function for RocksDB which will be called before a SST file is being created. It will follow by OnTableFileCreated after the creation finishes.

Note that if applications would like to use the passed reference outside this function call, they should make copies from these returned value.

fn on_memtable_sealed(&mut self, info: &MemTableInfo)

A call-back function for RocksDB which will be called before a memtable is made immutable.

Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

Note that if applications would like to use the passed reference outside this function call, they should make copies from these returned value.

fn on_column_family_handle_deletion_started(
    &mut self,
    handle: &ColumnFamilyHandle
)

A call-back function for RocksDB which will be called before a column family handle is deleted.

Note that the this function must be implemented in a way such that it should not run for an extended period of time before the function returns. Otherwise, RocksDB may be blocked.

@param handle is a pointer to the column family handle to be deleted which will become a dangling pointer after the deletion.

fn on_external_file_ingested(
    &mut self,
    db: &DBRef,
    info: &ExternalFileIngestionInfo
)

A call-back function for RocksDB which will be called after an external file is ingested using IngestExternalFile.

Note that the this function will run on the same thread as IngestExternalFile(), if this function is blocked, IngestExternalFile() will be blocked from finishing.

fn on_background_error(
    &mut self,
    reason: BackgroundErrorReason,
    bg_error: Error
) -> Result<()>

A call-back function for RocksDB which will be called before setting the background error status to a non-OK value. The new background error status is provided in bg_error and can be modified by the callback. E.g., a callback can suppress errors by resetting it to Error::OK(), thus preventing the database from entering read-only mode. We do not provide any guarantee when failed flushes/compactions will be rescheduled if the user suppresses an error.

Note that this function can run on the same threads as flush, compaction, and user writes. So, it is extremely important not to perform heavy computations or blocking calls in this function.

Rust: use Ok(()) to suppress errors, use Err(bg_error) otherwise and default impl.

fn get_compaction_event_listener(
    &mut self
) -> Option<&mut dyn CompactionEventListener>

Factory method to return CompactionEventListener. If multiple listeners provides CompactionEventListner, only the first one will be used.

Loading content...

Implementors

Loading content...