Skip to content

Move relation data page numbers back to a per-attachment cache - #9335

Open
dyemanov wants to merge 2 commits into
masterfrom
work/dp_num_cache_rework
Open

dyemanov wants to merge 2 commits into
masterfrom
work/dp_num_cache_rework

Conversation

@dyemanov

Copy link
Copy Markdown
Member

NB: This description (AI assisted, manually validated) is intentionally left quite verbose as it documents some decisions that may be not obvious from the patch itself. My apologies for the long read.

Every RelationPages object carries a SortedArray of up to 64{sequence → physical number} entries:

  • the capacity is per relation, so scanning a relation with more than 64 data pages thrashes the map instead of reusing it, and relations cannot share their warm entries;
  • in 6.0 the map is guarded by the page list mutex, so each lookup takes the mutex twice (get and set) and concurrent requests reading the same relation serialise on that single lock;
  • eviction is a partial sort of the array by a mark counter, performed under the same lock.

5.0-release kept the same map but without the lock, which is why it scales far better under concurrency. The lock is also visible on a single thread: the old map pays for a lock/unlock pair, a binary search and mark maintenance on every data page lookup, while the new cache is one lock-free hash probe.

Design

One DataPageNumberCache per attachment, created lazily in att_pool and freed with it. It embeds 1024 preallocated entries (m_items), hashes into 1021 buckets (m_map) and uses clock (second-chance) replacement, so recently used entries survive while a single cold entry is replaced per miss. Cached numbers are re-validated before use, so a stale or evicted entry can only cost a pointer page lookup, never return wrong data. Given the cache is attachment-local, the engine's per-attachment serialization is sufficient.

Why RelationPages keeps its getDPNumber/setDPNumber wrappers

The cache could have been called directly from dpm.epp, but the wrappers were kept deliberately:

  • all DPM call sites already hold a resolved RelationPages, obtained from getPages(), getBasePages() or getTempPages(), and need its page space for the window anyway — routing through the object avoids resolving the page set or deriving its identity a second time;
  • the identity is a property of the page set, not of the attachment:
    m_pageSetId lives in RelationPages, so getPageSetId() belongs next to it; the attachment only owns the storage;
  • callers stay unaware of the key representation and of the incarnation refresh rules, so those rules exist in one place. A future change (another identity component, a different cache placement) touches RelationPages only;
  • the accessors remain inline and const in Relation.h, so nothing is added to the hot path — they compile into DPM_get/DPM_next.

Why the cache class has its own header

Attachment.h is one of the most widely included engine headers and does not include Relation.h, while Relation.h includes Attachment.h. Keeping DataPageNumberCache in its own header (src/jrd/DataPageNumberCache.h), with no Jrd dependencies beyond firebird.h and Hash.h and with PageSetId defined as a plain value type (FB_UINT64), avoids an include cycle between Attachment.h and Relation.h, keeps Attachment.h self-contained, and lets the unit tests exercise the cache without an Attachment or a database.

Why this key format

A key must uniquely identify a specific incarnation of a page set:

  • the same relation can own several RelationPages (a tablespace move creates a new page space, GTT/LTT instances have separate page sets), and RelationPages objects are recycled from a free list;
  • a purely semantic tuple {relationId, pageSpaceId, instanceId} is not unique across incarnations:
    1. ALTER TABLE ... SET TABLESPACE round-trips (PRIMARY → TS → PRIMARY) reuse {relationId, DB_PAGE_SPACE, 0} on the same RelationPages via reset(pageSpaceId);
    2. DROP TABLE followed by CREATE TABLE reuses deleted relation IDs (RelationNode::generateRelId in DdlNodes.epp:6736-6838), producing the same {relationId, DB_PAGE_SPACE, 0} in a newly allocated RelationPages;
    3. declared LTTs (DECLARE LOCAL TEMPORARY TABLE) have a deterministic relationId (MIN_DECLARED_LTT_ID + tableNumber) and reuse the request's req_local_table_instance_id across repeated request executions after DeclareLocalTableNode::reset() frees and recycles the page set via reuse();
    4. created LTTs rotate att_next_ltt_id across 1024 IDs (DdlNodes.epp:10370-10393), and tablespace IDs wrap modulo 255 (TablespaceNodes.epp:208-211).

