Skip to content

mdbx: Cursor.GetBatch — batched cursor reads (one cgo call per N records, ~3.5x faster scans) - #240

Open
AskAlexSharov wants to merge 28 commits into
masterfrom
feat-cursor-get-batch
Open

AskAlexSharov wants to merge 28 commits into
masterfrom
feat-cursor-get-batch

Conversation

@AskAlexSharov

@AskAlexSharov AskAlexSharov commented Jul 17, 2026 •

Copy link
Copy Markdown
Collaborator

Scanning via Get(Next) pays the fixed cgo overhead once per record. GetBatch moves the loop into C: one call fills a reusable C-allocated MDBX_val buffer (never scanned for Go pointers), Key(i)/Val(i) return the usual zero-copy views, and eof distinguishes exhaustion from buffer-full. Advancing ops only — there is no way to pass a search key, so for ranged scans position the cursor with Get first and batch with (GetCurrent, Next); DupSort works via (FirstDup, NextDup) etc.

100k-record scan, darwin/arm64: 34.2 ns/record → 10.3 (batch 64) / 9.7 (batch 256+), ~3.5x. Includes correctness + no-allocs tests and the benchmark.

…records

Full-table iteration through Cursor.Get pays the fixed Go->C call
overhead once per record, which dominates the cost of small-record
scans. GetBatch moves the loop into C: one cgo call fills a reusable
C-allocated buffer of MDBX_val pairs (C memory so the cgo runtime never
scans it for Go pointers), and Go reads the results as zero-copy views.

Benchmark (100k records, 12-byte keys/values, darwin/arm64):

  Get_Next          34.2 ns/record
  GetBatch_64       10.3 ns/record
  GetBatch_256       9.7 ns/record
  GetBatch_1024      9.7 ns/record

~3.5x faster full scans; the returned slices have the same lifetime
rules as Cursor.Get (valid until txn end / next batch reusing the
buffer).

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a batched cursor-scan API to reduce per-record cgo overhead by moving the inner mdbx_cursor_get loop into C and returning zero-copy key/value views via a reusable C-allocated buffer.

Changes:

  • Add mdbxgo_cursor_get_batch C helper that retrieves up to N (key,value) pairs per call.
  • Introduce GetBatchBuffer + Cursor.GetBatch Go API backed by C-allocated MDBX_val storage.
  • Add correctness/no-alloc tests and a benchmark comparing Get/Next vs GetBatch.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File Description
mdbx/mdbxgo.h Declares the new mdbxgo_cursor_get_batch helper and documents its contract.
mdbx/mdbxgo.c Implements the batched loop around mdbx_cursor_get and writes results into a caller-provided MDBX_val pair buffer.
mdbx/batch.go Adds the public Go API (GetBatchBuffer, Cursor.GetBatch) and C-memory buffer management.
mdbx/batch_test.go Adds tests for correctness/allocations and a benchmark for scan performance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch_test.go Resolved
Comment thread mdbx/batch_test.go Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
…-on-error

2*(1<<28)*sizeof(MDBX_val) wraps a 32-bit size_t; 1<<20 pairs keeps the
byte count below 2^25 everywhere and is still far beyond useful batch
sizes. GetBatch doc now states the first n pairs stay valid on error.
…ndary paths

Indexing past the pairs actually filled returned stale views from an
earlier fill (possibly of an ended txn) instead of failing; at() now
panics past buf.n. Adds exact-fill boundary and partial-on-error tests,
documents *_MULTIPLE page granularity and write-txn view invalidation,
and reorders the doc example to consume n before handling err.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
An early EINVAL return left buf reporting entries from a previous fill,
so Key/Val could hand out views of an already-ended transaction.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

mdbx/batch.go:56

  • GetBatchBuffer.at() panics with “index out of range…” both for an out-of-range index and for use-after-Close (b.ptr == nil). Splitting the checks provides a clearer panic cause when the buffer has been closed.
	if b.ptr == nil || i < 0 || i >= 2*b.n {
		panic("mdbx: GetBatchBuffer: index out of range of the last GetBatch fill")
	}

