public interface EventListener
Note that callback 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
RocksDB.compactFiles(CompactionOptions, ColumnFamilyHandle, List, int, int,
CompactionJobInfo)
(as it may run for a long while) or issue many of
RocksDB.put(ColumnFamilyHandle, WriteOptions, byte[], byte[])
(as Put may be blocked in certain cases) in the same thread in the
EventListener callback.
However, doing
RocksDB.compactFiles(CompactionOptions, ColumnFamilyHandle, List, int, int,
CompactionJobInfo)
and RocksDB.put(ColumnFamilyHandle, WriteOptions, byte[], byte[])
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 onFlushCompleted(RocksDB, FlushJobInfo)
.
[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.
Modifier and Type | Method and Description |
---|---|
void |
onBackgroundError(BackgroundErrorReason backgroundErrorReason,
Status backgroundError)
A callback function for RocksDB which will be called before setting the
background error status to a non-OK value.
|
void |
onColumnFamilyHandleDeletionStarted(ColumnFamilyHandle columnFamilyHandle)
A callback function for RocksDB which will be called before
a column family handle is deleted.
|
void |
onCompactionBegin(RocksDB db,
CompactionJobInfo compactionJobInfo)
A callback function to RocksDB which will be called before a
RocksDB starts to compact.
|
void |
onCompactionCompleted(RocksDB db,
CompactionJobInfo compactionJobInfo)
A callback function for RocksDB which will be called whenever
a registered RocksDB compacts a file.
|
boolean |
onErrorRecoveryBegin(BackgroundErrorReason backgroundErrorReason,
Status backgroundError)
A callback function for RocksDB which will be called just before
starting the automatic recovery process for recoverable background
errors, such as NoSpace().
|
void |
onErrorRecoveryCompleted(Status oldBackgroundError)
A callback function for RocksDB which will be called once the database
is recovered from read-only mode after an error.
|
void |
onExternalFileIngested(RocksDB db,
ExternalFileIngestionInfo externalFileIngestionInfo)
A callback function for RocksDB which will be called after an external
file is ingested using IngestExternalFile.
|
void |
onFileCloseFinish(FileOperationInfo fileOperationInfo)
A callback function for RocksDB which will be called whenever a file close
operation finishes.
|
void |
onFileFlushFinish(FileOperationInfo fileOperationInfo)
A callback function for RocksDB which will be called whenever a file flush
operation finishes.
|
void |
onFileRangeSyncFinish(FileOperationInfo fileOperationInfo)
A callback function for RocksDB which will be called whenever a file
rangeSync operation finishes.
|
void |
onFileReadFinish(FileOperationInfo fileOperationInfo)
A callback function for RocksDB which will be called whenever a file read
operation finishes.
|
void |
onFileSyncFinish(FileOperationInfo fileOperationInfo)
A callback function for RocksDB which will be called whenever a file sync
operation finishes.
|
void |
onFileTruncateFinish(FileOperationInfo fileOperationInfo)
A callback function for RocksDB which will be called whenever a file
truncate operation finishes.
|
void |
onFileWriteFinish(FileOperationInfo fileOperationInfo)
A callback function for RocksDB which will be called whenever a file write
operation finishes.
|
void |
onFlushBegin(RocksDB db,
FlushJobInfo flushJobInfo)
A callback function to RocksDB which will be called before a
RocksDB starts to flush memtables.
|
void |
onFlushCompleted(RocksDB db,
FlushJobInfo flushJobInfo)
callback function to RocksDB which will be called whenever a
registered RocksDB flushes a file.
|
void |
onMemTableSealed(MemTableInfo memTableInfo)
A callback function for RocksDB which will be called before
a memtable is made immutable.
|
void |
onStallConditionsChanged(WriteStallInfo writeStallInfo)
A callback function for RocksDB which will be called whenever a change
of superversion triggers a change of the stall conditions.
|
void |
onTableFileCreated(TableFileCreationInfo tableFileCreationInfo)
A callback function for RocksDB which will be called whenever
a SST file is created.
|
void |
onTableFileCreationStarted(TableFileCreationBriefInfo tableFileCreationBriefInfo)
A callback function for RocksDB which will be called before
a SST file is being created.
|
void |
onTableFileDeleted(TableFileDeletionInfo tableFileDeletionInfo)
A callback function for RocksDB which will be called whenever
a SST file is deleted.
|
boolean |
shouldBeNotifiedOnFileIO()
If true, the
onFileReadFinish(FileOperationInfo)
and onFileWriteFinish(FileOperationInfo) will be called. |
void onFlushBegin(RocksDB db, FlushJobInfo flushJobInfo)
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.
db
- the databaseflushJobInfo
- the flush job info, contains data copied from
respective native structure.void onFlushCompleted(RocksDB db, FlushJobInfo flushJobInfo)
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.
db
- the databaseflushJobInfo
- the flush job info, contains data copied from
respective native structure.void onTableFileDeleted(TableFileDeletionInfo tableFileDeletionInfo)
onCompactionCompleted(RocksDB, CompactionJobInfo)
and
onFlushCompleted(RocksDB, FlushJobInfo)
,
this callback 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(RocksDB, FlushJobInfo)
and
onCompactionCompleted(RocksDB, CompactionJobInfo)
.
Note that if applications would like to use the passed reference outside this function call, they should make copies from the returned value.
tableFileDeletionInfo
- the table file deletion info,
contains data copied from respective native structure.void onCompactionBegin(RocksDB db, CompactionJobInfo compactionJobInfo)
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.
db
- a pointer to the rocksdb instance which just compacted
a file.compactionJobInfo
- a reference to a native CompactionJobInfo struct,
which is released after this function is returned, and must be copied
if it is needed outside of this function.void onCompactionCompleted(RocksDB db, CompactionJobInfo compactionJobInfo)
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.
db
- a pointer to the rocksdb instance which just compacted
a file.compactionJobInfo
- a reference to a native CompactionJobInfo struct,
which is released after this function is returned, and must be copied
if it is needed outside of this function.void onTableFileCreated(TableFileCreationInfo tableFileCreationInfo)
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.
tableFileCreationInfo
- the table file creation info,
contains data copied from respective native structure.void onTableFileCreationStarted(TableFileCreationBriefInfo tableFileCreationBriefInfo)
Note that if applications would like to use the passed reference outside this function call, they should make copies from these returned value.
tableFileCreationBriefInfo
- the table file creation brief info,
contains data copied from respective native structure.void onMemTableSealed(MemTableInfo memTableInfo)
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.
memTableInfo
- the mem table info, contains data
copied from respective native structure.void onColumnFamilyHandleDeletionStarted(ColumnFamilyHandle columnFamilyHandle)
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.
columnFamilyHandle
- is a pointer to the column family handle to be
deleted which will become a dangling pointer after the deletion.void onExternalFileIngested(RocksDB db, ExternalFileIngestionInfo externalFileIngestionInfo)
Note that the this function will run on the same thread as IngestExternalFile(), if this function is blocked, IngestExternalFile() will be blocked from finishing.
db
- the databaseexternalFileIngestionInfo
- the external file ingestion info,
contains data copied from respective native structure.void onBackgroundError(BackgroundErrorReason backgroundErrorReason, Status backgroundError)
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.
backgroundErrorReason
- background error reason codebackgroundError
- background error codesvoid onStallConditionsChanged(WriteStallInfo writeStallInfo)
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.
writeStallInfo
- write stall info,
contains data copied from respective native structure.void onFileReadFinish(FileOperationInfo fileOperationInfo)
fileOperationInfo
- file operation info,
contains data copied from respective native structure.void onFileWriteFinish(FileOperationInfo fileOperationInfo)
fileOperationInfo
- file operation info,
contains data copied from respective native structure.void onFileFlushFinish(FileOperationInfo fileOperationInfo)
fileOperationInfo
- file operation info,
contains data copied from respective native structure.void onFileSyncFinish(FileOperationInfo fileOperationInfo)
fileOperationInfo
- file operation info,
contains data copied from respective native structure.void onFileRangeSyncFinish(FileOperationInfo fileOperationInfo)
fileOperationInfo
- file operation info,
contains data copied from respective native structure.void onFileTruncateFinish(FileOperationInfo fileOperationInfo)
fileOperationInfo
- file operation info,
contains data copied from respective native structure.void onFileCloseFinish(FileOperationInfo fileOperationInfo)
fileOperationInfo
- file operation info,
contains data copied from respective native structure.boolean shouldBeNotifiedOnFileIO()
onFileReadFinish(FileOperationInfo)
and onFileWriteFinish(FileOperationInfo)
will be called. If
false, then they won't be called.
Default: false
boolean onErrorRecoveryBegin(BackgroundErrorReason backgroundErrorReason, Status backgroundError)
backgroundErrorReason
- background error reason codebackgroundError
- background error codesfalse
if the automatic recovery should be suppressedvoid onErrorRecoveryCompleted(Status oldBackgroundError)
oldBackgroundError
- old background error codes