Because PAG_release_pages only flips PIP bits (and CCH_clean_page only clears dirty flags for temp pages) without zeroing the on-page data_page header, an unallocated old data page still carries pag_type == pag_data, dpg_relation == relationId and dpg_sequence == dpSequence, so header validation (pageOk) cannot distinguish a reused semantic tuple from the previous incarnation.

Each page-set incarnation therefore gets a process-wide monotonic 64-bit ID, backed by a static atomic counter:

typedef FB_UINT64 PageSetId;

struct Key                       // 8 + 4 (+ 4 align) = 16 bytes
{
    PageSetId pageSetId = 0;     // monotonic page-set incarnation ID
    ULONG sequence = 0;
};
  • a fresh m_pageSetId is assigned in the RelationPages constructor and when the page set is reset or recycled (updatePageSpaceId in reset() and updateIdentity in reuse()); setInstanceId() (called by retainPages() on a retaining commit) keeps m_pageSetId unchanged because the physical pages are preserved;
  • because the counter is process-wide and 64-bit, it never repeats across reset(), reuse(), SET TABLESPACE round-trips, LTT re-executions, relation/tablespace ID reuse, or memory-pool address reuse after a RelationPages is destroyed and reallocated;
  • m_pageSetId is stored as std::atomic<PageSetId> and read with std::memory_order_relaxed in getPageSetId(), so lock-free readers in getDPNumber/setDPNumber cannot race or tear against a concurrent reset().

Key variants considered during implementation and measured on the scan benchmark:

key stored size
{RelationPages*, generation} (prototype) 16 B
{relationId, pageSpaceId, instanceId, sequence} 24 B
{relationId, tagged id, sequence} 24 B
{relationId, tagged id, sequence}, flattened 16 B
{relationId, id, instance flag, sequence}, precomputed key 16 B
{monotonic pageSetId, sequence} + embedded m_items (final) 16 B

The single-word 64-bit PageSetId makes the final key the fastest of all tested variants.

Performance

Benchmark: dp_cache_bench <db> scan <connections> <passes> 2048, all runs interleaved; medians of 5 runs.

Each version was measured on a database created by itself from the same schema and data: 500,000 rows, 8,192-byte pages, 4,432 data pages, 3 pointer pages, 61 % fill (verified with gstat).

Single and concurrent connections (v5.0-release vs master vs. patched)

N 5.0-release master patched vs master vs 5.0-release
1 120 ms 135 ms 127 ms -5.9% +5.8% (down from 12.5%)
4 140 ms 484 ms 163 ms 3.0x faster +16.4% (down from 245.7%)
8 215 ms 1662 ms 202 ms 8.2x faster 1.06x faster (-6.0%)
16 435 ms 5744 ms 343 ms 16.7x faster 1.27x faster (-21.1%)
32 1561 ms 10835 ms 915 ms 11.8x faster 1.71x faster (-41.4%)
  • Single thread: 6.0 is 6.1 % behind 5.0 in executed instructions (12.5 % in pure scan wall time); the cache recovers more than half of the wall-time gap (down to +5.8 %) and ~44 % of the instruction gap (down to +3.4 %). The residual difference comes from other 6.0 engine work, not from page number lookups.
  • Concurrency: in 5.0 metadata (jrd_rel / RelationPages) was per-attachment so its map had no lock and scaled; in 6.0 RelationPages is shared via MetadataCache, and its per-relation mutex made it 3.0–16.7× slower from 4 to 32 connections.
  • At 1-4 connections 1-2% of the slowdown are the virtual dispatch cost (Firebird::HashTable::Entry uses virtual isEqual() and get() methods), the rest comes from the unrelated engine parts. From 8 to 32 connections, shared buffer-cache latch contention on pointer-page fetches grows, so avoiding ~960 pointer-page CCH_FETCH/CCH_HANDOFF cycles per pass per connection outweighs the single-thread baseline gap and makes the patched build 1.06–1.71× faster than 5.0.

