A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
node_map.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 The A11 Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
28#ifndef A11_NODES_NODE_MAP_H_
29#define A11_NODES_NODE_MAP_H_
30
31#include <cstddef>
32#include <functional>
33#include <memory>
34#include <optional>
35#include <string>
36#include <string_view>
37#include <vector>
38
39#include <absl/base/thread_annotations.h>
40#include <absl/container/flat_hash_map.h>
41#include <absl/status/status.h>
42#include <absl/status/statusor.h>
43
44#include "a11/data/types.h"
46
47namespace a11::stores {
48class ChunkStore;
49} // namespace a11::stores
50
51namespace a11::nodes {
52
53class AsyncNode;
54class NodeMap;
55using StorageResolver = std::function<absl::StatusOr<std::shared_ptr<NodeMap>>(
57
61 std::function<absl::StatusOr<std::shared_ptr<stores::ChunkStore>>(
62 std::string node_id)>;
63
71class NodeMap : public std::enable_shared_from_this<NodeMap> {
72 public:
79 static absl::StatusOr<std::shared_ptr<NodeMap>> Create(
80 ChunkStoreFactory factory = {},
81 std::optional<data::StorageIdentity> storage = {});
82 ~NodeMap() = default;
83
89 // By value: on a miss the id is moved into the map, and callers hand it
90 // over rather than lending it.
91 // NOLINTNEXTLINE(performance-unnecessary-value-param)
97 absl::StatusOr<std::shared_ptr<AsyncNode>> Get(std::string node_id);
98
104 absl::StatusOr<std::shared_ptr<AsyncNode>> GetIfExists(
105 std::string_view node_id) const;
106
108 absl::Status RegisterStorage(std::string storage_id,
109 std::shared_ptr<NodeMap> storage);
110
112 [[nodiscard]] const std::optional<data::StorageIdentity>& Storage() const {
113 return storage_;
114 }
115
117 absl::Status SetStorageResolver(StorageResolver resolver,
118 std::vector<std::string> accessible_ids = {});
120 [[nodiscard]] std::vector<std::string> StorageIds() const;
121
123 void SetAllowLazyReadResolution(bool allowed);
124 [[nodiscard]] bool AllowsLazyReadResolution() const;
125
127 absl::StatusOr<std::shared_ptr<AsyncNode>> Resolve(
128 const data::NodeRef& reference);
130 absl::StatusOr<std::shared_ptr<AsyncNode>> ResolveForRead(
131 const data::NodeRef& reference);
132
134 absl::StatusOr<std::shared_ptr<AsyncNode>> ImportReference(
135 const data::NodeRef& reference, const std::shared_ptr<NodeMap>& source);
136
144 absl::StatusOr<std::shared_ptr<AsyncNode>> Discard(
145 std::string_view node_id,
146 const std::shared_ptr<AsyncNode>& expected = nullptr);
147
153 [[nodiscard]] bool Contains(std::string_view node_id) const;
154
159 [[nodiscard]] size_t Size() const;
160
169 [[nodiscard]] std::vector<std::string> Ids() const;
170
171 private:
172 explicit NodeMap(ChunkStoreFactory factory,
173 std::optional<data::StorageIdentity> storage);
174
175 absl::Status Insert(const std::shared_ptr<AsyncNode>& node);
176
177 const ChunkStoreFactory factory_;
178 const std::optional<data::StorageIdentity> storage_;
179 mutable thread::Mutex mu_;
180 StorageResolver storage_resolver_ ABSL_GUARDED_BY(mu_);
181 std::vector<std::string> accessible_ids_ ABSL_GUARDED_BY(mu_);
182 bool allow_lazy_read_resolution_ ABSL_GUARDED_BY(mu_) = false;
183 absl::flat_hash_map<std::string, std::shared_ptr<NodeMap>> storages_
184 ABSL_GUARDED_BY(mu_);
185 absl::flat_hash_map<
186 std::string, absl::flat_hash_map<std::string, std::shared_ptr<AsyncNode>>>
187 imported_ ABSL_GUARDED_BY(mu_);
188 absl::flat_hash_map<std::string, std::shared_ptr<AsyncNode>> nodes_
189 ABSL_GUARDED_BY(mu_);
190 absl::flat_hash_map<std::string, std::shared_ptr<AsyncNode>> retained_refs_
191 ABSL_GUARDED_BY(mu_);
192};
193
194} // namespace a11::nodes
195
196#endif // A11_NODES_NODE_MAP_H_
A thread-safe registry of AsyncNodes keyed by id.
Definition node_map.h:71
absl::StatusOr< std::shared_ptr< AsyncNode > > ImportReference(const data::NodeRef &reference, const std::shared_ptr< NodeMap > &source)
Share a referenced node from another scope, preserving its identity.
Definition node_map.cc:299
absl::StatusOr< std::shared_ptr< AsyncNode > > GetIfExists(std::string_view node_id) const
Return the node for an id without creating it.
Definition node_map.cc:109
static absl::StatusOr< std::shared_ptr< NodeMap > > Create(ChunkStoreFactory factory={}, std::optional< data::StorageIdentity > storage={})
Create a node map.
Definition node_map.cc:45
absl::Status SetStorageResolver(StorageResolver resolver, std::vector< std::string > accessible_ids={})
Adopt host connection policy; advertised ids must be directly accessible.
Definition node_map.cc:149
absl::StatusOr< std::shared_ptr< AsyncNode > > Discard(std::string_view node_id, const std::shared_ptr< AsyncNode > &expected=nullptr)
Remove the node for an id.
Definition node_map.cc:360
bool AllowsLazyReadResolution() const
Definition node_map.cc:127
void SetAllowLazyReadResolution(bool allowed)
Permit read resolution to open uncached nodes through this map's factory.
Definition node_map.cc:122
std::vector< std::string > StorageIds() const
Storage identities directly accessible through this host's resolver.
Definition node_map.cc:164
absl::StatusOr< std::shared_ptr< AsyncNode > > Get(std::string node_id)
Return the node for an id, creating it if it does not exist.
Definition node_map.cc:71
absl::Status RegisterStorage(std::string storage_id, std::shared_ptr< NodeMap > storage)
Configure a host-accessible namespace and its backend node map.
Definition node_map.cc:133
bool Contains(std::string_view node_id) const
Report whether a node with the given id exists.
Definition node_map.cc:374
std::vector< std::string > Ids() const
Return the id of every node the map holds, sorted.
Definition node_map.cc:384
size_t Size() const
Return the number of nodes currently in the map.
Definition node_map.cc:379
absl::StatusOr< std::shared_ptr< AsyncNode > > ResolveForRead(const data::NodeRef &reference)
Resolve an existing local target for a value read.
Definition node_map.cc:235
absl::StatusOr< std::shared_ptr< AsyncNode > > Resolve(const data::NodeRef &reference)
Resolve a whole-node reference; windows require a fragment-window reader.
Definition node_map.cc:178
const std::optional< data::StorageIdentity > & Storage() const
Identity of this map's backend, or absent for session-local storage.
Definition node_map.h:112
Abstract, pluggable backing store for the data of a node: an ordered, appendable log of fragments.
Definition chunk_store.h:67
Definition boost_primitives.h:21
Definition action.h:70
std::function< absl::StatusOr< std::shared_ptr< stores::ChunkStore > >(std::string node_id)> ChunkStoreFactory
Callable invoked to construct the backing chunk store for a new node from its id.
Definition node_map.h:62
std::function< absl::StatusOr< std::shared_ptr< NodeMap > >(data::StorageIdentity)> StorageResolver
Definition node_map.h:56
Definition node_map.h:47
graph::RefId node
Graph ref for this result, or [graph::kNone] without a resolved ref.
Definition resolve.cc:809
int storage
Definition sqlite_chunk_store.cc:189
A reference to a (slice of a) logical node, in lieu of inline data.
Definition types.h:311
Logical namespace with optional host-interpreted backend access information.
Definition types.h:290
A11's core wire value types: chunks, node fragments and messages.