A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
async_node.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
35#ifndef A11_NODES_ASYNC_NODE_H_
36#define A11_NODES_ASYNC_NODE_H_
37
38#include <cstddef>
39#include <cstdint>
40#include <memory>
41#include <optional>
42#include <string>
43#include <string_view>
44#include <utility>
45#include <vector>
46
47#include <absl/base/thread_annotations.h>
48#include <absl/status/status.h>
49#include <absl/status/status_macros.h>
50#include <absl/status/statusor.h>
51#include <absl/time/time.h>
52
57#include "a11/data/types.h"
62
63namespace a11::net {
64class WireStream;
65} // namespace a11::net
66
67namespace a11::nodes {
68class NodeMap;
69
71
81 bool wait = false;
84 bool close = true;
87 std::optional<std::uint32_t> seq = {};
90 std::string_view mimetype = {};
91};
92
114class AsyncNode : public std::enable_shared_from_this<AsyncNode> {
115 public:
129 static absl::StatusOr<std::shared_ptr<AsyncNode>> Create(
130 std::shared_ptr<stores::ChunkStore> store,
131 std::shared_ptr<data::SerializationRegistry> serialization_registry =
132 nullptr,
133 stores::ChunkStoreReaderOptions reader_options = {},
134 stores::ChunkStoreWriterOptions writer_options = {});
135
136 ~AsyncNode() = default;
137
138 AsyncNode(const AsyncNode&) = delete;
139 AsyncNode& operator=(const AsyncNode&) = delete;
140
147 absl::StatusOr<std::string> GetId() const;
148
155 [[nodiscard]] std::shared_ptr<stores::ChunkStore> GetChunkStore() const;
156
161 [[nodiscard]] std::shared_ptr<data::SerializationRegistry>
163
169 absl::Status SetSerializationRegistry(
170 std::shared_ptr<data::SerializationRegistry> registry);
171
176 absl::StatusOr<std::shared_ptr<stores::ChunkStoreReader>> reader();
177
182 absl::StatusOr<std::shared_ptr<stores::ChunkStoreWriter>> writer();
183
189
196
203 absl::Status ResetReader(
204 std::optional<stores::ChunkStoreReaderOptions> options = std::nullopt);
205
211
218
224 [[nodiscard]] absl::Status GetReaderStatus() const;
225
231 [[nodiscard]] absl::Status GetWriterStatus() const;
232
236
242 [[nodiscard]] std::optional<absl::Status> GetWriterAbortStatus() const;
243
250
263 data::Chunk chunk, std::optional<std::uint32_t> seq = std::nullopt,
264 bool final = false);
265
273 data::NodeRef reference, std::optional<std::uint32_t> seq = std::nullopt,
274 bool final = false);
275
304 template <typename T>
306 T value, std::string_view mimetype,
307 std::optional<std::uint32_t> seq = std::nullopt, bool final = false) {
308 std::shared_ptr<data::SerializationRegistry> registry;
309 {
310 thread::MutexLock lock(&mu_);
311 registry = serialization_registry_;
312 }
313 return PutChunk(
314 data::MakeChunkObject<T>(std::move(value), data::SerialTypeTag<T>(),
315 std::string(mimetype), registry),
316 seq, final);
317 }
318
319 template <typename T>
321 const T& value, std::optional<std::uint32_t> seq = std::nullopt,
322 bool final = false, std::string_view mimetype = {}) {
323 std::shared_ptr<data::SerializationRegistry> registry;
324 {
325 thread::MutexLock lock(&mu_);
326 registry = serialization_registry_;
327 }
328 absl::StatusOr<data::Chunk> chunk = registry->ToChunk<T>(value, mimetype);
329 if (!chunk.ok()) {
330 return a11::FailedFuture<std::uint32_t>(chunk.status());
331 }
332 return PutChunk(std::move(*chunk), seq, final);
333 }
334
354 a11::Task Finalize(FinalizeOptions options = {});
355
363 a11::Task Finalize(data::Chunk chunk, FinalizeOptions options = {});
364 a11::Task Finalize(data::NodeRef reference, FinalizeOptions options = {});
365
379 template <typename T>
381 std::shared_ptr<data::SerializationRegistry> registry;
382 {
383 thread::MutexLock lock(&mu_);
384 registry = serialization_registry_;
385 }
386 absl::StatusOr<data::Chunk> chunk =
387 registry->ToChunk<T>(value, options.mimetype);
388 if (!chunk.ok()) {
389 return a11::FailedTask(chunk.status());
390 }
391 return Finalize(std::move(*chunk), options);
392 }
393
405 size_t limit, absl::Duration timeout = absl::InfiniteDuration());
406
414 absl::Duration timeout = absl::InfiniteDuration());
415
423 absl::Duration timeout = absl::InfiniteDuration());
425 absl::Duration timeout = absl::InfiniteDuration());
427 NextLogicalFragments(size_t limit,
428 absl::Duration timeout = absl::InfiniteDuration());
430 bool LogicalSawFinal() const;
431
439 absl::Duration timeout = absl::InfiniteDuration());
440
450 template <typename T>
452 absl::Duration timeout = absl::InfiniteDuration(),
453 std::vector<std::string> mimetype_patterns = {}) {
454 std::shared_ptr<AsyncNode> self = shared_from_this();
455 return a11::Submit<std::optional<T>>(
456 [self = std::move(self), timeout,
457 mimetype_patterns = std::move(
458 mimetype_patterns)]() mutable -> absl::StatusOr<std::optional<T>> {
459 // Raw, so a chunk carrying a value still is one when it gets here.
460 // NextFragment() would have materialised it, which is right for every
461 // caller that wants bytes and is exactly what this one does not.
462 absl::StatusOr<std::optional<data::NodeFragment>> fragment =
463 self->NextLogicalFragment(timeout).Await();
464 if (!fragment.ok()) {
465 return fragment.status();
466 }
467 if (!fragment->has_value()) {
468 return std::nullopt;
469 }
470 absl::StatusOr<const data::Chunk*> chunk = (*fragment)->GetChunk();
471 if (!chunk.ok()) {
472 return chunk.status();
473 }
474 // The fast path: the producer put a T and this reader wants a T, so
475 // nothing was encoded and nothing is decoded. Guarded by the tag, not
476 // by type identity -- see a11::data::ChunkObject.
477 if ((*chunk)->HasObject()) {
478 // `if constexpr`, because NextObject is instantiated for types with
479 // no tag at all -- a JSON-native value, a bare string -- and those
480 // simply have no fast path to take.
481 if constexpr (data::HasSerialTypeTag<T>) {
482 if (std::optional<T> taken =
483 data::TryTakeObject<T>(**chunk, data::SerialTypeTag<T>());
484 taken.has_value()) {
485 return taken;
486 }
487 }
488 // Carrying something else. Fall through to the bytes, which means
489 // producing them now: a reader asking for a different type than the
490 // producer wrote is exactly when the wire format earns its keep.
491 data::Chunk materialised = **chunk;
492 ABSL_RETURN_IF_ERROR(materialised.Materialize());
493 std::shared_ptr<data::SerializationRegistry> registry;
494 {
495 thread::MutexLock lock(&self->mu_);
496 registry = self->serialization_registry_;
497 }
498 absl::StatusOr<T> value =
499 registry->FromChunk<T>(materialised, mimetype_patterns);
500 if (!value.ok()) {
501 return value.status();
502 }
503 return std::optional<T>(std::move(*value));
504 }
505 if ((*chunk)->IsNull()) {
506 if ((*fragment)->continued) {
507 return absl::FailedPreconditionError(
508 "A null stream marker must be final");
509 }
510 return std::nullopt;
511 }
512 std::shared_ptr<data::SerializationRegistry> registry;
513 {
514 thread::MutexLock lock(&self->mu_);
515 registry = self->serialization_registry_;
516 }
517 absl::StatusOr<T> value =
518 registry->FromChunk<T>(**chunk, mimetype_patterns);
519 if (!value.ok()) {
520 return value.status();
521 }
522 return std::optional<T>(std::move(*value));
523 });
524 }
525
532
552
559 a11::Task AbortWithStatus(absl::Status status);
560
572 absl::Status AttachStream(std::shared_ptr<net::WireStream> stream);
573 absl::Status AttachStream(
574 std::shared_ptr<net::WireStream> stream,
576
582 absl::Status DetachStream(const std::shared_ptr<net::WireStream>& stream);
583
587 void CancelReader();
588
592 void CancelWriter();
593
598 void Cancel();
599
601 void SetOwner(const std::shared_ptr<NodeMap>& owner);
602 [[nodiscard]] std::shared_ptr<NodeMap> Owner() const;
604 absl::StatusOr<data::NodeRef> Ref(
605 std::uint32_t offset = 0,
606 std::optional<std::uint64_t> length = std::nullopt,
607 std::shared_ptr<NodeMap> destination = nullptr,
610 absl::StatusOr<std::shared_ptr<stores::ChunkStoreReader>> OpenReader(
611 stores::ChunkStoreReaderOptions options) const;
612
613 private:
614 absl::StatusOr<std::shared_ptr<stores::LogicalChunkStoreReader>>
615 logical_reader();
616
617 AsyncNode(std::shared_ptr<stores::ChunkStore> store,
618 std::shared_ptr<data::SerializationRegistry> registry,
619 stores::ChunkStoreReaderOptions reader_options,
620 stores::ChunkStoreWriterOptions writer_options)
621 : store_(std::move(store)),
622 serialization_registry_(std::move(registry)),
623 reader_options_(reader_options),
624 writer_options_(writer_options) {}
625
626 const std::shared_ptr<stores::ChunkStore> store_;
627 mutable thread::Mutex mu_;
628 std::shared_ptr<data::SerializationRegistry> serialization_registry_
629 ABSL_GUARDED_BY(mu_);
630 stores::ChunkStoreReaderOptions reader_options_ ABSL_GUARDED_BY(mu_);
631 stores::ChunkStoreWriterOptions writer_options_ ABSL_GUARDED_BY(mu_);
632 std::shared_ptr<stores::ChunkStoreReader> reader_ ABSL_GUARDED_BY(mu_);
633 std::shared_ptr<stores::LogicalChunkStoreReader> logical_reader_
634 ABSL_GUARDED_BY(mu_);
635 std::shared_ptr<stores::ChunkStoreWriter> writer_ ABSL_GUARDED_BY(mu_);
636 std::weak_ptr<NodeMap> owner_ ABSL_GUARDED_BY(mu_);
637};
638
639} // namespace a11::nodes
640
641#endif // A11_NODES_ASYNC_NODE_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...
A read cursor over a ChunkStore that pulls fragments out in order (or by arrival),...
A write cursor over a ChunkStore that admits chunks into the store in sequence, applying backpressure...
An asynchronous, ordered stream of chunks read from and written to A11.
Definition async_node.h:114
bool LogicalSawFinal() const
Whether the logical source has supplied a final raw fragment.
Definition async_node.cc:661
absl::Status SetSerializationRegistry(std::shared_ptr< data::SerializationRegistry > registry)
Replace the serialization registry.
Definition async_node.cc:293
a11::Future< std::vector< std::optional< data::NodeFragment > > > NextLogicalFragments(size_t limit, absl::Duration timeout=absl::InfiniteDuration())
Definition async_node.cc:652
a11::Future< std::uint32_t > PutObject(T value, std::string_view mimetype, std::optional< std::uint32_t > seq=std::nullopt, bool final=false)
Serialize and write a typed value to the stream.
Definition async_node.h:305
std::shared_ptr< stores::ChunkStore > GetChunkStore() const
Return the underlying chunk store backing this node.
Definition async_node.cc:283
a11::Task WaitForBufferToDrain()
Wait for the write buffer to drain.
Definition async_node.cc:717
a11::Task Finalize(FinalizeOptions options={})
End the stream with an explicit null terminator (no value).
Definition async_node.cc:548
a11::Future< std::uint32_t > PutChunk(data::Chunk chunk, std::optional< std::uint32_t > seq=std::nullopt, bool final=false)
Enqueue a raw chunk into the stream.
Definition async_node.cc:520
stores::ChunkStoreWriterOptions GetWriterOptions() const
Return a copy of the writer's current options.
Definition async_node.cc:430
a11::Task Finalize(const T &value, FinalizeOptions options={})
Serialize value as the stream's final data, then end the stream.
Definition async_node.h:380
a11::Future< std::optional< data::NodeFragment > > NextLogicalFragment(absl::Duration timeout=absl::InfiniteDuration())
Definition async_node.cc:642
a11::Task Close()
Flush all buffered chunks and close the writer, without finality.
Definition async_node.cc:726
stores::ChunkStoreReaderOptions GetReaderOptions() const
Return a copy of the reader's current options.
Definition async_node.cc:385
static absl::StatusOr< std::shared_ptr< AsyncNode > > Create(std::shared_ptr< stores::ChunkStore > store, std::shared_ptr< data::SerializationRegistry > serialization_registry=nullptr, stores::ChunkStoreReaderOptions reader_options={}, stores::ChunkStoreWriterOptions writer_options={})
Create a node over an existing chunk store.
Definition async_node.cc:204
a11::Task AbortWithStatus(absl::Status status)
Fail the stream with an error status.
Definition async_node.cc:732
absl::Status DetachStream(const std::shared_ptr< net::WireStream > &stream)
Stop mirroring chunks over a previously attached wire stream.
Definition async_node.cc:752
void SetOwner(const std::shared_ptr< NodeMap > &owner)
Link a node created by a map to its owning resolution context.
Definition async_node.cc:237
std::shared_ptr< NodeMap > Owner() const
Definition async_node.cc:242
AsyncNode(const AsyncNode &)=delete
a11::Future< std::optional< data::Chunk > > NextChunk(absl::Duration timeout=absl::InfiniteDuration())
Read the next raw chunk.
Definition async_node.cc:692
absl::Status SetReaderOptions(stores::ChunkStoreReaderOptions options)
Replace the reader options.
Definition async_node.cc:390
absl::Status SetWriterOptions(stores::ChunkStoreWriterOptions options)
Replace the writer options.
Definition async_node.cc:435
absl::StatusOr< data::NodeRef > Ref(std::uint32_t offset=0, std::optional< std::uint64_t > length=std::nullopt, std::shared_ptr< NodeMap > destination=nullptr, ReferenceStoragePolicy policy=ReferenceStoragePolicy::kAuto) const
Return a fragment reference using the destination's resolution context.
Definition async_node.cc:247
a11::Future< std::uint32_t > Put(const T &value, std::optional< std::uint32_t > seq=std::nullopt, bool final=false, std::string_view mimetype={})
Definition async_node.h:320
void CancelWriter()
Cancel the writer, unblocking pending Put/drain awaits.
Definition async_node.cc:777
absl::Status GetWriterStatus() const
Return the current status of the node's writer.
Definition async_node.cc:461
a11::Future< std::optional< data::NodeFragment > > NextFragment(absl::Duration timeout=absl::InfiniteDuration())
Read the next raw fragment.
Definition async_node.cc:670
absl::Status GetReaderStatus() const
Return the current status of the node's reader.
Definition async_node.cc:447
absl::Status ResetReader(std::optional< stores::ChunkStoreReaderOptions > options=std::nullopt)
Rewind/reconfigure the reader (e.g.
Definition async_node.cc:406
AsyncNode & operator=(const AsyncNode &)=delete
std::optional< absl::Status > GetWriterAbortStatus() const
Return the status the writer was aborted with.
Definition async_node.cc:488
absl::StatusOr< std::shared_ptr< stores::ChunkStoreWriter > > writer()
Return the node's chunk store writer (the producing half).
Definition async_node.cc:372
void CancelReader()
Cancel the reader, unblocking pending Next* awaits.
Definition async_node.cc:761
a11::Task ObserveCompletion()
Observe logical completion without consuming data or closing the node.
Definition async_node.cc:474
void Cancel()
Cancel both reader and writer, tearing down all pending streaming operations on the node at once.
Definition async_node.cc:788
absl::Status AttachStream(std::shared_ptr< net::WireStream > stream)
Tee this node's stored chunks onto a wire stream.
Definition async_node.cc:738
a11::Future< bool > IsWritable()
Report whether the node can currently accept writes.
Definition async_node.cc:497
std::shared_ptr< data::SerializationRegistry > serialization_registry() const
Return the registry used to (de)serialize typed values.
Definition async_node.cc:287
absl::StatusOr< std::shared_ptr< stores::ChunkStoreReader > > OpenReader(stores::ChunkStoreReaderOptions options) const
Open an independent cursor with this node's reference resolution context.
Definition async_node.cc:360
a11::Future< std::uint32_t > PutReference(data::NodeRef reference, std::optional< std::uint32_t > seq=std::nullopt, bool final=false)
Definition async_node.cc:539
a11::Future< std::optional< T > > NextObject(absl::Duration timeout=absl::InfiniteDuration(), std::vector< std::string > mimetype_patterns={})
Read and deserialize the next value.
Definition async_node.h:451
absl::StatusOr< std::shared_ptr< stores::ChunkStoreReader > > reader()
Return the node's chunk store reader (the consuming half).
Definition async_node.cc:303
a11::Future< std::optional< data::NodeFragment > > NextFragmentRaw(absl::Duration timeout=absl::InfiniteDuration())
Read the next fragment without producing bytes for it.
Definition async_node.cc:633
a11::Future< std::vector< std::optional< data::NodeFragment > > > NextFragments(size_t limit, absl::Duration timeout=absl::InfiniteDuration())
Read up to limit fragments in a single await.
Definition async_node.cc:624
absl::StatusOr< std::string > GetId() const
Return the node's stable identifier.
Definition async_node.cc:233
a11::Future< std::uint32_t > PutFragment(data::NodeFragment fragment)
Enqueue a fragment carrying its own sequence and final flag.
Definition async_node.cc:530
std::function< absl::StatusOr< data::NodeRef >(const data::NodeRef &)> ReferenceRewriter
Definition chunk_store_writer.h:105
Definition boost_primitives.h:28
Definition boost_primitives.h:21
Whether T publishes a serialisation tag.
Definition serializable.h:171
std::string value
Definition discover.cc:100
Completion values used by every asynchronous A11 operation.
std::optional< absl::Duration > timeout
Definition main.cc:146
Definition action.h:66
Definition action.h:70
ReferenceStoragePolicy
Definition async_node.h:70
Task FailedTask(absl::Status status)
Return an already-failed Task.
Definition future.h:440
stores::ChunkStoreReaderOptions options
Definition runtime_streams.cc:31
std::optional< std::uint64_t > length
Definition runtime_streams.cc:37
std::uint32_t offset
Definition runtime_streams.cc:36
ADL-based customization points that make a custom C++ type serializable through a11::data::Serializat...
Type-and-mimetype indexed serialization of values to/from Chunks.
std::uint32_t seq
Definition sqlite_chunk_store.cc:186
std::string mimetype
Definition sqlite_chunk_store.cc:191
A unit of data: bytes plus optional descriptive metadata.
Definition types.h:173
One piece of a node's stream: an inline chunk or a node reference.
Definition types.h:366
A reference to a (slice of a) logical node, in lieu of inline data.
Definition types.h:311
How an AsyncNode::Finalize() call ends the stream.
Definition async_node.h:78
std::string_view mimetype
MIME type selecting the encoding of a typed value.
Definition async_node.h:90
bool close
Whether to close the writer after the final chunk.
Definition async_node.h:84
std::optional< std::uint32_t > seq
Explicit sequence number for the final chunk; assigned in order when omitted.
Definition async_node.h:87
bool wait
Whether to resolve only once the store confirmed the write and, if close is set, closed.
Definition async_node.h:81
Tunables controlling how a ChunkStoreReader delivers and buffers fragments.
Definition chunk_store_reader.h:69
Tunables controlling how a ChunkStoreWriter batches and buffers chunks.
Definition chunk_store_writer.h:56
A11's core wire value types: chunks, node fragments and messages.