Trade-offs

  • the cache is per attachment: nothing is shared, a new attachment starts cold, and each used cache costs roughly 64 KB (1024 embedded slots plus the 1021-bucket array) in a single pool allocation until the attachment is closed; attachments that never cache a data page number do not allocate it;
  • the capacity is fixed; a workload touching more than 1024 distinct {page set, sequence} pairs per attachment still evicts entries (though the old map was capped at 64 per relation);
  • clock replacement is an approximation of LRU and has no tuning knobs — it was chosen because a hit costs a single bit store instead of relinking entries;
  • when a shared permanent RelationPages is reset by one attachment, that attachment immediately frees its own cached slots via invalidateDPNumbers(tdbb), while other attachments' entries under the retired m_pageSetId become unreachable and age out via clock replacement.

Correctness

  • Every page-set incarnation gets a unique 64-bit PageSetId, updated atomically on construction, reset() and reuse(). Recycled RelationPages objects, SET TABLESPACE round-trips, declared LTT re-executions, and recreated tables that reuse a dropped relationId or pageSpaceId always receive a new key, so entries of a previous incarnation are unreachable in every attachment's cache.
  • On reset() and reuse(), RelationPages::invalidateDPNumbers(tdbb) also purges all slots belonging to the retiring PageSetId from the current attachment's cache and returns them to m_free, so temporary table and DDL churn does not leave dead entries occupying capacity.
  • Cached numbers are validated on use in both DPM_get and DPM_next (page type and flags, dpg_relation, dpg_sequence, dpg_count > 0). When validation (pageOk) fails, relPages->invalidateDPNumber(tdbb, dpSequence) immediately removes the stale entry (so it does not stay marked used = true if the pointer-page fallback skips an empty slot) before falling through to the pointer page path.
  • Entries are also invalidated explicitly when a data page is freed on record deletion (DPM_delete → invalidateDPNumber(tdbb, dpSequence + s)). Other page-freeing paths in dpm.epp either release whole
    relation page sets (DPM_delete_relation_pages → relPages->reset(tdbb)) or release only orphan fragment / blob pages (DPM_release, delete_tail), which are never cached.
  • Readers and writers go through the same accessor, so an entry updated after a pointer page change is the same slot readers look up.

Verification

  • Release and Debug: make run_tests — 120 + 35 (28 existing + 7 new cache tests) + 8 cases pass.
  • Local integration harness (tests/relation_pages_cache/verify.sh, not part of the patch): stress with 15,000 keys to force clock eviction, SET TABLESPACE in both directions across connections, single-attachment SET TABLESPACE round-trip (PRIMARY → TS → DELETE/UPDATE → PRIMARY) and single-attachment DROP TABLE + CREATE TABLE reusing the relation ID, GTT instance recycling (20 × 2,000 rows), and two attachments with 2,000 GTT rows each — no cross-instance cache hits.
  • LTT ALTER TABLE scenario (rows 2 → 3 → 4) to confirm temporary base page sets and frame-scoped instances are still resolved correctly.

Files

  • src/jrd/DataPageNumberCache.h — new cache (PageSetId, embedded m_items, clock eviction, hash, invalidateDPNumber / invalidateDPNumbers)
  • src/jrd/Attachment.h — att_dp_number_cache + lazy accessor
  • src/jrd/Relation.h — atomic monotonic m_pageSetId, accessor and invalidation wrappers, tdbb threaded into reset() / free() / reuse(), old 64-entry map removed
  • src/jrd/Relation.cpp — pass tdbb to free() and reuse()
  • src/jrd/dpm.epp — pass tdbb to getDPNumber / setDPNumber / invalidateDPNumber / reset(), invalidate on !pageOk
  • src/dsql/DdlNodes.epp — pass tdbb to newPages->reset(...)
  • src/jrd/tests/DataPageNumberCacheTest.cpp — new unit tests
  • builds/win32/msvc15/engine_static.vcxproj{,.filters} — new header
  • builds/win32/msvc15/engine_test.vcxproj{,.filters} — new unit test

