[−][src]Trait rocks::listener::EventListener
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
pub fn on_flush_completed(
&mut self,
db: &DBRef,
flush_job_info: &FlushJobInfo<'_>
)
[src]
&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.
pub fn on_flush_begin(&mut self, db: &DBRef, flush_job_info: &FlushJobInfo<'_>)
[src]
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.
pub fn on_table_file_deleted(&mut self, info: &TableFileDeletionInfo<'_>)
[src]
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.
pub fn on_compaction_completed(
&mut self,
db: &DBRef,
ci: &CompactionJobInfo<'_>
)
[src]
&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.
pub fn on_table_file_created(&mut self, info: &TableFileCreationInfo)
[src]
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.
pub fn on_table_file_creation_started(
&mut self,
info: &TableFileCreationBriefInfo
)
[src]
&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.
pub fn on_memtable_sealed(&mut self, info: &MemTableInfo)
[src]
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.
pub fn on_column_family_handle_deletion_started(
&mut self,
handle: &ColumnFamilyHandle
)
[src]
&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.
pub fn on_external_file_ingested(
&mut self,
db: &DBRef,
info: &ExternalFileIngestionInfo
)
[src]
&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.
pub fn on_background_error(
&mut self,
reason: BackgroundErrorReason,
bg_error: Error
) -> Result<()>
[src]
&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.
pub fn get_compaction_event_listener(
&mut self
) -> Option<&mut dyn CompactionEventListener>
[src]
&mut self
) -> Option<&mut dyn CompactionEventListener>
Factory method to return CompactionEventListener. If multiple listeners provides CompactionEventListner, only the first one will be used.