db: add drainReaders flag to BeginTemporalRw and TryBeginTemporalRo/TryView for MDBX GC

[mh0lt]

Summary

MDBX GC can only reclaim freed pages when openTxs=1 at commit time (only the committing RW tx itself). Any RO tx opened before the RW tx holds an older snapshot, preventing the GC from advancing cached_oldest and reclaiming pages from prior transactions. This causes unbounded DB file growth.

RO txs opened after BeginTemporalRw see the same snapshot (txnid N) as the RW tx and do NOT block GC — they don't hold older snapshots.

Proposed API Changes

BeginTemporalRw(ctx context.Context, drainReaders ...bool) (TemporalRwTx, error)

When drainReaders=true:

1. Acquire exclusive write lock on a shared sync.RWMutex (the "commit gate")
2. Call the underlying BeginRw to create the MDBX write transaction
3. Release the write lock immediately

This drains all in-flight background RO txs that hold older snapshots before the RW tx is created. New RO txs can open immediately after — they see the same snapshot as the RW tx and won't block GC.

TryBeginTemporalRo(ctx context.Context) (TemporalRoTx, bool, error)

Attempts commitGate.TryRLock(). If the gate is held by a committing writer, returns (nil, false, nil) instead of blocking. Callers can return cached/stale data.

TryView(ctx context.Context, f func(tx Tx) error) (bool, error)

Same as View but uses TryRLock. Returns (false, nil) if a commit is in progress, allowing the caller to skip the read without blocking.

Background

The commit gate is an sync.RWMutex:

• Background readers (collation db.View(), sentry status, etc.) hold RLock — multiple can run concurrently
• Commit paths set drainReaders=true on BeginTemporalRw — waits for existing RLock holders to finish, then creates the RW tx and releases immediately
• Lock hold time is microseconds (just the BeginRw call), not the full commit duration

Without this, background collation and sentry status db.View() calls open RO txs that overlap with commits, keeping openTxs > 1 and preventing MDBX GC page reclamation — leading to unbounded DB growth (observed: 8 GB → 526 GB overnight).

Implementation Notes

• The sync.RWMutex lives on the Aggregator and is exposed via CommitGate() *sync.RWMutex
• TryBeginTemporalRo / TryView are opt-in for background readers that can tolerate stale data
• Critical readers that MUST have fresh data continue using BeginTemporalRo / View (blocking RLock)
• The temporal DB layer (kv_temporal.go) implements the gate internally — callers don't manage locks directly

🤖 Generated with Claude Code

[mh0lt]

Design note: The drainReaders bool parameter is preferred over a separate BeginTemporalRwDrained method. The bool forces every caller of BeginTemporalRw to explicitly decide whether drain semantics are needed — it makes the choice visible and intentional at every callsite, rather than allowing callers to use the non-drain variant without thinking about the implications.

🤖 Generated with Claude Code

[AskAlexSharov]

fyi: mdbx has:

/** \brief Enumerate the entries in the reader lock table.
 *
 * \ingroup c_statinfo
 *
 * \param [in] env     An environment handle returned by \ref mdbx_env_create().
 * \param [in] func    A \ref MDBX_reader_list_func function.
 * \param [in] ctx     An arbitrary context pointer for the enumeration
 *                     function.
 *
 * \returns A non-zero error value on failure and 0 on success,
 * or \ref MDBX_RESULT_TRUE if the reader lock table is empty. */
LIBMDBX_API int mdbx_reader_list(const MDBX_env *env, MDBX_reader_list_func *func, void *ctx);

/** \brief Check for stale entries in the reader lock table.
 * \ingroup c_extra
 *
 * \param [in] env     An environment handle returned by \ref mdbx_env_create().
 * \param [out] dead   Number of stale slots that were cleared.
 *
 * \returns A non-zero error value on failure and 0 on success,
 * or \ref MDBX_RESULT_TRUE if a dead reader(s) found or mutex was recovered. */
LIBMDBX_API int mdbx_reader_check(MDBX_env *env, int *dead);

also mdbx added some monitoring for "how much data hoolded now by all readers" - but i didn't have time to add it to grafana.

[AskAlexSharov]

very hard to say anything about api-change. because it require from me to switch experimenting in this direction. because intuition is not enough.

[sudeepdino008]

Any RO tx opened before the RW tx holds an older snapshot, preventing the GC from advancing cached_oldest and reclaiming pages from prior transactions
-- but this is only for more recent pages (determined by oldest rotx before the rwtx). If we're closing up rotxs regularly, we should still me advancing the free list.

[wmitsuda]

probably related: #18421

[JkLondon]

@mh0lt feel free to experiment with readers here (added metrics + commit gate)
#20953

[VBulikov]

yperbasis added Imp2 as Importance