A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
chunk_store_reader.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
24#ifndef A11_STORES_CHUNK_STORE_READER_H_
25#define A11_STORES_CHUNK_STORE_READER_H_
26
27#include <atomic>
28#include <cstddef>
29#include <cstdint>
30#include <memory>
31#include <optional>
32#include <utility>
33#include <vector>
34
35#include <absl/status/status.h>
36#include <absl/status/statusor.h>
37#include <absl/time/time.h>
38
40#include "a11/data/types.h"
42
43namespace a11::stores {
44class ReferenceResolver;
45class LogicalChunkStoreReader;
46
48 std::shared_ptr<ChunkStore> store;
49 std::shared_ptr<ReferenceResolver> resolver;
50};
51
54 public:
55 virtual ~ReferenceResolver() = default;
56 virtual absl::StatusOr<ResolvedReference> Resolve(
57 const data::NodeRef& reference) = 0;
58};
59
71 std::uint64_t num_chunks_to_buffer = 32;
73 std::optional<std::uint64_t> max_chunks_to_read = {};
75 std::uint32_t offset = 0;
77 std::uint32_t max_ref_depth = 8;
79 std::uint32_t max_ref_breadth = 2;
81 bool ordered = true;
83 bool pop_chunks = false;
85 bool sticky_mimetype = false;
87 bool follow_node_refs = true;
88
95 absl::Status Validate() const;
96};
97
109 public:
122 static absl::StatusOr<std::shared_ptr<ChunkStoreReader>> Create(
123 std::shared_ptr<ChunkStore> store, ChunkStoreReaderOptions options = {},
124 std::shared_ptr<ReferenceResolver> resolver = nullptr);
125
127
134 void EnsureStarted();
135
142 void Cancel();
143
151 absl::Status GetStatus() const;
152
160 [[nodiscard]] a11::Task Done() const;
161
172 absl::Duration timeout = absl::InfiniteDuration());
173
198 size_t limit, absl::Duration timeout = absl::InfiniteDuration());
201 absl::Duration timeout = absl::InfiniteDuration());
204 size_t limit, absl::Duration timeout = absl::InfiniteDuration());
206 bool LogicalSawFinal() const;
207
209 [[nodiscard]] std::shared_ptr<ChunkStore> store() const;
211 [[nodiscard]] ChunkStoreReaderOptions options() const;
213 [[nodiscard]] size_t buffer_size() const;
214
215 private:
217 struct State;
218 struct LogicalState;
219 struct LogicalHolder;
220 absl::StatusOr<std::shared_ptr<LogicalChunkStoreReader>> GetLogical();
221 LogicalHolder* GetLogicalHolder();
222 void CancelLogical();
223 absl::Status GetLogicalStatus() const;
224 std::optional<data::NodeFragment> TryTakeSimpleBuffered();
225
226 explicit ChunkStoreReader(std::shared_ptr<State> state)
227 : state_(std::move(state)) {}
228
229 std::shared_ptr<State> state_;
230 std::shared_ptr<ReferenceResolver> resolver_;
231 std::atomic<LogicalHolder*> logical_holder_ = nullptr;
232};
233
236 public:
237 static absl::StatusOr<std::shared_ptr<LogicalChunkStoreReader>> Create(
238 std::shared_ptr<ChunkStore> store, ChunkStoreReaderOptions options,
239 std::shared_ptr<ReferenceResolver> resolver = nullptr);
240
241 void Cancel();
242 absl::Status GetStatus() const;
243 bool SawFinal() const;
245 absl::Duration timeout = absl::InfiniteDuration());
247 size_t limit, absl::Duration timeout = absl::InfiniteDuration());
248
249 private:
251 std::shared_ptr<ChunkStoreReader::LogicalState> state)
252 : state_(std::move(state)) {}
253
254 std::shared_ptr<ChunkStoreReader::LogicalState> state_;
255};
256
257} // namespace a11::stores
258
259#endif // A11_STORES_CHUNK_STORE_READER_H_
std::shared_ptr< stores::ChunkStore > store
Definition async_node.cc:55
A11's pluggable storage interface for streamed node data: an ordered, appendable log of fragments key...
An ordered, buffered read cursor over a ChunkStore.
Definition chunk_store_reader.h:108
ChunkStoreReaderOptions options() const
Definition chunk_store_reader.cc:816
size_t buffer_size() const
Definition chunk_store_reader.cc:820
static absl::StatusOr< std::shared_ptr< ChunkStoreReader > > Create(std::shared_ptr< ChunkStore > store, ChunkStoreReaderOptions options={}, std::shared_ptr< ReferenceResolver > resolver=nullptr)
Create a reader over store.
Definition chunk_store_reader.cc:709
a11::Future< std::optional< data::NodeFragment > > NextLogical(absl::Duration timeout=absl::InfiniteDuration())
Read a leaf fragment after following references with this reader's policy.
Definition chunk_store_reference_reader.cc:419
void EnsureStarted()
Start the background read pump if it is not already running.
Definition chunk_store_reader.cc:733
a11::Future< std::vector< std::optional< data::NodeFragment > > > NextMany(size_t limit, absl::Duration timeout=absl::InfiniteDuration())
Get up to limit fragments in one await.
Definition chunk_store_reader.cc:769
bool LogicalSawFinal() const
Whether the logical source has supplied a final raw fragment.
Definition chunk_store_reference_reader.cc:406
a11::Task Done() const
Await completion of the background read pump.
Definition chunk_store_reader.cc:751
a11::Future< std::optional< data::NodeFragment > > Next(absl::Duration timeout=absl::InfiniteDuration())
Get the next fragment from the store.
Definition chunk_store_reader.cc:755
std::shared_ptr< ChunkStore > store() const
Definition chunk_store_reader.cc:812
~ChunkStoreReader()
Definition chunk_store_reference_reader.cc:344
a11::Future< std::vector< std::optional< data::NodeFragment > > > NextLogicalMany(size_t limit, absl::Duration timeout=absl::InfiniteDuration())
Read available logical leaf fragments without waiting to fill the batch.
Definition chunk_store_reference_reader.cc:461
absl::Status GetStatus() const
Get the reader's current status.
Definition chunk_store_reader.cc:742
void Cancel()
Stop the background read pump.
Definition chunk_store_reader.cc:737
Logical read cursor backed by one raw reader and a reference traversal.
Definition chunk_store_reader.h:235
void Cancel()
Definition chunk_store_reference_reader.cc:332
a11::Future< std::vector< std::optional< data::NodeFragment > > > NextMany(size_t limit, absl::Duration timeout=absl::InfiniteDuration())
Definition chunk_store_reference_reader.cc:479
bool SawFinal() const
Definition chunk_store_reference_reader.cc:340
static absl::StatusOr< std::shared_ptr< LogicalChunkStoreReader > > Create(std::shared_ptr< ChunkStore > store, ChunkStoreReaderOptions options, std::shared_ptr< ReferenceResolver > resolver=nullptr)
Definition chunk_store_reference_reader.cc:309
absl::Status GetStatus() const
Definition chunk_store_reference_reader.cc:336
a11::Future< std::optional< data::NodeFragment > > Next(absl::Duration timeout=absl::InfiniteDuration())
Definition chunk_store_reference_reader.cc:432
Supplies a target store and the target's own resolution context.
Definition chunk_store_reader.h:53
virtual ~ReferenceResolver()=default
virtual absl::StatusOr< ResolvedReference > Resolve(const data::NodeRef &reference)=0
Completion values used by every asynchronous A11 operation.
std::optional< absl::Duration > timeout
Definition main.cc:146
Definition node_map.h:47
stores::ChunkStoreReaderOptions options
Definition runtime_streams.cc:31
A reference to a (slice of a) logical node, in lieu of inline data.
Definition types.h:311
Tunables controlling how a ChunkStoreReader delivers and buffers fragments.
Definition chunk_store_reader.h:69
std::uint32_t max_ref_depth
Maximum active reference edges.
Definition chunk_store_reader.h:77
bool ordered
Whether fragments are delivered strictly in sequence order.
Definition chunk_store_reader.h:81
std::uint32_t offset
Sequence number at which reading begins.
Definition chunk_store_reader.h:75
bool pop_chunks
Whether fragments are removed from the store as they are read.
Definition chunk_store_reader.h:83
std::optional< std::uint64_t > max_chunks_to_read
Optional cap on the total number of fragments to read.
Definition chunk_store_reader.h:73
absl::Status Validate() const
Validate that the options are internally consistent.
Definition chunk_store_reader.cc:48
bool follow_node_refs
Expand references in logical chunk and value reads.
Definition chunk_store_reader.h:87
std::uint32_t max_ref_breadth
Maximum sibling followers prefetched at one level.
Definition chunk_store_reader.h:79
std::uint64_t num_chunks_to_buffer
Maximum number of fragments to prefetch into the buffer.
Definition chunk_store_reader.h:71
bool sticky_mimetype
Whether ordered reads inherit the last explicitly set chunk mimetype.
Definition chunk_store_reader.h:85
Definition chunk_store_reference_reader.cc:303
Definition chunk_store_reference_reader.cc:39
Definition chunk_store_reader.cc:68
Definition chunk_store_reader.h:47
std::shared_ptr< ReferenceResolver > resolver
Definition chunk_store_reader.h:49
std::shared_ptr< ChunkStore > store
Definition chunk_store_reader.h:48
A11's core wire value types: chunks, node fragments and messages.