diff options
Diffstat (limited to '')
| -rw-r--r-- | include/CursorManager.h | 26 | ||||
| -rw-r--r-- | include/LifecycleManager.h | 1 | ||||
| -rw-r--r-- | include/NamespaceReferenceManager.h | 20 | ||||
| -rw-r--r-- | include/VM.h | 46 | ||||
| -rw-r--r-- | include/WAM.h | 10 |
5 files changed, 93 insertions, 10 deletions
diff --git a/include/CursorManager.h b/include/CursorManager.h index 33230ab..61fba87 100644 --- a/include/CursorManager.h +++ b/include/CursorManager.h @@ -4,6 +4,32 @@ namespace nt { + /** + * @class CursorManager + * @brief Orchestrates data pagination from storage backends to the query executor. + * + * The Cursor Manager implements the glue between the 'registry' objects + * and the Volcano-style iterator model. It translates high-level plan + * requests into low-level backend operations (LMDB, etcd, etc.). + * + * DUTIES: + * 1. Snapshot Anchoring & Pins: + * We need to bind the retrieval to a multigroup snapshot, the object + * for it should hold the reference for the tree that holds all the relations and tuples. + * + * 2. State Maintenance: + * Tracks the current position (Iterators/Offsets) within a relation + * to support sequential Next() calls from the algebra engine. + * + * 3. Prefetching & Buffering: + * Abstracts the 'paging' logic of the backend. For remote backends + * like etcd, it manages local buffers to hide latency from the executor. + * Think of a driver for an operating system. + * + * 4. Boundary Enforcement: + * Ensures scans do not cross commit boundaries or logical branch + * definitions unless explicitly requested by the plan. + */ class NT_API CursorManager { }; diff --git a/include/LifecycleManager.h b/include/LifecycleManager.h index 2cd270d..8bf1a2c 100644 --- a/include/LifecycleManager.h +++ b/include/LifecycleManager.h @@ -10,6 +10,7 @@ namespace nt public: // If object is not being monitored already, monitors the lifecycle by updating the handle count. // Maybe also look at the reference count and kill some categories of disposable objects no longer referenced by other objects, like transactions. + // One use case is preventing compaction/prunning of history while cursors depend on old database snapshots, for example. // Think of other use cases later. void Monitor(ObjectManager::registry* object); // Serializes contention for the change of a mutable reference. diff --git a/include/NamespaceReferenceManager.h b/include/NamespaceReferenceManager.h index 922a0ca..d5c3897 100644 --- a/include/NamespaceReferenceManager.h +++ b/include/NamespaceReferenceManager.h @@ -4,6 +4,26 @@ namespace nt { + /** + * @class NamespaceReferenceManager + * + * @brief Handles the logical mapping and isolation of human-readable references. + * + * DESIGN NOTES: + * 1. Namespace Isolation: + * Allows for private branch shadowing (e.g., /user_a/refs/branch/abc). + * To maintain lookup clarity, protocol-level syntax must explicitly define + * the scope to prevent non-deterministic shadowing during resolution. + * + * 2. Multi-Ref Atomic Updates: + * Ensures that updates to multiple references (e.g., pushing to 'master' + * and 'audit_log' simultaneously) are all-or-nothing. If any single + * contention check fails, the entire batch is aborted to prevent + * partial commits and maintain consistent audit trails. Considering we + * want to have a global access to audit, we would need to be dissociated + * from the scope of a branch, and branches are the only points of contention + * for references, so it made sense to me to think of audit as an independent branch too. + */ class NT_API NamespaceReferenceManager { }; diff --git a/include/VM.h b/include/VM.h new file mode 100644 index 0000000..74ab982 --- /dev/null +++ b/include/VM.h @@ -0,0 +1,46 @@ +#pragma once + +#include "Api.h" + +namespace nt +{ + /** + * @class VM + * @brief The first-order logic (FOL) and second-order logic (SOL) dual cores + * + * This partitioning is here to ensure termination on retrieval with FOL. + * 1. Tarski Runtime (FOL): + * A relational engine that implements Tarski's relational calculus. + * It uses a deterministic Volcano-iterator model to perform relational algebra operations + * (Joins, Projections, Selects, etc) directly against the Cursor Manager and a prepared plan. + * + * 2. Karuta Runtime (SOL): + * An isolated WAM-based environment for higher-order logic programming. It + * handles recursion, choice points, and other complex programming constructs + * that do not guarantee termination. + * + * @remark Lazy Evaluation & Paging Strategy + * + * Both the Tarski (First-Order) and Karuta (Second-Order) engines are + * strictly pull-based. Data is streamed lazily from the Cursor Manager + * to ensure a constant memory footprint regardless of relation size. + * + * PIPELINE DYNAMICS: + * 1. Demand-Driven: + * The Karuta WAM only requests a fact when a goal needs satisfaction. + * A request propagates down the algebra tree as a chain of Next() calls. + * + * 2. Short-Circuiting: + * If the Karuta engine finds a solution or hits a failure that + * invalidates a branch, the Tarski iterator is discarded or reset + * without ever having materialized the remaining tuples. + * + * 3. Resource Stewardship: + * By maintaining laziness up to the highest logical level, we + * minimize pressure on the ObjectManager and keep snapshots pinned + * (via Monitor) only for the absolute minimum time required. + */ + class NT_API WAM + { + }; +} diff --git a/include/WAM.h b/include/WAM.h deleted file mode 100644 index 8f0cb11..0000000 --- a/include/WAM.h +++ /dev/null @@ -1,10 +0,0 @@ -#pragma once - -#include "Api.h" - -namespace nt -{ - class NT_API WAM - { - }; -} |