A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
chunk_store_writer.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_WRITER_H_
25#define A11_STORES_CHUNK_STORE_WRITER_H_
26
27#include <cstddef>
28#include <cstdint>
29#include <functional>
30#include <memory>
31#include <optional>
32#include <variant>
33
34#include <absl/status/status.h>
35#include <absl/status/statusor.h>
36
38#include "a11/data/types.h"
40
41namespace a11::net {
42class WireStream;
43} // namespace a11::net
44
45namespace a11::stores {
46
58 std::optional<std::uint64_t> num_chunks_to_buffer = {};
60 std::uint64_t max_chunks_to_write_at_once = 8;
62 std::uint32_t offset = 0;
64 bool sticky_mimetype = false;
65
72 absl::Status Validate() const;
73};
74
90
103 public:
105 std::function<absl::StatusOr<data::NodeRef>(const data::NodeRef&)>;
118 static absl::StatusOr<std::shared_ptr<ChunkStoreWriter>> Create(
119 std::shared_ptr<ChunkStore> store, ChunkStoreWriterOptions options = {});
120
121 ~ChunkStoreWriter() = default;
122
129 void EnsureStarted();
130
151 void Flush();
152
174 std::optional<std::uint32_t> seq = std::nullopt,
175 bool final = false, bool ensure_started = true);
177 data::NodeRef reference, std::optional<std::uint32_t> seq = std::nullopt,
178 bool final = false, bool ensure_started = true);
179
197 data::Chunk chunk, std::optional<std::uint32_t> seq = std::nullopt,
198 bool final = false);
200 data::NodeRef reference, std::optional<std::uint32_t> seq = std::nullopt,
201 bool final = false);
202
204 [[nodiscard]] std::optional<absl::Status> GetStatus() const;
206 [[nodiscard]] std::optional<absl::Status> GetAbortStatus() const;
209 [[nodiscard]] bool IsWritable() const;
210
218
238
250 a11::Task AbortWithStatus(absl::Status status);
251
265
281 absl::Status AttachStream(std::shared_ptr<net::WireStream> stream);
282 absl::Status AttachStream(std::shared_ptr<net::WireStream> stream,
283 ReferenceRewriter rewrite);
284
293 absl::Status DetachStream(const std::shared_ptr<net::WireStream>& stream);
294
296 [[nodiscard]] std::shared_ptr<ChunkStore> store() const;
298 [[nodiscard]] ChunkStoreWriterOptions options() const;
300 [[nodiscard]] size_t queue_size() const;
301
302 private:
303 struct State;
304 ChunkStoreWrite EnqueuePayload(
305 std::variant<data::Chunk, data::NodeRef> payload,
306 std::optional<std::uint32_t> seq, bool final, bool ensure_started);
307
308 explicit ChunkStoreWriter(std::shared_ptr<State> state)
309 : state_(std::move(state)) {}
310
311 std::shared_ptr<State> state_;
312};
313
314} // namespace a11::stores
315
316#endif // A11_STORES_CHUNK_STORE_WRITER_H_
A11's pluggable storage interface for streamed node data: an ordered, appendable log of fragments key...
A buffered, backpressured write cursor over a ChunkStore.
Definition chunk_store_writer.h:102
void Flush()
Run the flush loop now, on the calling thread, if it is idle.
Definition chunk_store_writer.cc:783
a11::Task WaitForBufferToDrain()
Wait until the in-flight write buffer empties.
Definition chunk_store_writer.cc:1025
absl::Status DetachStream(const std::shared_ptr< net::WireStream > &stream)
Stop mirroring fragments to a previously attached wire stream.
Definition chunk_store_writer.cc:1070
absl::Status AttachStream(std::shared_ptr< net::WireStream > stream)
Mirror persisted fragments to an additional wire stream.
Definition chunk_store_writer.cc:1048
a11::Task Cancel()
Stop the writer immediately, discarding any queued chunks.
Definition chunk_store_writer.cc:922
bool IsWritable() const
Definition chunk_store_writer.cc:917
a11::Future< std::uint32_t > PutChunk(data::Chunk chunk, std::optional< std::uint32_t > seq=std::nullopt, bool final=false)
Write a chunk and await backing-store confirmation.
Definition chunk_store_writer.cc:890
static absl::StatusOr< std::shared_ptr< ChunkStoreWriter > > Create(std::shared_ptr< ChunkStore > store, ChunkStoreWriterOptions options={})
Create a writer over store.
Definition chunk_store_writer.cc:760
ChunkStoreWrite EnqueueChunk(data::Chunk chunk, std::optional< std::uint32_t > seq=std::nullopt, bool final=false, bool ensure_started=true)
Enqueue a chunk, exposing backpressure and confirmation separately.
Definition chunk_store_writer.cc:796
std::function< absl::StatusOr< data::NodeRef >(const data::NodeRef &)> ReferenceRewriter
Definition chunk_store_writer.h:105
a11::Future< std::uint32_t > PutReference(data::NodeRef reference, std::optional< std::uint32_t > seq=std::nullopt, bool final=false)
Definition chunk_store_writer.cc:899
size_t queue_size() const
Definition chunk_store_writer.cc:1090
std::optional< absl::Status > GetAbortStatus() const
Definition chunk_store_writer.cc:912
void EnsureStarted()
Start the background flush loop if it is not already running.
Definition chunk_store_writer.cc:779
std::optional< absl::Status > GetStatus() const
Definition chunk_store_writer.cc:907
ChunkStoreWriterOptions options() const
Definition chunk_store_writer.cc:1086
std::shared_ptr< ChunkStore > store() const
Definition chunk_store_writer.cc:1082
a11::Task DrainAndClose()
Flush every queued chunk, then close the writer.
Definition chunk_store_writer.cc:955
a11::Task AbortWithStatus(absl::Status status)
Abort the writer with an error status.
Definition chunk_store_writer.cc:982
ChunkStoreWrite EnqueueReference(data::NodeRef reference, std::optional< std::uint32_t > seq=std::nullopt, bool final=false, bool ensure_started=true)
Definition chunk_store_writer.cc:803
Completion values used by every asynchronous A11 operation.
Definition action.h:66
Definition node_map.h:47
std::uint32_t seq
Definition sqlite_chunk_store.cc:186
A unit of data: bytes plus optional descriptive metadata.
Definition types.h:173
A reference to a (slice of a) logical node, in lieu of inline data.
Definition types.h:311
The pair of awaitables returned when enqueuing a chunk, separating queue admission from backing-store...
Definition chunk_store_writer.h:84
a11::Task admitted
Resolves once the chunk is admitted into the bounded queue (backpressure).
Definition chunk_store_writer.h:86
a11::Future< std::uint32_t > confirmation
Resolves with the assigned sequence once the backing store accepts it.
Definition chunk_store_writer.h:88
Tunables controlling how a ChunkStoreWriter batches and buffers chunks.
Definition chunk_store_writer.h:56
absl::Status Validate() const
Validate that the options are internally consistent.
Definition chunk_store_writer.cc:59
std::uint64_t max_chunks_to_write_at_once
Maximum number of chunks flushed to the store per batch.
Definition chunk_store_writer.h:60
bool sticky_mimetype
Whether repeated contiguous chunk mimetypes are omitted when writing.
Definition chunk_store_writer.h:64
std::optional< std::uint64_t > num_chunks_to_buffer
Optional bound on the in-flight write buffer size.
Definition chunk_store_writer.h:58
std::uint32_t offset
Sequence number at which writing begins.
Definition chunk_store_writer.h:62
Definition chunk_store_writer.cc:78
A11's core wire value types: chunks, node fragments and messages.