EventListener

All Known Implementing Classes:

AbstractEventListener
```
public interface EventListener
```
EventListener class contains a set of callback 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 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.

Method Summary

All Methods Instance Methods Abstract Methods
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.

- Method Detail
  - onFlushBegin
```
void onFlushBegin(RocksDB db,
                  FlushJobInfo flushJobInfo)
```
    A callback function to RocksDB which will be called before a RocksDB starts to flush memtables. 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.
    
    Parameters:
    
    db - the database
    
    flushJobInfo - the flush job info, contains data copied from respective native structure.
  - onFlushCompleted
```
void onFlushCompleted(RocksDB db,
                      FlushJobInfo flushJobInfo)
```
    callback function to RocksDB which will be called whenever a registered RocksDB flushes a file. 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.
    
    Parameters:
    
    db - the database
    
    flushJobInfo - the flush job info, contains data copied from respective native structure.
  - onTableFileDeleted
```
void onTableFileDeleted(TableFileDeletionInfo tableFileDeletionInfo)
```
    A callback function for RocksDB which will be called whenever a SST file is deleted. Different from 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.
    
    Parameters:
    
    tableFileDeletionInfo - the table file deletion info, contains data copied from respective native structure.
  - onCompactionBegin
```
void onCompactionBegin(RocksDB db,
                       CompactionJobInfo compactionJobInfo)
```
    A callback function to RocksDB which will be called before a RocksDB starts to compact. 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.
    
    Parameters:
    
    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.
  - onCompactionCompleted
```
void onCompactionCompleted(RocksDB db,
                           CompactionJobInfo compactionJobInfo)
```
    A callback 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.
    
    Parameters:
    
    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.
  - onTableFileCreated
```
void onTableFileCreated(TableFileCreationInfo tableFileCreationInfo)
```
    A callback function for RocksDB which will be called whenever a SST file is created. Different from OnCompactionCompleted and OnFlushCompleted, 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 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.
    
    Parameters:
    
    tableFileCreationInfo - the table file creation info, contains data copied from respective native structure.
  - onTableFileCreationStarted
```
void onTableFileCreationStarted(TableFileCreationBriefInfo tableFileCreationBriefInfo)
```
    A callback 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.
    
    Parameters:
    
    tableFileCreationBriefInfo - the table file creation brief info, contains data copied from respective native structure.
  - onMemTableSealed
```
void onMemTableSealed(MemTableInfo memTableInfo)
```
    A callback 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.
    
    Parameters:
    
    memTableInfo - the mem table info, contains data copied from respective native structure.
  - onColumnFamilyHandleDeletionStarted
```
void onColumnFamilyHandleDeletionStarted(ColumnFamilyHandle columnFamilyHandle)
```
    A callback 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.
    
    Parameters:
    
    columnFamilyHandle - is a pointer to the column family handle to be deleted which will become a dangling pointer after the deletion.
  - onExternalFileIngested
```
void onExternalFileIngested(RocksDB db,
                            ExternalFileIngestionInfo externalFileIngestionInfo)
```
    A callback 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.
    
    Parameters:
    
    db - the database
    
    externalFileIngestionInfo - the external file ingestion info, contains data copied from respective native structure.
  - onBackgroundError
```
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. 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 Status::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.
    
    Parameters:
    
    backgroundErrorReason - background error reason code
    
    backgroundError - background error codes
  - onStallConditionsChanged
```
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. 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.
    
    Parameters:
    
    writeStallInfo - write stall info, contains data copied from respective native structure.
  - onFileReadFinish
```
void onFileReadFinish(FileOperationInfo fileOperationInfo)
```
    A callback function for RocksDB which will be called whenever a file read operation finishes.
    
    Parameters:
    
    fileOperationInfo - file operation info, contains data copied from respective native structure.
  - onFileWriteFinish
```
void onFileWriteFinish(FileOperationInfo fileOperationInfo)
```
    A callback function for RocksDB which will be called whenever a file write operation finishes.
    
    Parameters:
    
    fileOperationInfo - file operation info, contains data copied from respective native structure.
  - onFileFlushFinish
```
void onFileFlushFinish(FileOperationInfo fileOperationInfo)
```
    A callback function for RocksDB which will be called whenever a file flush operation finishes.
    
    Parameters:
    
    fileOperationInfo - file operation info, contains data copied from respective native structure.
  - onFileSyncFinish
```
void onFileSyncFinish(FileOperationInfo fileOperationInfo)
```
    A callback function for RocksDB which will be called whenever a file sync operation finishes.
    
    Parameters:
    
    fileOperationInfo - file operation info, contains data copied from respective native structure.
  - onFileRangeSyncFinish
```
void onFileRangeSyncFinish(FileOperationInfo fileOperationInfo)
```
    A callback function for RocksDB which will be called whenever a file rangeSync operation finishes.
    
    Parameters:
    
    fileOperationInfo - file operation info, contains data copied from respective native structure.
  - onFileTruncateFinish
```
void onFileTruncateFinish(FileOperationInfo fileOperationInfo)
```
    A callback function for RocksDB which will be called whenever a file truncate operation finishes.
    
    Parameters:
    
    fileOperationInfo - file operation info, contains data copied from respective native structure.
  - onFileCloseFinish
```
void onFileCloseFinish(FileOperationInfo fileOperationInfo)
```
    A callback function for RocksDB which will be called whenever a file close operation finishes.
    
    Parameters:
    
    fileOperationInfo - file operation info, contains data copied from respective native structure.
  - shouldBeNotifiedOnFileIO
```
boolean shouldBeNotifiedOnFileIO()
```
    If true, the onFileReadFinish(FileOperationInfo) and onFileWriteFinish(FileOperationInfo) will be called. If false, then they won't be called. Default: false
    
    Returns:
    
    whether to callback when file read/write is finished
  - onErrorRecoveryBegin
```
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(). The callback can suppress the automatic recovery by setting returning false. The database will then have to be transitioned out of read-only mode by calling RocksDB#resume().
    
    Parameters:
    
    backgroundErrorReason - background error reason code
    
    backgroundError - background error codes
    
    Returns:
    
    return false if the automatic recovery should be suppressed
  - onErrorRecoveryCompleted
```
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. When this is called, it means normal writes to the database can be issued and the user can initiate any further recovery actions needed
    
    Parameters:
    
    oldBackgroundError - old background error codes

Interface EventListener

Method Summary

Method Detail

onFlushBegin

onFlushCompleted

onTableFileDeleted

onCompactionBegin

onCompactionCompleted

onTableFileCreated

onTableFileCreationStarted

onMemTableSealed

onColumnFamilyHandleDeletionStarted

onExternalFileIngested

onBackgroundError

onStallConditionsChanged

onFileReadFinish

onFileWriteFinish

onFileFlushFinish

onFileSyncFinish

onFileRangeSyncFinish

onFileTruncateFinish

onFileCloseFinish

shouldBeNotifiedOnFileIO

onErrorRecoveryBegin

onErrorRecoveryCompleted