Type Alias HandleSlowReadersCallback

pub type HandleSlowReadersCallback = extern "C" fn(_: *const MDBX_env, _: *const MDBX_txn, _: i32, _: u64, _: u64, _: u32, _: usize, _: i32) -> HandleSlowReadersReturnCode;

Available on crate feature mdbx only.

Handle-Slow-Readers callback function to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.

Read transactions prevent reuse of pages freed by newer write transactions, thus the database can grow quickly. This callback will be called when there is not enough space in the database (i.e. before increasing the database size or before MDBX_MAP_FULL error) and thus can be used to resolve issues with a “long-lived” read transacttions.

Depending on the arguments and needs, your implementation may wait, terminate a process or thread that is performing a long read, or perform some other action. In doing so it is important that the returned code always corresponds to the performed action.

Arguments

• process_id – A process id of the reader process.
• thread_id – A thread id of the reader thread.
• read_txn_id – An oldest read transaction number on which stalled.
• gap – A lag from the last committed txn.
• space – A space that actually become available for reuse after this reader finished. The callback function can take this value into account to evaluate the impact that a long-running transaction has.
• retry – A retry number starting from 0. If callback has returned 0 at least once, then at end of current handling loop the callback function will be called additionally with negative retry value to notify about the end of loop. The callback function can use this fact to implement timeout reset logic while waiting for a readers.

Returns

A return code that determines the further actions for MDBX and must match the action which was executed by the callback:

• -2 or less – An error condition and the reader was not killed.
• -1 – The callback was unable to solve the problem and agreed on MDBX_MAP_FULL error; MDBX should increase the database size or return MDBX_MAP_FULL error.
• 0 – The callback solved the problem or just waited for a while, libmdbx should rescan the reader lock table and retry. This also includes a situation when corresponding transaction terminated in normal way by mdbx_txn_abort() or mdbx_txn_reset(), and may be restarted. I.e. reader slot isn’t needed to be cleaned from transaction.
• 1 – Transaction aborted asynchronous and reader slot should be cleared immediately, i.e. read transaction will not continue but mdbx_txn_abort() nor mdbx_txn_reset() will be called later.
• 2 or greater – The reader process was terminated or killed, and MDBX should entirely reset reader registration.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 8 bytes