Comment thread mdbx/batch.go Resolved
…ill count

GetBatch passes an empty key/value to mdbx_cursor_get, so an op that expects
one silently produced a plausible wrong answer instead of an error: (Set,
Next) matched nothing and reported a clean EOF, (First, Set) ended the scan
after one record the same way, and (SetRange, Next) rewound to the first key.
Restrict opFirst/opNext to the ops that need no input — the start_op/turn_op
sets libmdbx documents for mdbx_cursor_scan, plus the turn ops as opFirst so a
scan can continue past its first batch — and return EINVAL for the rest. The
allow-list also rejects GetCurrent as opNext (it would restream one record
until the buffer filled) and out-of-range op values.

Close now clears the last-fill count as well, so Key/Val panic with "use after
Close" instead of handing out views of freed memory; at() reports that case
separately from an out-of-range index.

Tests: rejected-op table, reverse (Last, Prev) scan, DupSort (FirstDup,
NextDup) scan, use-after-Close and out-of-fill panics. The partial-on-error
test now provokes MDBX_INCOMPATIBLE with NextMultiple, which stays valid under
the allow-list. Scan benchmark is unchanged: 36.6 ns/record for Get/Next vs
9.2 for GetBatch(256).
…ixture

The rejected-op assertions checked IsErrnoSys(err, syscall.EINVAL), which only
holds on POSIX: on Windows MDBX_EINVAL is ERROR_INVALID_PARAMETER, so every
case failed the win job. Pin the rejection itself — an error, n=0, eof=false —
as TestTxn_Reset_ReturnsError already does for the same reason.

fillBatchDB uses fmt.Appendf, fixing the two modernize findings from lint.
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch_test.go Resolved
Comment thread mdbx/batch.go Resolved
Comment thread mdbx/batch.go Resolved
… docs

GetBatchBuffer uniquely owns a calloc allocation but was copyable, so
`c := *buf` gave two values that free the same pointer. Add noCopy, as
Cursor and Txn have; go vet now rejects the copy.

The doc told callers to do ranged scans by positioning with Get and then
batching with (GetCurrent, Next), and nothing tested it -- dropping
GetCurrent from batchFirstOpOK broke the recipe with every test still
green. TestCursor_GetBatch_Ranged covers it, and
TestCursor_GetBatch_AcceptsAllTurnOps covers the turn ops the doc lists
that no test reached.

Doc corrections, none with runtime effect:

- Key said Cursor.Get reports a nil key for FirstDup, LastDup, NextDup
  and PrevDup. cursor.go only nils it for the first two, and libmdbx
  fills it for all four.
- PrevMultiple was missing from the unspecified-key list. It reaches
  fetch_multiple through cursor_sibling_left, which writes only data, so
  every pair after the first carries an empty key -- while the *_MULTIPLE
  note promised a key per pair.
- Close said Key/Val slices point into the buffer's allocation. They view
  libmdbx's pages; castToBytes builds them over iov_base. Close
  invalidates later calls, not slices already returned. The refill/Close
  restriction is a conservative contract, now labelled as one.
- The rejected-op list named "KeyTo/PairTo seeks", which are not
  identifiers here; the Go names are Key*/ExactKeyValue*/Pair*.
- "rejected with EINVAL" now notes ERROR_INVALID_PARAMETER on Windows,
  matching how txn.go:464 words the same thing.
- The MDBX_RESULT_TRUE comments in batch.go, mdbxgo.c and mdbxgo.h gave
  bound seeks as the example. e77127a made those ops rejected, so no op
  reaching the helper can produce RESULT_TRUE; it is kept as a defence
  and now says so.

@awskii awskii left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

51b23f3 covers the eight points from my last review. Three minor follow-ups inline.

Comment thread mdbx/batch_test.go Resolved
Comment thread mdbx/batch_test.go Resolved
Comment thread mdbx/batch.go Resolved
51b23f3 left three defects of its own.

