diff options
Diffstat (limited to 'include/CursorManager.h')
| -rw-r--r-- | include/CursorManager.h | 153 |
1 files changed, 0 insertions, 153 deletions
diff --git a/include/CursorManager.h b/include/CursorManager.h deleted file mode 100644 index a4c82d7..0000000 --- a/include/CursorManager.h +++ /dev/null @@ -1,153 +0,0 @@ -#pragma once - -#include "Api.h" -#include "HandlerManager.h" -#include "IStorageBackend.h" -#include "LifecycleManager.h" -#include "ObjectManager.h" -#include "Types.h" - -#include <cstddef> -#include <string> -#include <vector> - -/** - * @file CursorManager.h - * @brief Declares paging and cursor orchestration for query execution. - */ - -namespace nt { - /** - * @class CursorManager - * @brief 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. - */ - class CursorManager { - public: - static constexpr std::size_t PAGE_SIZE = 1; - - /** - * @brief Constructs a CursorManager. - * - * The @p lifecycles and @p 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. - */ - explicit CursorManager(IStorageBackend& backend, LifecycleManager* lifecycles = nullptr, - ObjectManager* objects = nullptr); - - /** - * @brief Active scan state for a single relation. - * - * Holds one page of deserialized tuples at a time. When page_position - * reaches the end of the page, Next() discards the page and fetches - * the next one from the backend. - * - * The pointer returned by Next() is valid only until the next Next() - * or Close() call — a page replacement invalidates all prior pointers. - * - * merkle_root is seeded from ObjectManager::Relation::merkle_root at - * open time and does not change during iteration; the cursor reads the - * snapshot captured when it was opened. - * - * Notably the cursor does NOT keep a pointer to the HandlerManager - * handle it was opened from. Everything Next() needs — the relation - * type, the merkle_root, and the ephemeral generator function — is - * captured at Open time, so closing the handle before the cursor is - * exhausted is safe (the API contract still says to close the cursor - * first, but a violation no longer dereferences a freed handle). - */ - struct cursor { - /** - * Hex hash of the relation's Merkle B-tree root node. - * Empty string means the relation contains no tuples. - */ - std::string merkle_root; - /** - * Bound argument values for EPHEMERAL_RELATION cursors. - * Written by the JOIN operator before each probe; ignored for - * stored RELATION cursors. - */ - std::vector<std::string> args; - std::vector<Tuple> page; - std::size_t page_position = 0; - std::size_t fetch_offset = 0; // next Merkle::Page() call starts here - bool exhausted = false; - /** - * True for EPHEMERAL_RELATION cursors; selects the generator-driven - * page fetch path instead of Merkle B-tree paging. - */ - bool is_ephemeral = false; - /** - * Generator function for ephemeral cursors. Copied from the - * ephemeral_object_type at Open time, so the cursor remains valid - * even if the source registry entry is later torn down (the - * snapshot pin held in pinned_snapshot prevents that today, but - * the copy makes the cursor independent regardless). - */ - ObjectManager::ephemeral_object_type::Generator generator; - /** - * Borrowed pointer to the snapshot the cursor is pinning. - * Non-null only when a /system/snapshots/<H>/<n> - * ancestor was found at Open time and LifecycleManager was - * available. Close unpins it. - */ - ObjectManager::registry* pinned_snapshot = nullptr; - }; - - /** - * @brief 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 @p merkle_root is empty (empty relation). - * Returns nullptr when the handle does not refer to a RELATION or - * EPHEMERAL_RELATION. - * - * @param handle Open RELATION or EPHEMERAL_RELATION handle. - * @param merkle_root Hex hash of the relation's Merkle root at open - * time. Ignored for EPHEMERAL_RELATION handles. - */ - cursor* Open(HandlerManager::handle* handle, const std::string& merkle_root = ""); - - /** - * @brief 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. - */ - Tuple* Next(cursor* cursor); - - /** - * @brief Closes the cursor and releases its resources. - * @param cursor Cursor to close. - */ - void Close(cursor* cursor); - - private: - IStorageBackend& backend_; - LifecycleManager* lifecycles_ = nullptr; - ObjectManager* objects_ = nullptr; - - /** - * Fetches a page of hashes via Merkle::Page, resolves each from the - * KV store, and deserializes them into cursor->page. Clears the - * existing page. Advances fetch_offset by the number of hashes - * returned; sets exhausted when fewer than PAGE_SIZE hashes come back. - */ - void LoadPage(cursor* c); - }; -} // namespace nt |