Non-Hierarchical Graph
Freely connect nodes via named branches (Token, string, etc.), with support for cycles.
CppUtils::Container::MeshNetwork is designed for creating non-hierarchical graphs (whether they have a single root or not), where nodes connect via labeled branches, tolerate cycles without memory leaks, are safely manipulated across threads, and support disk pagination (MeshPager).
While this model provides high flexibility, it introduces structural overhead (link allocations, branch lookup tables, multithreading support).
Example of a graph representable with MeshNetwork:
graph LR
R1["Root 1"] -->|"next"| A["Node A"]
R1 -->|"next"| B["Node B"]
R2["Root 2"] -->|"next"| C["Node C"]
R2 -->|"link"| B
R3["Root 3"] -->|"next"| D["Node D"]
A <-->|"link"| E["Node E"]
A -->|"branch"| B
B <-->|"link"| F["Node F"]
B -->|"next"| D
C -->|"branch"| B
C -->|"branch"| G["Node G"]
D -->|"next"| C
D -->|"branch"| H["Node H"]
E -->|"next"| F
F -->|"next"| G
G -->|"next"| D
G -->|"link"| E
H -->|"link"| F
H -->|"next"| A
classDef root fill:#2563eb,stroke:#93c5fd,stroke-width:2px,color:#ffffff
class R1,R2,R3 root
This guide is a step-by-step tutorial designed to teach you how to declare a mesh, connect branches, manipulate nodes safely across threads, and serialize graphs with progressive disk pagination.
Non-Hierarchical Graph
Freely connect nodes via named branches (Token, string, etc.), with support for cycles.
RAII Destruction
Instant reclamation of detached subgraphs, even in the presence of cycles.
Deadlock-Free Concurrency
Per-node locking via RAII lockers for safe concurrent access.
Paged Disk Persistence
Progressive disk serialization, saving, and on-demand loading via MeshPager to minimize RAM usage.
Declare a node pointer by specifying the branch key type (here CppUtils::Type::Token) and the payload value type stored in each node (here std::string):
The examples in this guide use the ""_token user-defined literal (from using namespace CppUtils::String::Literals;).
// Define the node type to manipulate (Token keys, std::string values)using NodePtr = CppUtils::Container::MeshNodePtr<CppUtils::Type::Token, std::string>;
// Create a graph root anchorauto root = NodePtr::makeRoot("Root");
// Instantiate standalone nodes (not yet attached to a root)auto nodeA = NodePtr::make("Node A");auto nodeB = NodePtr::make("Node B");graph LR
Root["Root (root)"]
A["Node A (standalone)"]
B["Node B (standalone)"]
classDef root fill:#2563eb,stroke:#93c5fd,stroke-width:2px,color:#ffffff
class Root root
style A stroke-dasharray: 5 5
style B stroke-dasharray: 5 5
Use dedicated operators to connect or detach nodes:
>>)The >> operator links a child node to a parent branch. It supports two forms:
branch >> node attaches node to branch and returns node;parent["a"_token] >> child["b"_token] attaches child to parent["a"_token] and returns the child["b"_token] branch, allowing multi-level chaining in a single expression:// Attach 'nodeA' onto root's "branch" branchroot["branch"_token] >> nodeA;
// Attach 'nodeB' onto nodeA's "sub" branchnodeA["sub"_token] >> nodeB;
// Equivalent single-expression chainingroot["branch"_token] >> nodeA["sub"_token] >> nodeB;
// Fluid chaining on instantiationauto nodeC = root["other"_token] >> NodePtr::make("Node C");graph LR
Root["Root"] -->|"branch"| A["Node A"]
A -->|"sub"| B["Node B"]
Root -->|"other"| C["Node C"]
classDef root fill:#2563eb,stroke:#93c5fd,stroke-width:2px,color:#ffffff
class Root root
-)The - operator removes a link to a node without affecting sibling nodes on the branch:
// Remove nodeA from the "branch" branchroot["branch"_token] - nodeA;As long as you hold a local MeshNodePtr handle to the detached node (nodeA), it remains valid in memory along with its children (nodeB) and can be re-attached. Conversely, any detached node or group of nodes (including cyclic ones) with no remaining root path and no local handle is immediately reclaimed in RAII:
// 1. nodeA stays valid via its local handle and keeps its child nodeBroot["branch"_token] >> nodeA;
// 2. Cyclic subgraph with no remaining local handle: freed on detachment{ auto tempA = root["temp"_token] >> NodePtr::make("Temp A"); auto tempB = tempA["next"_token] >> NodePtr::make("Temp B"); tempB["back"_token] >> tempA; // Internal cycle} // tempA and tempB leave scope, but stay alive while reachable from root
root["temp"_token].clear(); // No root path and no local handle: tempA and tempB are destroyed immediately (despite the cycle)flowchart LR
subgraph Kept ["1. Local handle kept in memory"]
Root["Root"] -->|"branch"| NA["Node A"] -->|"sub"| NB["Node B"]
end
subgraph Freed ["2. No root and no local handle, RAII destroyed"]
TA["Temp A"] -->|"next"| TB["Temp B"]
TB -->|"back"| TA
end
NB ~~~ TA
classDef root fill:#2563eb,stroke:#93c5fd,stroke-width:2px,color:#ffffff
classDef freed stroke:#ef4444,stroke-dasharray: 5 5
class Root root
class TA,TB freed
To clear all children from an entire branch at once, use the clear() member method:
root["branch"_token].clear();To detach all outgoing branches from a node in a single call, use clearBranches():
root.clearBranches();&)The & operator creates both reciprocal links in a single statement. Each bracket refers to the outgoing branch of its respective node, and attachment automatically starts from whichever node is already connected to a root:
// At least one node must be a root or already attached to a rootauto nodeA = NodePtr::makeRoot("Node A");auto nodeB = NodePtr::make("Node B");
// nodeA["toB"] -> nodeB and nodeB["toA"] -> nodeA// (both keys can also be identical)nodeA["toB"_token] & nodeB["toA"_token];graph LR
A["Node A"] -->|"toB"| B["Node B"]
B -->|"toA"| A
classDef root fill:#2563eb,stroke:#93c5fd,stroke-width:2px,color:#ffffff
class A root
Functionally, & is equivalent to chaining two >> links in a single statement:
// Functional unidirectional equivalentnodeA["toB"_token] >> nodeB;nodeB["toA"_token] >> nodeA;/)The / operator detaches both directions of a cross-linked pair simultaneously. As with &, each bracket specifies the outgoing branch to detach on each node:
// Removes nodeB from nodeA["toB"] and nodeA from nodeB["toA"]nodeA["toB"_token] / nodeB["toA"_token];Functionally, / is equivalent to chaining two - operations in a single statement:
nodeA["toB"_token] - nodeB;nodeB["toA"_token] - nodeA;Each node protects its payload with a thread-safe container:
// Acquire a shared read-only accessor to the payload valueif (auto valueAccessor = nodeA.getValue()){ // The value remains locked for shared reading throughout this block std::println("Current value: {}", valueAccessor.value());} // valueAccessor is destroyed here and releases the lock
// Mutate the payload thread-safely (only possible once the lock is released)nodeA.setValue("Node A v2");Always distinguish between two forms of node comparison:
nodeA == nodeB): Returns a bool indicating whether two pointers reference the exact same memory allocation, regardless of value.nodeA.getValue().value() == nodeB.getValue().value()): Compares the payload contents.auto node1 = NodePtr::makeRoot("Value");auto node2 = NodePtr::makeRoot("Value");auto alias1 = node1;
assert(node1 == alias1); // True: same node instanceassert(node1 != node2); // True: distinct allocationsassert(node1.getValue().value() == node2.getValue().value()); // True: identical payload "Value"MeshNodePtr seamlessly integrates with standard C++ ranges, views, and algorithms.
[] and at())There are two ways to access a node’s branch, depending on whether you want to create or mutate it (node[key]) or query it without risking exceptions (node.at(key)):
| Call | On non-const node | On const node | If key is missing |
|---|---|---|---|
node[key] | Returns a mutable branch (exclusive lock) | Returns a read-only branch (shared lock) | Creates the branch if non-const; throws std::out_of_range if const |
node.at(key) | Returns a std::expected (read-only branch, shared lock, or std::string_view error) | Same | Does not create and never throws (std::unexpected<std::string_view>) |
On a branch, indexed access branch[i] (as well as front() and back()) also returns a std::expected<MeshNodePtr, std::string_view>.
Check branch presence and node membership beforehand:
if (root.contains("branch"_token)){ auto branch = root["branch"_token]; std::println("Connected nodes count: {}", std::ranges::size(branch)); std::println("Contains nodeA: {}", branch.contains(nodeA));}Exception-safe access (recommended for read-only inspection):
if (auto branch = root.at("branch"_token)){ if (auto firstNode = branch->front()) { std::println("First node: {}", firstNode->getValue().value()); }}Count the links of a branch without creating it if absent:
const auto linkCount = root.at("branch"_token).transform([](const auto& branch) { return std::ranges::size(branch);}).value_or(0uz);A branch can be traversed like any standard C++ collection:
std::random_access_iterator).Branch object holds a RAII lock on the branch’s link vector (std::vector<Link>) for the entire loop or expression, so no links can be added to or removed from that branch during traversal.WeakPtr rather than a strong pointer. This prevents reference-cycle memory leaks and allows another thread or MeshPager to delete or unpage a target node without locking the entire graph. If the target has expired or been unpaged in the meantime, the iterator yields an empty MeshNodePtr (hence the if (child) check).Start by iterating directly over attached children with a range-for loop:
for (const auto& child : root["branch"_token]){ if (child) { std::println("Node: {}", child.getValue().value()); }}Because branches work with std::ranges algorithms, you can test conditions over their elements in a single expression:
const auto hasNodeA = std::ranges::any_of(root["branch"_token], [](const auto& node) { return node and node.getValue().value() == "Node A";});They also compose cleanly with std::views, for instance to filter valid nodes and reverse traversal order:
for (const auto& validChild : root["branch"_token] | std::views::filter([](const auto& node) { return static_cast<bool>(node); }) | std::views::reverse){ std::println("Valid node: {}", validChild.getValue().value());}Finally, thanks to std::random_access_iterator support, you can work with iterators directly (such as computing an index by subtraction):
auto branch = root["branch"_token];if (auto it = std::ranges::find_if(branch, [](const auto& node) { return node and node.getValue().value() == "Node A"; }); it != std::ranges::end(branch)){ std::println("Found at index {}", it - std::ranges::begin(branch));}getBranches())When branch keys are not known upfront, use getBranches() to iterate over all outgoing branches of a node.
In the loop below, links has type SafeShared<std::vector<Link>> (a thread-safe shared pointer to the branch’s link vector), and .sharedAccess() acquires read-only access to it:
for (const auto& [branchKey, links] : node.getBranches().value()){ std::println("Branch '{}': {} link(s)", branchKey, links->sharedAccess()->size());}The internal architecture of MeshNode relies on synchronization without a global lock, built around three independent levels of CppUtils::Thread::SharedLocker:
SharedLocker<Value>): getValue() and setValue() only lock the node’s payload, without blocking branch operations.SharedLocker<Branches>): getBranches() only locks the branch-key index.SharedLocker<std::vector<Link>>): each branch key has its own link-vector lock. Holding a Branch proxy on "branchA" never blocks access to the node’s payload or concurrent edits to "branchB".An accessor therefore never locks the entire node, only the specific resource being accessed.
flowchart TD
subgraph MeshNode ["Internal MeshNode Architecture"]
ValLock["SharedLocker<Value> (Payload)"]
BranchMapLock["SharedLocker<Branches> (Branch index)"]
BranchALock["SharedLocker<vector<Link>> (Branch A)"]
BranchBLock["SharedLocker<vector<Link>> (Branch B)"]
BranchMapLock --> BranchALock
BranchMapLock --> BranchBLock
end
Reader1["Thread 1 (getValue / sharedAccess)"] --> ValLock
Writer["Thread 2 (setValue / uniqueAccess)"] -. Exclusive .-> ValLock
Reader2["Thread 3 (node['A'])"] --> BranchALock
WriterB["Thread 4 (node['B'] >> x)"] -. Exclusive .-> BranchBLock
In practice, one thread can modify a node’s payload (or one of its branches) while another thread works on a different branch or reads the same node’s payload, without blocking each other.
MeshPager)When your graph needs to persist between program executions or exceeds the machine’s physical RAM, CppUtils provides out-of-core persistence through CppUtils::FileSystem::MeshPager.
track)MeshPager does not discover your nodes automatically: after importing CppUtils.FileSystem.MeshPager and opening a storage directory, you need to register each node with pager.track(node). This assigns it a persistent ID (std::size_t).
Calling track() does not immediately write the node to disk, though: while it stays in the pager’s cache, it remains in RAM. Persistence to disk only triggers when a node falls outside a focus window and is unloaded from RAM, or when the MeshPager is destroyed:
using namespace CppUtils::Type::Literals;using MeshPager = CppUtils::FileSystem::MeshPager<CppUtils::Type::Token, std::string>;using PagedNode = MeshPager::MeshNodePtr; // Equivalent to CppUtils::Container::MeshNodePtr<CppUtils::Type::Token, std::string, MeshPager::Policy>
const auto saveDirectory = std::filesystem::path{"./save"};auto pager = MeshPager{saveDirectory};
auto root = PagedNode::makeRoot("Root");auto nodeA = root["next"_token] >> PagedNode::make("Node A");auto nodeB = nodeA["next"_token] >> PagedNode::make("Node B");auto nodeC = nodeB["next"_token] >> PagedNode::make("Node C");auto nodeD = nodeC["next"_token] >> PagedNode::make("Node D");auto nodeE = nodeD["next"_token] >> PagedNode::make("Node E");
// Register nodes in the pagerpager.track(root);pager.track(nodeA);pager.track(nodeB);pager.track(nodeC);pager.track(nodeD);pager.track(nodeE);acquireFocusInstead of keeping the entire graph in RAM, pager.acquireFocus(node, radius) returns an RAII window (ScopedFocus) that keeps nodes within radius hops resident in memory and automatically evicts the rest to disk:
{ auto focus = pager.acquireFocus(root, 1uz); // 'root' and its direct neighbor 'nodeA' stay in RAM. // 'nodeB', 'nodeC', 'nodeD', and 'nodeE' (at distance >= 2) are evicted to disk while preserving their persistent links.} // When 'focus' (and later 'pager') is destroyed, remaining nodes are flushed to disk.If node is not yet tracked by the pager, acquireFocus() automatically calls track(node) before activating the window.
Multiple ScopedFocus guards can be active at the same time, whether they overlap (like a sliding window across a traversal) or remain completely disjoint to keep separate regions resident in RAM. The union of their radii determines which nodes stay in RAM, while the rest remain on disk.
{ auto focusA = pager.acquireFocus(nodeA, 1uz); auto focusB = pager.acquireFocus(nodeB, 1uz);}{ auto focusA = pager.acquireFocus(nodeA, 1uz); auto focusD = pager.acquireFocus(nodeD, 1uz);}addFocus, removeFocus)If you need non-RAII control (such as tying a focus to an event rather than a lexical scope), use addFocus(nodeId, distance) and removeFocus(nodeId, distance):
// Manage a focus lifetime manually (without an RAII scope)const auto idA = nodeA.getId();pager.addFocus(idA, 1uz);// ...pager.removeFocus(idA, 1uz);loadNode, unloadNode)If you want to control node residency in RAM manually without using focus windows, MeshPager provides two complementary methods: loadNode(nodeId) to load a node from disk into RAM, and unloadNode(nodeId) to serialize it to disk and free RAM immediately:
auto root = pager.loadNode(rootId); // Loads root from diskpager.unloadNode(rootId); // Flushes root to disk and removes it from RAMloadNode() and unloadNode() work on any node by its ID, not only root nodes: every node is stored and indexed independently by its nodeId.
auto root = pager.loadNode(rootId);auto nodeA = root["next"_token].front().value(); // Loads nodeA on demandOnce a node is loaded with loadNode(), accessing any of its branches automatically reloads target nodes that are not yet in RAM from disk, and the same applies to any subsequent hops across the graph.
MeshPager assigns sequential IDs starting at 1uz (0uz is reserved for untracked or null nodes) and does not maintain a root catalog. Two best practices make it easy to locate your entry points on the next startup:
1uz: in a fresh directory, register a dedicated root node first so it automatically receives ID 1uz and links to your graph’s roots or branches. On restart, calling pager.loadNode(1uz) gives you immediate access to the whole entry table.pager.track(root) (or root.getId()) in an application configuration file (or in a separate IndexedStorage instance using a distinct directory from the pager) and read them back at startup.removeNode)Two mechanisms handle deleting nodes from disk, depending on your use case:
ScopedFocus goes out of scope). A plain unloadNode() call does not trigger this cleanup: it simply flushes the node to disk and evicts it from RAM.removeNode(nodeId)): required to delete a root node (never deleted automatically, even with no parent) or to immediately remove a specific node from RAM, link tables, and disk storage (especially when not using focus windows, or without waiting for a ScopedFocus to expire).{ auto focus = pager.acquireFocus(root, 1uz); root["next"_token] - nodeA;} // When focus goes out of scope, nodeA (and nodeB if unreachable) are removed from disk
// Or explicitly delete a node by IDpager.removeNode(rootId);To persist a node to disk when it is evicted from RAM (and reconstruct it when reloaded), MeshPager<Key, Value> must convert both its branch keys (Key) and node values (Value) into a binary stream using CppUtils::Type::Binary::Serializer.
The following types are supported out of the box, with no extra boilerplate:
int, double, bool, etc.), enum types, and plain POD structs (std::is_trivially_copyable_v<T>).std::stringstd::vector<T>, provided T is itself serializable.std::unordered_map<Key, Value>, provided both Key and Value are serializable.To extend binary serialization support to your own custom types (for instance a struct containing std::string or other non-trivial members), specialize CppUtils::Type::Binary::Serializer:
struct UserAccount{ std::string name; std::uint64_t score = 0;};
template<>struct CppUtils::Type::Binary::Serializer<UserAccount> final{ static auto serialize(const UserAccount& user, auto& target) -> void { CppUtils::Type::serialize(user.name, target); CppUtils::Type::serialize(user.score, target); }
[[nodiscard]] static auto deserialize(auto& source, UserAccount& user) -> std::expected<void, std::string_view> { if (auto result = CppUtils::Type::deserialize(source, user.name); not result) return result; if (auto result = CppUtils::Type::deserialize(source, user.score); not result) return result; return {}; }
[[nodiscard]] static auto deserialize(auto& source) -> std::expected<UserAccount, std::string_view> { auto user = UserAccount{}; if (auto result = deserialize(source, user); not result) return std::unexpected{result.error()}; return user; }};Once this specialization is defined, you can directly instantiate MeshPager<std::string, UserAccount>: the pager automatically serializes and reloads your UserAccount payloads to and from disk with no extra configuration.