ceph/src/rocksdb/java/src/main/java/org/rocksdb/EventListener.java

   1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
   2 //  This source code is licensed under both the GPLv2 (found in the
   3 //  COPYING file in the root directory) and Apache 2.0 License
   4 //  (found in the LICENSE.Apache file in the root directory).
   5
   6 package org.rocksdb;
   7
   8 import java.util.List;
   9
  10 /**
  11  * EventListener class contains a set of callback functions that will
  12  * be called when specific RocksDB event happens such as flush.  It can
  13  * be used as a building block for developing custom features such as
  14  * stats-collector or external compaction algorithm.
  15  *
  16  * Note that callback functions should not run for an extended period of
  17  * time before the function returns, otherwise RocksDB may be blocked.
  18  * For example, it is not suggested to do
  19  * {@link RocksDB#compactFiles(CompactionOptions, ColumnFamilyHandle, List, int, int,
  20  * CompactionJobInfo)} (as it may run for a long while) or issue many of
  21  * {@link RocksDB#put(ColumnFamilyHandle, WriteOptions, byte[], byte[])}
  22  * (as Put may be blocked in certain cases) in the same thread in the
  23  * EventListener callback.
  24  *
  25  * However, doing
  26  * {@link RocksDB#compactFiles(CompactionOptions, ColumnFamilyHandle, List, int, int,
  27  * CompactionJobInfo)} and {@link RocksDB#put(ColumnFamilyHandle, WriteOptions, byte[], byte[])} in
  28  * another thread is considered safe.
  29  *
  30  * [Threading] All EventListener callback will be called using the
  31  * actual thread that involves in that specific event. For example, it
  32  * is the RocksDB background flush thread that does the actual flush to
  33  * call {@link #onFlushCompleted(RocksDB, FlushJobInfo)}.
  34  *
  35  * [Locking] All EventListener callbacks are designed to be called without
  36  * the current thread holding any DB mutex. This is to prevent potential
  37  * deadlock and performance issue when using EventListener callback
  38  * in a complex way.
  39  */
  40 public interface EventListener {
  41   /**
  42    * A callback function to RocksDB which will be called before a
  43    * RocksDB starts to flush memtables.
  44    *
  45    * Note that the this function must be implemented in a way such that
  46    * it should not run for an extended period of time before the function
  47    * returns. Otherwise, RocksDB may be blocked.
  48    *
  49    * @param db the database
  50    * @param flushJobInfo the flush job info, contains data copied from
  51    *     respective native structure.
  52    */
  53   void onFlushBegin(final RocksDB db, final FlushJobInfo flushJobInfo);
  54
  55   /**
  56    * callback function to RocksDB which will be called whenever a
  57    * registered RocksDB flushes a file.
  58    *
  59    * Note that the this function must be implemented in a way such that
  60    * it should not run for an extended period of time before the function
  61    * returns. Otherwise, RocksDB may be blocked.
  62    *
  63    * @param db the database
  64    * @param flushJobInfo the flush job info, contains data copied from
  65    *     respective native structure.
  66    */
  67   void onFlushCompleted(final RocksDB db, final FlushJobInfo flushJobInfo);
  68
  69   /**
  70    * A callback function for RocksDB which will be called whenever
  71    * a SST file is deleted. Different from
  72    * {@link #onCompactionCompleted(RocksDB, CompactionJobInfo)} and
  73    * {@link #onFlushCompleted(RocksDB, FlushJobInfo)},
  74    * this callback is designed for external logging
  75    * service and thus only provide string parameters instead
  76    * of a pointer to DB.  Applications that build logic basic based
  77    * on file creations and deletions is suggested to implement
  78    * {@link #onFlushCompleted(RocksDB, FlushJobInfo)} and
  79    * {@link #onCompactionCompleted(RocksDB, CompactionJobInfo)}.
  80    *
  81    * Note that if applications would like to use the passed reference
  82    * outside this function call, they should make copies from the
  83    * returned value.
  84    *
  85    * @param tableFileDeletionInfo the table file deletion info,
  86    *     contains data copied from respective native structure.
  87    */
  88   void onTableFileDeleted(final TableFileDeletionInfo tableFileDeletionInfo);
  89
  90   /**
  91    * A callback function to RocksDB which will be called before a
  92    * RocksDB starts to compact. The default implementation is
  93    * no-op.
  94    *
  95    * Note that the this function must be implemented in a way such that
  96    * it should not run for an extended period of time before the function
  97    * returns. Otherwise, RocksDB may be blocked.
  98    *
  99    * @param db a pointer to the rocksdb instance which just compacted
 100    *     a file.
 101    * @param compactionJobInfo a reference to a native CompactionJobInfo struct,
 102    *     which is released after this function is returned, and must be copied
 103    *     if it is needed outside of this function.
 104    */
 105   void onCompactionBegin(final RocksDB db, final CompactionJobInfo compactionJobInfo);
 106
 107   /**
 108    * A callback function for RocksDB which will be called whenever
 109    * a registered RocksDB compacts a file. The default implementation
 110    * is a no-op.
 111    *
 112    * Note that this function must be implemented in a way such that
 113    * it should not run for an extended period of time before the function
 114    * returns. Otherwise, RocksDB may be blocked.
 115    *
 116    * @param db a pointer to the rocksdb instance which just compacted
 117    *     a file.
 118    * @param compactionJobInfo a reference to a native CompactionJobInfo struct,
 119    *     which is released after this function is returned, and must be copied
 120    *     if it is needed outside of this function.
 121    */
 122   void onCompactionCompleted(final RocksDB db, final CompactionJobInfo compactionJobInfo);
 123
 124   /**
 125    * A callback function for RocksDB which will be called whenever
 126    * a SST file is created.  Different from OnCompactionCompleted and
 127    * OnFlushCompleted, this callback is designed for external logging
 128    * service and thus only provide string parameters instead
 129    * of a pointer to DB.  Applications that build logic basic based
 130    * on file creations and deletions is suggested to implement
 131    * OnFlushCompleted and OnCompactionCompleted.
 132    *
 133    * Historically it will only be called if the file is successfully created.
 134    * Now it will also be called on failure case. User can check info.status
 135    * to see if it succeeded or not.
 136    *
 137    * Note that if applications would like to use the passed reference
 138    * outside this function call, they should make copies from these
 139    * returned value.
 140    *
 141    * @param tableFileCreationInfo the table file creation info,
 142    *     contains data copied from respective native structure.
 143    */
 144   void onTableFileCreated(final TableFileCreationInfo tableFileCreationInfo);
 145
 146   /**
 147    * A callback function for RocksDB which will be called before
 148    * a SST file is being created. It will follow by OnTableFileCreated after
 149    * the creation finishes.
 150    *
 151    * Note that if applications would like to use the passed reference
 152    * outside this function call, they should make copies from these
 153    * returned value.
 154    *
 155    * @param tableFileCreationBriefInfo the table file creation brief info,
 156    *     contains data copied from respective native structure.
 157    */
 158   void onTableFileCreationStarted(final TableFileCreationBriefInfo tableFileCreationBriefInfo);
 159
 160   /**
 161    * A callback function for RocksDB which will be called before
 162    * a memtable is made immutable.
 163    *
 164    * Note that the this function must be implemented in a way such that
 165    * it should not run for an extended period of time before the function
 166    * returns.  Otherwise, RocksDB may be blocked.
 167    *
 168    * Note that if applications would like to use the passed reference
 169    * outside this function call, they should make copies from these
 170    * returned value.
 171    *
 172    * @param memTableInfo the mem table info, contains data
 173    *     copied from respective native structure.
 174    */
 175   void onMemTableSealed(final MemTableInfo memTableInfo);
 176
 177   /**
 178    * A callback function for RocksDB which will be called before
 179    * a column family handle is deleted.
 180    *
 181    * Note that the this function must be implemented in a way such that
 182    * it should not run for an extended period of time before the function
 183    * returns.  Otherwise, RocksDB may be blocked.
 184    *
 185    * @param columnFamilyHandle is a pointer to the column family handle to be
 186    *     deleted which will become a dangling pointer after the deletion.
 187    */
 188   void onColumnFamilyHandleDeletionStarted(final ColumnFamilyHandle columnFamilyHandle);
 189
 190   /**
 191    * A callback function for RocksDB which will be called after an external
 192    * file is ingested using IngestExternalFile.
 193    *
 194    * Note that the this function will run on the same thread as
 195    * IngestExternalFile(), if this function is blocked, IngestExternalFile()
 196    * will be blocked from finishing.
 197    *
 198    * @param db the database
 199    * @param externalFileIngestionInfo the external file ingestion info,
 200    *     contains data copied from respective native structure.
 201    */
 202   void onExternalFileIngested(
 203       final RocksDB db, final ExternalFileIngestionInfo externalFileIngestionInfo);
 204
 205   /**
 206    * A callback function for RocksDB which will be called before setting the
 207    * background error status to a non-OK value. The new background error status
 208    * is provided in `bg_error` and can be modified by the callback. E.g., a
 209    * callback can suppress errors by resetting it to Status::OK(), thus
 210    * preventing the database from entering read-only mode. We do not provide any
 211    * guarantee when failed flushes/compactions will be rescheduled if the user
 212    * suppresses an error.
 213    *
 214    * Note that this function can run on the same threads as flush, compaction,
 215    * and user writes. So, it is extremely important not to perform heavy
 216    * computations or blocking calls in this function.
 217    *
 218    * @param backgroundErrorReason background error reason code
 219    * @param backgroundError background error codes
 220    */
 221   void onBackgroundError(
 222       final BackgroundErrorReason backgroundErrorReason, final Status backgroundError);
 223
 224   /**
 225    * A callback function for RocksDB which will be called whenever a change
 226    * of superversion triggers a change of the stall conditions.
 227    *
 228    * Note that the this function must be implemented in a way such that
 229    * it should not run for an extended period of time before the function
 230    * returns. Otherwise, RocksDB may be blocked.
 231    *
 232    * @param writeStallInfo write stall info,
 233    *     contains data copied from respective native structure.
 234    */
 235   void onStallConditionsChanged(final WriteStallInfo writeStallInfo);
 236
 237   /**
 238    * A callback function for RocksDB which will be called whenever a file read
 239    * operation finishes.
 240    *
 241    * @param fileOperationInfo file operation info,
 242    *     contains data copied from respective native structure.
 243    */
 244   void onFileReadFinish(final FileOperationInfo fileOperationInfo);
 245
 246   /**
 247    * A callback function for RocksDB which will be called whenever a file write
 248    * operation finishes.
 249    *
 250    * @param fileOperationInfo file operation info,
 251    *     contains data copied from respective native structure.
 252    */
 253   void onFileWriteFinish(final FileOperationInfo fileOperationInfo);
 254
 255   /**
 256    * A callback function for RocksDB which will be called whenever a file flush
 257    * operation finishes.
 258    *
 259    * @param fileOperationInfo file operation info,
 260    *     contains data copied from respective native structure.
 261    */
 262   void onFileFlushFinish(final FileOperationInfo fileOperationInfo);
 263
 264   /**
 265    * A callback function for RocksDB which will be called whenever a file sync
 266    * operation finishes.
 267    *
 268    * @param fileOperationInfo file operation info,
 269    *     contains data copied from respective native structure.
 270    */
 271   void onFileSyncFinish(final FileOperationInfo fileOperationInfo);
 272
 273   /**
 274    * A callback function for RocksDB which will be called whenever a file
 275    * rangeSync operation finishes.
 276    *
 277    * @param fileOperationInfo file operation info,
 278    *     contains data copied from respective native structure.
 279    */
 280   void onFileRangeSyncFinish(final FileOperationInfo fileOperationInfo);
 281
 282   /**
 283    * A callback function for RocksDB which will be called whenever a file
 284    * truncate operation finishes.
 285    *
 286    * @param fileOperationInfo file operation info,
 287    *     contains data copied from respective native structure.
 288    */
 289   void onFileTruncateFinish(final FileOperationInfo fileOperationInfo);
 290
 291   /**
 292    * A callback function for RocksDB which will be called whenever a file close
 293    * operation finishes.
 294    *
 295    * @param fileOperationInfo file operation info,
 296    *     contains data copied from respective native structure.
 297    */
 298   void onFileCloseFinish(final FileOperationInfo fileOperationInfo);
 299
 300   /**
 301    * If true, the {@link #onFileReadFinish(FileOperationInfo)}
 302    * and {@link #onFileWriteFinish(FileOperationInfo)} will be called. If
 303    * false, then they won't be called.
 304    *
 305    * Default: false
 306    *
 307    * @return whether to callback when file read/write is finished
 308    */
 309   boolean shouldBeNotifiedOnFileIO();
 310
 311   /**
 312    * A callback function for RocksDB which will be called just before
 313    * starting the automatic recovery process for recoverable background
 314    * errors, such as NoSpace(). The callback can suppress the automatic
 315    * recovery by setting returning false. The database will then
 316    * have to be transitioned out of read-only mode by calling
 317    * RocksDB#resume().
 318    *
 319    * @param backgroundErrorReason background error reason code
 320    * @param backgroundError background error codes
 321    * @return return {@code false} if the automatic recovery should be suppressed
 322    */
 323   boolean onErrorRecoveryBegin(
 324       final BackgroundErrorReason backgroundErrorReason, final Status backgroundError);
 325
 326   /**
 327    * A callback function for RocksDB which will be called once the database
 328    * is recovered from read-only mode after an error. When this is called, it
 329    * means normal writes to the database can be issued and the user can
 330    * initiate any further recovery actions needed
 331    *
 332    * @param oldBackgroundError old background error codes
 333    */
 334   void onErrorRecoveryCompleted(final Status oldBackgroundError);
 335 }