TestCursor_GetBatch_AcceptsAllTurnOps claimed all turn ops but checked
four of eight, and no start op beyond First and Last. Dropping PrevDup,
PrevMultiple, LastDup or GetMultiple from the allow-lists left every test
green. It is now TestCursor_GetBatch_AcceptsAllScanOps and drives every
start and turn op the doc lists across a plain, a DupSort and a
DupSort|DupFixed table; removing any of those four ops now fails it.

The Close and Key docs contradicted each other: Close said returned
slices survive it, Key said to treat them as invalid once Closed. The
slices view libmdbx pages, not the buffer, so state that lifetime once and
drop the conservative-contract sentence.

The "(Last, Prev)" comment had been pushed onto the Ranged test's doc
block; it is back above TestCursor_GetBatch_Reverse.
@AskAlexSharov

Copy link
Copy Markdown
Collaborator Author

GetBatch on linux/amd64, against Erigon's real iterator

dev-bm-e3-ethmainnet-n5, AMD EPYC 4344P, go1.26.8, libmdbx 0.14.3. 100k records, medians of 6 runs.

scan ns/record
Get(Next) loop, this PR's baseline 52.75
GetBatch, batch 64 10.29
GetBatch, batch 256 9.20
GetBatch, batch 1024 8.83

5.7x on the production platform, more than the 3.5x measured on darwin/arm64, because a cgo call costs more here (52.75 against 34.2 ns).

Erigon's cursor2iter.Next is Current() then advance(), which is GetCurrent plus Next: two cgo calls per record. A throwaway benchmark reproducing that shape, with and without copying each key and value:

scan count only copy k,v
Erigon iterator shape 104.55 94.84
Get(Next) loop 52.38 51.19
GetBatch, batch 256 9.88 13.30

Against what Erigon runs today, batching is 10.6x on a bare loop and 7.1x with a per-record copy. Half of that needs no new API: the iterator re-fetches every record with GetCurrent after Next already returned it, and dropping that alone is 2x.

Where it would not help: a 30-second CPU profile of an Erigon execution workload shows mdbxgo_cursor_get_val at ~11% cumulative, but that time is B-tree search (cmp_lexical, search_branch_lexical, page_get_unchecked), which means seeks. GetBatch only speeds up sequential scans, and rejects seek ops.

@awskii awskii left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two minor follow-ups inline.

Comment thread mdbx/batch_test.go Resolved
Comment thread mdbx/batch.go Resolved
… write-txn view and cursor-position limits

- PrevMultiple off a single-value key (and GetCurrent on an empty table)
  returns MDBX_ENODATA; report it as eof instead of erroring the scan.
- Key/Val views in a write txn last only until the next update: any
  Put/Del shifts the page under the batch's other views.
- The cursor sits on the last stored pair after a fill; cursor ops in the
  handler hit the wrong record.
- Scan-ops test now walks each op to eof, crosses DupFixed pages, and
  covers the single-value PrevMultiple case.
- Note how mdbxgo_cursor_get_batch differs from libmdbx's
  mdbx_cursor_get_batch; trim the RESULT_TRUE comments.
Copilot AI balanced review requested due to automatic review settings October 25, 2026 07:24

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Index arithmetic can overflow before validation in both buffer accessors, allowing invalid indexes to return records.

1 open issue
1 resolved since last review

Review effort: Balanced

Comment thread mdbx/batch.go Resolved
Key(math.MinInt) and Val(math.MinInt) overflowed to slot 0 and 1 and returned the first record instead of panicking.
Copilot AI balanced review requested due to automatic review settings November 9, 2026 03:08

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the batched cursor-read change.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

NextMultiple segfaulted on a fresh cursor over a single-value key, returned empty pages without DupFixed, and lost or repeated values when paired with a record op.
Copilot AI balanced review requested due to automatic review settings November 9, 2026 03:19

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The batched cursor-read changes have no active review issues.

No open issues 🎉

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants