Module `Granary_storage.Pager`Source

Pager: page cache + allocator over a BLOCK backend.

Sourcetype cache_key = int64 * int

Sourcetype wal_callbacks = {

wal_find_page : int64 -> int option;
wal_find_page_at : int64 -> max_frame:int -> int option;
wal_read_frame : int -> (Cstruct.t, string) result Lwt.t;
wal_append_commit : (int64 * Cstruct.t) list -> (unit, string) result Lwt.t;
wal_append_commit_no_sync : (int64 * Cstruct.t) list -> (unit, string) result Lwt.t;
wal_sync : unit -> (unit, string) result Lwt.t;

}

Sourcetype t

Sourcetype error =

| Block_error of string
| Corruption of string

Sourcetype dirty_snapshot = (int64, Cstruct.t) Hashtbl.t

Sourceval pp_error : Format.formatter -> error -> unit

Pretty-print a pager error.

Sourceval pp : Format.formatter -> t -> unit

Pretty-print the pager state (n_pages, cache/dirty sizes, txn_id).

Source

val create : 
  read_page:(page_id:int64 -> Cstruct.t -> (unit, string) result Lwt.t) ->
  write_page:(page_id:int64 -> Cstruct.t -> (unit, string) result Lwt.t) ->
  sync:(unit -> (unit, string) result Lwt.t) ->
  resize:(n_pages:int64 -> (unit, string) result Lwt.t) ->
  n_pages:int64 ->
  freelist:Freelist.t ->
  t

Create a pager over BLOCK callbacks with the given initial page count and freelist.

Sourceval set_write_tag : t -> int32 -> unit