Unit tests

Seven cases in DataPageNumberCacheSuite (libEngine14_test), all driving a real RelationPages against a fresh pool:

Key identity

  • KeyIncludesPageSet — different RelationPages objects (different page spaces, two distinct objects created for the same DB_PAGE_SPACE, and an instance page set) get distinct keys and do not collide; an unknown sequence misses.

Identity changes / invalidation

  • ReuseChangesIdentity — reset(nullptr), reset(nullptr, 99) back to the same page space, reuse(nullptr, 99, 7), reset(nullptr) while instanceId != 0, and reuse(nullptr, 99, 7) with identical arguments each make previously cached entries unreachable.
  • SetInstanceIdPreservesIdentity — setInstanceId() (GTT retained across a retaining commit) preserves the page-set key so cached data page numbers stay valid.

Eviction policy

  • CapacityAndClockEviction — inserting 2 × CAPACITY keys keeps the most recent 100 and proves the first entry was evicted.
  • ClockEvictsOneAtATime — a full cache plus one insert evicts exactly one entry, not a batch.
  • ClockSecondChance — after the sweep clears all reference bits, a recently read entry survives the next eviction while the following cold entry is replaced.

Update & removal

  • RemoveAndReuse — setDPNumber overwrites an existing entry in place; invalidateDPNumber drops a single sequence and returns its slot for reuse; invalidateDPNumbers drops all sequences of one page set while preserving entries of other page sets.

Replace the mutex-guarded 64-entry SortedArray in every RelationPages
with a single 1024-entry hash + CLOCK cache owned by the attachment.

Each RelationPages incarnation gets a process-wide monotonic 64-bit
PageSetId (regenerated on reset and reuse, preserved across retaining
commits), preventing stale-key collisions when relation, tablespace or
LTT IDs are reused. Cached entries are explicitly purged from the
current attachment's cache on page deletion, validation failure, and
page-set reset/reuse.
@dyemanov
dyemanov requested a review from hvlad November 21, 2026 10:40

@hvlad hvlad 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.

I found no explicit problems with the code, please consider few notes that I've made.
Results looks good!

Comment thread src/jrd/DataPageNumberCache.h Resolved
Comment thread src/jrd/DataPageNumberCache.h Resolved
Comment thread src/jrd/DataPageNumberCache.h Resolved
@aafemt

aafemt commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

Is it necessary to have in the key all three relation id, pagespace id and sequence if sequence belongs only to temporary pages while pagespace id only to persistent tables?

@hvlad

hvlad commented Nov 21, 2026

Copy link
Copy Markdown
Member

Is it necessary to have in the key all three relation id, pagespace id and sequence if sequence belongs only to temporary pages while pagespace id only to persistent tables?

The sequence is a logical number of data page in relation. Looks like you completely missed the goal of this feature - cache part of mapping of logical to physical data page numbers to save access of PP.

@dyemanov

Copy link
Copy Markdown
Member Author

Is it necessary to have in the key all three relation id, pagespace id and sequence if sequence belongs only to temporary pages while pagespace id only to persistent tables?

Sequence belongs to the every table. As for pagespace ID (persistent tables) vs instance ID (temporary tables) -- they can be dense-packed and it was considered (see options with the "tagged id"), but rejected as unsafe in the border cases. And it's a bit slower than the final key design anyway.

@aafemt

aafemt commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

The sequence is a logical number of data page in relation.

Why it isn't called "pageNumber" then...?

@dyemanov

Copy link
Copy Markdown
Member Author

The sequence is a logical number of data page in relation.

Why it isn't called "pageNumber" then...?

Because pageNumber is a physical number.

@aafemt

aafemt commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

Because pageNumber is a physical number.

Modern IDEs let us have logicalPageNumber and physicalPageNumer without hurting of fingers.

@hvlad

hvlad commented Nov 21, 2026

Copy link
Copy Markdown
Member

Spam again, nothing new

@aafemt

aafemt commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

Sure, readability of code is an old thing that always was ignored by the team.

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.

3 participants