nt::CursorManager Class Reference

Orchestrates paginated data retrieval from a storage backend. More...

#include <CursorManager.h>

Classes
struct	cursor
	Active scan state for a single relation. More...

Public Member Functions
	CursorManager (IStorageBackend &backend, LifecycleManager *lifecycles=nullptr, ObjectManager *objects=nullptr)
	Constructs a CursorManager.
cursor *	Open (HandlerManager::handle *handle, const std::string &merkle_root="")
	Opens a cursor on the relation referenced by the handle.
Tuple *	Next (cursor *cursor)
	Pulls the next tuple from the cursor.
void	Close (cursor *cursor)
	Closes the cursor and releases its resources.

Static Public Attributes
static constexpr std::size_t	PAGE_SIZE = 1

Detailed Description

Orchestrates paginated data retrieval from a storage backend.

CursorManager depends only on IStorageBackend. The concrete backend (SqliteBackend, InMemoryBackend, …) is injected at construction time.

Tuples are never loaded all at once. Open() fetches the first page; each subsequent Next() call transparently fetches the next page from the backend once the current page is exhausted.

Pagination is driven by the Merkle B-tree: each cursor carries the hex hash of the relation's Merkle root at open time, and LoadPage calls Merkle::Page(backend, merkle_root, fetch_offset, PAGE_SIZE) to retrieve the next page of tuple hashes without loading sibling subtrees.

Constructor & Destructor Documentation

CursorManager()

nt::CursorManager::CursorManager ( IStorageBackend & backend, LifecycleManager * lifecycles = nullptr, ObjectManager * objects = nullptr )

explicit

Constructs a CursorManager.

The lifecycles and objects references are optional: when left null the cursor performs no snapshot pinning (this matches the test fixtures, which register relations at synthetic paths with no /system/snapshots ancestor). When both are provided, Open finds the resolved snapshot for the handle's relation and Pins it for the cursor's lifetime, releasing the pin in Close.

Member Function Documentation

Close()

void nt::CursorManager::Close

(

cursor *

cursor

)

Closes the cursor and releases its resources.

Parameters

cursor

Cursor to close.

Next()

Tuple * nt::CursorManager::Next

(

cursor *

cursor

)

Pulls the next tuple from the cursor.

Fetches the next page from the backend transparently when the current page is exhausted. Returns nullptr when all pages are done.

Open()

CursorManager::cursor * nt::CursorManager::Open	(	HandlerManager::handle *	handle,
		const std::string &	merkle_root = "" )

Opens a cursor on the relation referenced by the handle.

Fetches the first page immediately for non-empty relations. Returns a valid exhausted cursor when merkle_root is empty (empty relation). Returns nullptr when the handle does not refer to a RELATION or EPHEMERAL_RELATION.

Parameters

handle	Open RELATION or EPHEMERAL_RELATION handle.
merkle_root	Hex hash of the relation's Merkle root at open time. Ignored for EPHEMERAL_RELATION handles.

---

The documentation for this class was generated from the following files:

• CursorManager.h
• CursorManager.cpp