diff options
| -rw-r--r-- | .github/workflows/docs.yml | 45 | ||||
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | Doxyfile | 28 | ||||
| -rw-r--r-- | README.org | 29 | ||||
| -rw-r--r-- | RelationalNT.vcxproj | 4 | ||||
| -rw-r--r-- | RelationalNT.vcxproj.filters | 6 | ||||
| -rw-r--r-- | docs/mainpage.dox | 56 | ||||
| -rw-r--r-- | include/Api.h | 5 | ||||
| -rw-r--r-- | include/CursorManager.h | 39 | ||||
| -rw-r--r-- | include/HandlerManager.h | 38 | ||||
| -rw-r--r-- | include/IdentityManager.h | 18 | ||||
| -rw-r--r-- | include/LifecycleManager.h | 61 | ||||
| -rw-r--r-- | include/NT.h | 7 | ||||
| -rw-r--r-- | include/NamespaceReferenceManager.h | 32 | ||||
| -rw-r--r-- | include/ObjectManager.h | 47 | ||||
| -rw-r--r-- | include/PermissionsManager.h | 34 | ||||
| -rw-r--r-- | include/Runtime.h | 12 | ||||
| -rw-r--r-- | include/Types.h | 24 | ||||
| -rw-r--r-- | include/VM.h | 75 | ||||
| -rw-r--r-- | src/HandlerManager.cpp | 7 |
20 files changed, 463 insertions, 105 deletions
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..09486ca --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,45 @@ +name: Documentation + +on: + push: + branches: + - master + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install Doxygen + run: sudo apt-get update && sudo apt-get install -y doxygen graphviz + + - name: Generate documentation + run: doxygen Doxyfile + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/generated/html + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 @@ -31,3 +31,4 @@ RNT.exp RNT.lib libRNT.so libRNT.dylib +docs/generated/ diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..c29388d --- /dev/null +++ b/Doxyfile @@ -0,0 +1,28 @@ +PROJECT_NAME = "Relational NT" +PROJECT_BRIEF = "A relational database kernel shaped around NT-style object management." +OUTPUT_DIRECTORY = docs/generated +INPUT = docs/mainpage.dox include src +RECURSIVE = YES +FILE_PATTERNS = *.h *.cpp *.dox +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_AS_ERROR = NO +GENERATE_HTML = YES +HTML_OUTPUT = html +GENERATE_LATEX = NO +GENERATE_XML = NO +USE_MDFILE_AS_MAINPAGE = +JAVADOC_AUTOBRIEF = YES +QT_AUTOBRIEF = NO +QUIET = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = . +EXCLUDE_PATTERNS = */docs/generated/* +IMAGE_PATH = images @@ -5,20 +5,21 @@ * About -This is a Relational NT-inspired database kernel. The goal of the project is to offer an approach similar to how the NT kernel offers for an OS, but for administrating database objects and state. +Relational NT is an experimental database kernel inspired by the object-management model of the Windows NT kernel. The project explores what database internals look like when relations, tuples, transactions, namespaces, permissions, cursors, and handles are treated as explicit runtime-managed objects. -Relational NT explores database internals through an object-manager style architecture. Instead of treating relations, tuples, transactions, namespaces, permissions, and handles as unrelated mechanisms, the runtime models them as managed objects with explicit lifecycle, uniform access paths and explicit security enforcement. +The goal is to build a small, understandable runtime where database state is accessed through uniform paths, guarded by explicit security checks, and managed through visible lifecycle rules. The codebase is still early, so several classes define architectural boundaries before they define complete behavior. * Design Direction -- Object management: database objects are registered, located, and referenced through a central object manager. -- Permissions: access checks are separated from object lookup so security policy can evolve independently. -- Identity and lifecycle: opening, closing, monitoring, and contention decisions are represented as runtime responsibilities. -- Handles: authorized access to objects is modeled explicitly, making ownership and cleanup visible. +- Object management: database objects are registered, located, and referenced through a central registry. +- Permissions: access checks are kept separate from object lookup so security policy can evolve independently. +- Identity and lifecycle: opening, closing, monitoring, pinning, cleanup, and contention are modeled as runtime responsibilities. +- Handles: authorized access is explicit, which makes ownership, accounting, and cleanup visible. +- Cursors and VM: retrieval is designed around pull-based cursors and a split between terminating first-order logic and higher-order logic execution. * Current Status -The project is early-stage and focused on shaping the runtime structure. Many components are intentionally skeletal while the core abstractions settle. +The project is currently focused on the runtime shape. Many components are intentionally skeletal while the core abstractions settle, but the headers document the intended responsibilities and constraints of each manager. * Building @@ -33,3 +34,17 @@ For Unix-like environments with a C++17 compiler and Make installed: #+begin_src shell make unix #+end_src + +* Documentation + +API documentation is generated with Doxygen. The root =Doxyfile= reads the public headers, source files, and the documentation main page in =docs/mainpage.dox=. + +#+begin_src shell +doxygen Doxyfile +#+end_src + +Generated HTML is written to =docs/generated/html=. + +The comments in the public headers are part of the design record. Keep architectural notes close to the declarations they explain so Doxygen can publish them with the API reference. + +The repository also includes a GitHub Actions workflow that publishes the generated Doxygen HTML to GitHub Pages on pushes to =master=. In the repository settings, configure Pages to use =GitHub Actions= as its source. diff --git a/RelationalNT.vcxproj b/RelationalNT.vcxproj index 2586587..b2d68f1 100644 --- a/RelationalNT.vcxproj +++ b/RelationalNT.vcxproj @@ -103,9 +103,11 @@ <ClInclude Include="include\VM.h" /> </ItemGroup> <ItemGroup> + <None Include="Doxyfile" /> + <None Include="docs\mainpage.dox" /> <None Include="Makefile" /> </ItemGroup> <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" /> <ImportGroup Label="ExtensionTargets"> </ImportGroup> -</Project>
\ No newline at end of file +</Project> diff --git a/RelationalNT.vcxproj.filters b/RelationalNT.vcxproj.filters index 29a22eb..ec1b7ae 100644 --- a/RelationalNT.vcxproj.filters +++ b/RelationalNT.vcxproj.filters @@ -81,6 +81,12 @@ </ClInclude> </ItemGroup> <ItemGroup> + <None Include="Doxyfile"> + <Filter>Build Files</Filter> + </None> + <None Include="docs\mainpage.dox"> + <Filter>Build Files</Filter> + </None> <None Include="Makefile"> <Filter>Build Files</Filter> </None> diff --git a/docs/mainpage.dox b/docs/mainpage.dox new file mode 100644 index 0000000..0013b0b --- /dev/null +++ b/docs/mainpage.dox @@ -0,0 +1,56 @@ +/** + * @mainpage Relational NT + * + * @image html logo.png + * + * Relational NT is an experimental database kernel inspired by the + * object-management model of the Windows NT kernel. The project applies the + * same style of explicit object management to database state: relations, + * tuples, transactions, namespaces, permissions, cursors, and handles are + * treated as runtime-managed objects rather than isolated subsystems. + * + * The current codebase is intentionally early-stage. Most classes define the + * boundaries of the runtime and document the design constraints that should + * guide future implementation. + * + * @section architecture Architecture Direction + * + * - ObjectManager registers, locates, and references database objects. + * - PermissionsManager keeps security checks separate from object lookup. + * - IdentityManager decides whether an object supports lifecycle operations + * such as open and close. + * - LifecycleManager models monitoring, pinning, cleanup, and contention. + * - HandlerManager represents authorized access through explicit handles. + * - CursorManager bridges durable snapshots and pull-based query execution. + * - VM separates terminating relational retrieval from higher-order logic + * execution. + * + * @section building Building + * + * From a Visual Studio/NMake environment: + * + * @code{.sh} + * nmake /f Makefile windows + * @endcode + * + * From a Unix-like environment with Make and a C++17 compiler: + * + * @code{.sh} + * make unix + * @endcode + * + * @section docs Generating Documentation + * + * Install Doxygen and run: + * + * @code{.sh} + * doxygen Doxyfile + * @endcode + * + * The generated HTML documentation is written to docs/generated/html. + */ + +/** + * @namespace nt + * @brief Contains the Relational NT runtime managers and API facade. + */ diff --git a/include/Api.h b/include/Api.h index d47636d..33a7f6d 100644 --- a/include/Api.h +++ b/include/Api.h @@ -1,5 +1,10 @@ #pragma once +/** + * @file Api.h + * @brief Defines symbol visibility for the Relational NT public API. + */ + #if defined(_WIN32) && defined(NT_CONSOLE_APP) #define NT_API #elif defined(_WIN32) && defined(NT_EXPORTS) diff --git a/include/CursorManager.h b/include/CursorManager.h index 61fba87..7e1ebe0 100644 --- a/include/CursorManager.h +++ b/include/CursorManager.h @@ -2,33 +2,36 @@ #include "Api.h" +/** + * @file CursorManager.h + * @brief Declares paging and cursor orchestration for query execution. + */ + 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.). + * The cursor manager is the glue between registry objects and the + * Volcano-style iterator model. It translates high-level plan requests into + * low-level backend operations such as LMDB or etcd reads. * - * 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. + * Responsibilities: + * - Snapshot anchoring and pins: bind retrieval to a multigroup snapshot. + * The snapshot object should hold the reference to the tree containing + * all relations and tuples. * - * 2. State Maintenance: - * Tracks the current position (Iterators/Offsets) within a relation - * to support sequential Next() calls from the algebra engine. + * - State maintenance: track the current iterator or offset inside 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. + * - Prefetching and buffering: abstract backend paging. For remote + * backends like etcd, manage local buffers to hide latency from the + * executor. Think of this as a database equivalent of an operating-system + * driver. * - * 4. Boundary Enforcement: - * Ensures scans do not cross commit boundaries or logical branch - * definitions unless explicitly requested by the plan. + * - Boundary enforcement: ensure scans do not cross commit boundaries or + * logical branch definitions unless explicitly requested by the plan. */ class NT_API CursorManager { diff --git a/include/HandlerManager.h b/include/HandlerManager.h index d126680..185cc55 100644 --- a/include/HandlerManager.h +++ b/include/HandlerManager.h @@ -6,20 +6,50 @@ #include <string> #include <vector> +/** + * @file HandlerManager.h + * @brief Declares handle allocation and release for authorized object access. + */ + namespace nt { + /** @brief Opens and closes authorized handles to registry objects. */ class NT_API HandlerManager { public: - // This is supposed to represent an authorized access to a certain object in the registry - // This increases the handle count in the object manager - // We should consider adding on the object manager a vector of all the handles that refer to an object + /** + * @brief Represents authorized access to an object in the registry. + * + * This increases the handle count in the object manager. We should + * consider adding a vector to the object manager with all handles that + * refer to an object. + */ struct handle { + /** Object referenced by this handle. */ ObjectManager::registry* object = nullptr; + /** Connection metadata associated with the authorized access. */ void* connection_context = nullptr; }; + + /** + * @brief Releases a handle allocation. + * @param handle Handle to release. + */ void DeallocateHandle(struct handle* handle); - struct handle Open(std::vector<std::string> object_path, void* connection_context); + + /** + * @brief Opens an object by path for a connection. + * @param object_path Logical object path. + * @param connection_context Connection metadata for the caller. + * @return A valid handle pointer on success, or nullptr on failure. + */ + struct handle* Open(std::vector<std::string> object_path, void* connection_context); + + /** + * @brief Closes a previously opened handle. + * @param handle Handle to close. + * @return True when the handle was closed successfully. + */ bool Close(struct handle* handle); }; } diff --git a/include/IdentityManager.h b/include/IdentityManager.h index 1a03fff..0e2d08f 100644 --- a/include/IdentityManager.h +++ b/include/IdentityManager.h @@ -3,13 +3,29 @@ #include "Api.h" #include "ObjectManager.h" +/** + * @file IdentityManager.h + * @brief Declares object capability checks. + */ + namespace nt { + /** @brief Checks whether an object supports identity-level operations. */ class NT_API IdentityManager { public: - // Looks into the methods of the object type and asserts if it can be opened + /** + * @brief Looks into the methods of the object type and asserts if it can be opened. + * @param object Object to inspect. + * @return True when the object can be opened. + */ const bool CanOpen(ObjectManager::registry* object); + + /** + * @brief Checks whether an object can be closed. + * @param object Object to inspect. + * @return True when the object can be closed. + */ const bool CanClose(ObjectManager::registry* object); }; } diff --git a/include/LifecycleManager.h b/include/LifecycleManager.h index 8bf1a2c..914ce0a 100644 --- a/include/LifecycleManager.h +++ b/include/LifecycleManager.h @@ -3,27 +3,60 @@ #include "Api.h" #include "ObjectManager.h" +/** + * @file LifecycleManager.h + * @brief Declares monitoring, pinning, cleanup, and contention operations. + */ + namespace nt { + /** @brief Manages runtime lifecycle concerns for registry objects. */ class NT_API LifecycleManager { 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. + /** + * @brief Starts monitoring an object's lifecycle. + * + * If the object is not being monitored already, monitor 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/pruning of history while + * cursors depend on old database snapshots, for example. Think of + * other use cases later. + * + * @param object Object to monitor. + */ void Monitor(ObjectManager::registry* object); - // Serializes contention for the change of a mutable reference. - // This can be used in, for example, the HEAD of a branch to serialize the access. - // If the object does not causes contention, like a relation (since they are immutable, just like multigroups, all snapshots) - // then just approve, as they do not cause any contention. Transactions also do not cause any, - // the only things that do are mutable reference states in shared sessions, - // for example: the HEAD of a branch, namespace collisions (creating two branches with the same name, or two multigroups with the same name from the same state, etc), - // multi-branch atomic commits (which I wish to not have as it damages isolation), - // garbage collection of old state (as in, we want to delete an old-enough history to save up space), etc. + + /** + * @brief Serializes contention for changes to mutable references. + * + * This can be used for the HEAD of a branch to serialize access. If the + * object does not cause contention, such as a relation, then this can + * approve the operation because relations and multigroups are immutable + * snapshots. Transactions also do not cause contention. + * + * The objects that do cause contention are mutable reference states in + * shared sessions. Examples include the HEAD of a branch, namespace + * collisions, multi-branch atomic commits (which may damage isolation), + * and garbage collection of old state when old-enough history is removed + * to save space. + * + * @param object Object to check for contention. + * @return True when the operation may proceed. + */ const bool Contention(ObjectManager::registry* object); - // The inverse of `Monitor`, stops monitoring. - // Maybe garbage collect here also if the counters goes to zero. + + /** + * @brief Stops monitoring an object. + * + * The inverse of Monitor. Maybe garbage collect here also if the + * counters go to zero. + * + * @param object Object to stop monitoring. + */ void Unmonitor(ObjectManager::registry* object); }; } diff --git a/include/NT.h b/include/NT.h index a97f6c8..0fc5514 100644 --- a/include/NT.h +++ b/include/NT.h @@ -1,5 +1,10 @@ #pragma once +/** + * @file NT.h + * @brief Includes for the Relational NT public API. + */ + #include "Types.h" #include "ObjectManager.h" #include "PermissionsManager.h" @@ -8,5 +13,5 @@ #include "IdentityManager.h" #include "LifecycleManager.h" #include "HandlerManager.h" -#include "WAM.h" +#include "VM.h" #include "Runtime.h" diff --git a/include/NamespaceReferenceManager.h b/include/NamespaceReferenceManager.h index d5c3897..59068f7 100644 --- a/include/NamespaceReferenceManager.h +++ b/include/NamespaceReferenceManager.h @@ -2,27 +2,31 @@ #include "Api.h" +/** + * @file NamespaceReferenceManager.h + * @brief Declares logical reference mapping and namespace isolation. + */ + 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. + * Design notes: + * - Namespace isolation: allow private branch shadowing, such as + * /user_a/refs/branch/abc. To preserve lookup clarity, protocol-level + * syntax must explicitly define scope and prevent non-deterministic + * shadowing during resolution. + * + * - Multi-reference atomic updates: ensure updates to multiple references, + * such as pushing to master and audit_log simultaneously, are + * all-or-nothing. If any contention check fails, the whole batch is + * aborted to prevent partial commits and preserve audit consistency. * - * 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. + * Audit needs global access, which means it should be dissociated from a + * branch scope. Since branches are the only contention points for + * references, it makes sense to model audit as an independent branch too. */ class NT_API NamespaceReferenceManager { diff --git a/include/ObjectManager.h b/include/ObjectManager.h index 8abf44c..52ba602 100644 --- a/include/ObjectManager.h +++ b/include/ObjectManager.h @@ -8,40 +8,79 @@ #include <string> #include <vector> +/** + * @file ObjectManager.h + * @brief Declares the registry responsible for runtime-managed database objects. + */ + namespace nt { + /** + * @brief Owns the registry used to locate and reference database objects. + * + * The object manager is the central directory for runtime objects. It keeps + * the metadata needed to reason about object type, path, references, and + * handles while the concrete storage model is still being designed. + */ class NT_API ObjectManager { public: + /** @brief Base type for objects stored in the registry. */ class IObject { public: virtual ~IObject() = default; }; + + /** @brief Object representing a multigroup. */ class Multigroup : IObject {}; + /** @brief Object representing a relation. */ class Relation : IObject {}; + /** @brief Object representing a tuple. */ class Tuple : IObject {}; + /** @brief Object representing a transaction. */ class Transaction : IObject {}; + + /** @brief Describes the behavior and capabilities of an object category. */ struct object_type { + /** Object category label. */ OBJECT_TYPE label; - // If the object is not durable. E.g.: TRANSACTION + /** True when the object is not durable. For example: TRANSACTION. */ bool disposable; + /** Methods supported by this object type. */ std::set<METHOD> methods; }; + + /** @brief Shared metadata stored at the head of a registry entry. */ struct registry_head { + /** Number of object-to-object references. */ uint32_t reference_count; + /** Number of open handles. */ uint32_t handle_count; + /** Object type metadata. */ struct object_type* type; + /** Logical object path inside the namespace. */ std::vector<std::string> path; - //security_descriptor to be added later, maybe also a set of labels + /** security_descriptor to be added later, maybe also a set of labels */ }; + + /** @brief Node in the object registry. */ struct registry { + /** Shared metadata for this object. */ struct registry_head* head; + /** Stored object payload. */ IObject object; - // TODO: Treat as a list for now, but ideally it's a tree + /** TODO: Treat as a list for now, but ideally it is a tree. */ struct registry* next; }; + + /** Root registry entries. */ struct registry** entries; - // Looks into this registry and attempts to retrieve the entry + + /** + * @brief Looks into this registry and attempts to retrieve an entry. + * @param object_path Logical path to search for. + * @return Matching registry entry, or nullptr when no object is found. + */ struct registry* Find(const std::vector<std::string> object_path); }; } diff --git a/include/PermissionsManager.h b/include/PermissionsManager.h index c51bd27..6d79642 100644 --- a/include/PermissionsManager.h +++ b/include/PermissionsManager.h @@ -6,14 +6,44 @@ #include <set> +/** + * @file PermissionsManager.h + * @brief Declares authentication and object-access checks. + */ + namespace nt { + /** + * @brief Evaluates connection claims and object permissions. + * + * Permission checks are intentionally separated from lookup. The object + * manager can retrieve a candidate object, while this manager decides + * whether the caller is allowed to use it. + */ class NT_API PermissionsManager { public: - // For validating connections at login + /** + * @brief Validates a connection during login. + * @param method Authentication method used by the connection. + * @return Claims granted to the authenticated connection. + */ std::set<AUTH_CLAIM> Firewall(AUTH_METHOD method); - // For validating permission to an object + + /** + * @brief Validates permission to an object. + * + * Checks the security descriptor on the head of the object found in + * ObjectManager::registry. It should also check connection metadata + * that is still to be defined, such as user group and policy. + * + * It is still undecided whether this should run on every attempt to get + * hold of an object, since that might produce significant overhead. + * + * @param object Object being accessed. + * @param connection_context Connection metadata for the caller. + * @return True when access is allowed. + */ const bool Access(const ObjectManager::registry* object, const void* connection_context); }; } diff --git a/include/Runtime.h b/include/Runtime.h index 60a0b90..aeac136 100644 --- a/include/Runtime.h +++ b/include/Runtime.h @@ -2,12 +2,24 @@ #include "Api.h" +/** + * @file Runtime.h + * @brief Declares the top-level Relational NT runtime facade. + */ + namespace nt { + /** @brief Top-level runtime object used by applications and the console entry point. */ class NT_API NT { public: + /** + * @brief Reports whether the runtime is active. + * @return True when the runtime is running. + */ bool IsRunning() const; + + /** @brief Simulates an external entry call into the runtime. */ void SimulateEntryCall(); }; } diff --git a/include/Types.h b/include/Types.h index fe6afed..9d55765 100644 --- a/include/Types.h +++ b/include/Types.h @@ -1,26 +1,48 @@ #pragma once +/** + * @file Types.h + * @brief Shared enum types used by the runtime managers. + */ + +/** @brief Runtime object categories known by the object manager. */ enum OBJECT_TYPE { + /** A database snapshot grouping relations and tuples. */ MULTIGROUP, + /** A relation object. */ RELATION, + /** A tuple object. */ TUPLE, + /** An attribute object. */ ATTRIBUTE, + /** A transaction object. */ TRANSACTION }; +/** @brief Operations that may be supported by an object type. */ enum METHOD { + /** Opens an object and creates an authorized handle. */ OPEN, + /** Closes a previously opened handle. */ CLOSE, - PARSE, // To plug a secondary namespace + /** Parses through a secondary namespace. */ + PARSE, + /** Performs security checks. */ SECURITY }; +/** @brief Claims granted to an authenticated connection. */ enum AUTH_CLAIM { + /** Permission to read object state. */ READ, + /** Permission to mutate object state. */ WRITE }; +/** @brief Authentication strategies supported by the permissions layer. */ enum AUTH_METHOD { + /** Certificate-based authentication. */ CERTIFICATE, + /** Plain-text authentication. */ PLAIN_TEXT }; diff --git a/include/VM.h b/include/VM.h index 74ab982..2defe79 100644 --- a/include/VM.h +++ b/include/VM.h @@ -2,45 +2,50 @@ #include "Api.h" +/** + * @file VM.h + * @brief Declares the logic execution boundary for relational and higher-order workloads. + */ + 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. + * @brief Hosts the first-order logic (FOL) and second-order logic (SOL) cores. + * + * This partitioning exists to ensure retrieval terminates when execution is + * constrained to first-order logic. + * + * - Tarski runtime (FOL): a relational engine that implements Tarski's + * relational calculus. It uses a deterministic Volcano-iterator model to + * perform relational algebra operations such as joins, projections, and + * selects directly against the CursorManager and a prepared plan. + * + * - Karuta runtime (SOL): an isolated WAM-based environment for + * higher-order logic programming. It handles recursion, choice points, and + * other programming constructs that do not guarantee termination. + * + * @remark Lazy evaluation and paging strategy + * + * Both the Tarski first-order engine and the Karuta second-order engine are + * strictly pull-based. Data is streamed lazily from the CursorManager to + * preserve a constant memory footprint regardless of relation size. + * + * Pipeline dynamics: + * - Demand-driven: the Karuta WAM requests a fact only when a goal needs + * satisfaction. A request propagates down the algebra tree as a chain of + * Next() calls. + * + * - Short-circuiting: if the Karuta engine finds a solution or reaches a + * failure that invalidates a branch, the Tarski iterator is discarded or + * reset without materializing the remaining tuples. + * + * - Resource stewardship: by maintaining laziness up to the highest logical + * level, the runtime minimizes pressure on ObjectManager and keeps + * snapshots pinned through LifecycleManager::Monitor only for the minimum + * time required. */ - class NT_API WAM + class NT_API VM { }; } diff --git a/src/HandlerManager.cpp b/src/HandlerManager.cpp index 895f553..7d7015d 100644 --- a/src/HandlerManager.cpp +++ b/src/HandlerManager.cpp @@ -8,9 +8,10 @@ namespace nt { void HandlerManager::DeallocateHandle(struct handle* handle) { + delete handle; } - struct HandlerManager::handle HandlerManager::Open(std::vector<std::string> object_path, void* connection_context) + struct HandlerManager::handle* HandlerManager::Open(std::vector<std::string> object_path, void* connection_context) { ObjectManager objects; PermissionsManager permissions; @@ -22,11 +23,11 @@ namespace nt && lifecycles.Contention(retrieved_object)) { // Starts monitoring this guy lifecycles.Monitor(retrieved_object); - return { retrieved_object, connection_context }; // Return a successful handle + return new handle{ retrieved_object, connection_context }; // Return a successful handle } else { // Return something more algebraic instead of null or an int - return {}; + return nullptr; }; } |