Module bitmap_scan 

Bitmap heap scan — Fase 5 P6 consumer of TidBitmap.

Implements the second half of the PG bitmap-index-scan pipeline: given a TidBitmap produced by AND/OR-ing per-index bitmaps, walk the target heap pages in sorted order and fetch the rows corresponding to set bits.

The win over a plain index scan is sequential page access: bitmap entries are sorted by TID, so successive fetches go to adjacent pages, giving the OS and buffer pool a prefetch-friendly stream instead of random seeks. For queries touching >1% of a large table the difference is 5-20× on spinning disks and ~2-3× on SSDs.

Mirrors PG’s nodeBitmapHeapscan.c modulo features we don’t have:

• Lossy bitmap entries: PG’s tidbitmap can spill to page-level granularity when memory pressure mounts. TidBitmap doesn’t, so the bitmap heap scan here always processes tuple-level entries.
• Prefetch hints: PG calls PrefetchBuffer for the next few pages while the current page is being processed. We rely on the OS readahead for now.
• Parallel bitmap heap scans: single-producer for now.

This module is not yet wired into the canonical plan. A BitmapHeapScan logical plan node and its executor arm plug into query_exec/table.rs when the planner learns to emit bitmap paths.

Structs

BitmapScanStats

Summary statistics the bitmap scan returns alongside its output. Useful for EXPLAIN ANALYZE-style diagnostics and for the planner’s feedback loop when adjusting cost estimates based on actual selectivity.

Enums

BitmapCombine

Boolean combinator passed into execute_combined_bitmap_scan.

Traits

RowFetcher

Callback the bitmap scan uses to fetch a row by its TID. The caller (typically the runtime executor) provides this when invoking the scan because the row shape depends on the target collection.

Functions

execute_bitmap_scan

Execute a bitmap heap scan over bitmap, invoking fetcher for each surviving TID in sorted order. Returns the materialised rows in the same TID order.

execute_bitmap_scan_with_stats

Variant of execute_bitmap_scan that also fills a BitmapScanStats struct alongside the row output. Used by EXPLAIN ANALYZE paths and by the runtime’s cardinality feedback loop.

execute_combined_bitmap_scan

Phase 3.6 wiring entry point. Combines a list of per-index bitmaps via the requested boolean op and runs a single heap fetch over the result. The planner uses this when WHERE has multi-index AND/OR predicates.