Set the schema-fingerprint stamp for subsequently-built Btree pages (#174).

Sourceval write_tag : t -> int32

Current schema-fingerprint stamp (#174).

Sourceval set_page_event_callback : t -> (Pager_event.t -> unit) option -> unit

#384: attach/detach a synchronous observer for physical page I/O events (internals monitor). None (the default) is zero-overhead. The observer must be cheap and non-blocking; exceptions it raises are NOT caught here — Store.set_event_callback wraps the store-level observer to swallow them.

Sourceval set_geom : t -> Geometry.t -> unit

Set the file's page geometry (called once on open, before any page op).

Sourceval geom : t -> Geometry.t

Current page geometry.

Sourceval page_size : t -> int

Page size in bytes.

Sourceval reserved_bytes : t -> int

Reserved bytes per page (#174 schema fingerprint).

Sourceval max_data_bytes : t -> int

Maximum bytes of user data per page.

Sourceval max_overflow_payload_bytes : t -> int

Maximum payload bytes for an overflow page.

Sourceval max_freelist_entries_per_page : t -> int

Maximum freelist entries that fit on one page.

Sourceval set_wal : t -> wal_callbacks option -> unit

Attach or detach the WAL overlay. Clears cache on transition into WAL mode.

Sourceval wal_mode : t -> bool

True when a WAL overlay is attached.

Source

val read : 
  ?snapshot_frames:int ->
  ?pin_set:(int64, unit) Hashtbl.t ->
  ?bypass_cache:bool ->
  t ->
  int64 ->
  (Cstruct.t, error) result Lwt.t

Read page_id, consulting dirty (writer path) or the WAL snapshot. When ~bypass_cache:true, the page is read from the block device but NOT inserted into the shared FIFO cache. Intended for single-use pages such as BLOB overflow chains where caching would evict hot B-tree pages without benefit. On a cache hit the cached buffer is still returned even when bypass_cache is set; only insertion-on-miss is suppressed.

Source

val read_borrow : 
  ?snapshot_frames:int ->
  ?pin_set:(int64, unit) Hashtbl.t ->
  ?bypass_cache:bool ->
  t ->
  int64 ->
  (Cstruct.t -> 'a Lwt.t) ->
  ('a, error) result Lwt.t

Zero-copy borrow-read: the callback receives the page buffer directly. When ~bypass_cache:true, the page is read from the block device but NOT inserted into the shared FIFO cache. See read for details.

Sourceval write : t -> int64 -> Cstruct.t -> unit

Write buf to page_id (defensive copy).

Sourceval write_owned : t -> int64 -> Cstruct.t -> unit

Write buf to page_id (takes ownership, no defensive copy).

Sourceval dirty_buffer : t -> int64 -> Cstruct.t option

#356: the LIVE dirty buffer for page_id (NOT a copy), or None if the page is not dirty in the current write txn. A dirty page was allocated or CoW-copied by this txn, so no committed snapshot or concurrent reader references it — the caller may mutate it in place. Mutations must keep the page well-formed; the CRC reseals at flush time.

Sourceval alloc : t -> (int64, error) result Lwt.t

Allocate a page: txn-owned pool, then main freelist, then file extension.

Sourceval free : t -> page_id:int64 -> freed_at_txn_id:int64 -> unit

Free page_id stamped with freed_at_txn_id; txn-owned pages route to the pool.

Sourceval flush : t -> (unit, error) result Lwt.t

Flush all dirty pages to the WAL with an fsync.

Sourceval flush_no_sync : t -> (unit, error) result Lwt.t

Flush all dirty pages to the WAL without an fsync.

Sourceval flush_sync_main : t -> (unit, error) result Lwt.t

Flush dirty pages directly to the main BLOCK device with an fsync.

Source

val flush_one_to_main : 
  t ->
  page_id:int64 ->
  buf:Cstruct.t ->
  (unit, error) result Lwt.t

Flush a single page to the main BLOCK device.

Sourceval n_pages : t -> int64

Current page count (may grow via alloc, shrink via set_n_pages).

Sourceval freelist : t -> Freelist.t

Current freelist state.

Sourceval set_txn_id : t -> int64 -> unit

Set the current RW transaction ID.

Sourceval get_txn_id : t -> int64

Current RW transaction ID (0 when no RW txn is active).

Sourceval set_alloc_min_safe : t -> int64 -> unit

Set the minimum safe txn ID for freelist reuse (gated by active readers).

Sourceval pinned_count : t -> int

Number of distinct pages pinned by live RO snapshots (#159).

Sourceval set_freelist : t -> Freelist.t -> unit

Replace the entire freelist (used by rollback and checkpoint).

Sourceval set_n_pages : t -> int64 -> unit

Override n_pages (used by savepoint rollback to truncate the file).

Sourceval clear_dirty : t -> unit

Discard all dirty pages and rollback state (#297 pool included).

Sourceval dirty_clone : t -> dirty_snapshot

Snapshot the dirty set (for savepoints).

Sourceval dirty_restore : t -> dirty_snapshot -> unit

Restore a dirty set snapshot (for savepoints).

Sourceval unpin_all : t -> (int64, unit) Hashtbl.t -> unit

Release every pin held by an RO snapshot (#159).

Sourceval wal_sync : t -> (unit, error) result Lwt.t

Forward-sync the WAL (fsync the WAL file).

Sourceval set_n_pages_at_rw_begin : t -> int64 -> unit

Set the page count threshold at rw_begin; pages >= this are txn-owned.

Sourceval txn_owned_pool_get : t -> int64 list

Current txn-owned page pool (freed pages available for reuse).

Sourceval txn_owned_pool_set : t -> int64 list -> unit

Replace the txn-owned page pool (used by commit and rollback).

Install

dune-project
Dependency

Authors

Maintainers

Sources

doc/granary.storage/Granary_storage/Pager/index.html

Module `Granary_storage.Pager`Source

package granary

Install

dune-project Dependency

Authors

Maintainers

Sources

doc/granary.storage/Granary_storage/Pager/index.html

Module Granary_storage.PagerSource

dune-project
Dependency

Module `Granary_storage.Pager`Source