A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
runtime.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
17#ifndef A11_FLOW_RUNTIME_H_
18#define A11_FLOW_RUNTIME_H_
19
20#include <atomic>
21#include <cstddef>
22#include <limits>
23#include <memory>
24#include <string>
25#include <string_view>
26#include <vector>
27
28#include <absl/base/nullability.h>
29#include <absl/status/status.h>
30#include <absl/status/statusor.h>
31
32#include "a11/actions/action.h"
33#include "a11/actions/schema.h"
34#include "a11/flow/graph.h"
35#include "a11/flow/module.h"
36#include "a11/flow/parser.h"
37#include "a11/flow/plan.h"
38#include "a11/flow/resolve.h"
40#include "a11/flow/values.h"
41
42namespace a11::net {
43class WireStream;
44} // namespace a11::net
45
46namespace a11::flow {
47
49inline constexpr size_t kQueueDepth = 8;
50
51struct RuntimeLayouts;
52struct RuntimeAccess;
53
54// One flow file, compiled: the plans, the graphs, and the tree they borrow. A
55// graph points into the parse tree it was resolved from, so the two have one
56// owner and one lifetime.
64 public:
71 static absl::StatusOr<std::shared_ptr<CompiledProgram>> Compile(
72 std::string source, std::string source_name = {},
73 const ModuleSources& modules = {}, ModuleResolver resolver = {},
75
76 [[nodiscard]] const Program& program() const { return resolved_.program; }
77
78 [[nodiscard]] const std::string& source() const { return source_; }
79
80 [[nodiscard]] const std::string& source_name() const { return source_name_; }
81
82 [[nodiscard]] const std::vector<Diagnostic>& diagnostics() const {
83 return resolved_.diagnostics;
84 }
85
87 [[nodiscard]] const std::vector<ResolvedFlow>& flows() const {
88 return resolved_.flows;
89 }
90
92 const SingleItemAnalysis* absl_nullable SingleItems(
93 std::string_view flow) const;
95 nlohmann::json Optimizations() const;
96
98 std::vector<std::string> ExternalActions() const;
99
101 [[nodiscard]] const ResolvedFlow* absl_nullable Flow(
102 std::string_view name) const;
103
105 [[nodiscard]] const ResolvedFlow* absl_nullable Entry() const;
106
107 const PreparedExpressions& prepared() const { return prepared_; }
108
109 private:
110 friend struct RuntimeAccess;
111 CompiledProgram() = default;
112
113 std::shared_ptr<const RuntimeLayouts> layouts_;
114
115 std::string source_;
116 std::string linked_source_;
117 std::string source_name_;
118 ParseResult parsed_;
119 std::vector<ModuleMember> members_;
120 ResolveResult resolved_;
121 PreparedExpressions prepared_;
122 bool single_item_slots_ = false;
123 absl::flat_hash_map<std::string, SingleItemAnalysis> single_items_;
124};
125
130absl::StatusOr<actions::ActionSchema> FlowSchema(
131 const FlowPlan& plan, const Program* absl_nullable shapes = nullptr);
132
136 std::vector<DtoPlan> types;
137 std::vector<Diagnostic> diagnostics;
138};
139
141
143struct ExecutionSnapshot;
144
147 std::atomic<size_t> bus_pumps{0};
148 std::atomic<size_t> slot_pumps{0};
149 std::atomic<size_t> buffer_pumps{0};
150 std::atomic<size_t> inline_producers{0};
151 std::atomic<size_t> queue_readers{0};
152 std::atomic<size_t> slots{0};
153 std::atomic<size_t> transfer_tasks{0};
154 std::atomic<size_t> virtual_groups{0};
155 std::atomic<size_t> literal_transfers{0};
156 std::atomic<size_t> active_writer_groups{0};
157 std::atomic<size_t> peak_writer_groups{0};
158};
159
164 std::atomic<size_t> allocations{0};
165 std::atomic<size_t> reuses{0};
166 std::atomic<size_t> activations{0};
167 std::atomic<size_t> reserved_bytes{0};
168 std::atomic<size_t> peak_reserved_bytes{0};
169 std::atomic<size_t> live_bytes{0};
170 std::atomic<size_t> peak_live_bytes{0};
171 std::atomic<size_t> cached_bytes{0};
172 std::atomic<size_t> peak_cached_bytes{0};
173 std::atomic<size_t> active_frames{0};
174 std::atomic<size_t> peak_active_frames{0};
175};
176
180 size_t cache_limit_bytes = 256 * 1024;
183 size_t max_reserved_bytes = std::numeric_limits<size_t>::max();
184 std::shared_ptr<FrameStats> stats;
185};
186
188 std::shared_ptr<TransportStats> transport_stats;
189
191 std::shared_ptr<ExecutionSnapshot> snapshot;
195 std::shared_ptr<HostBridge> bridge;
196
205 std::shared_ptr<net::WireStream> dispatch_stream;
206
208};
209
215absl::StatusOr<actions::ActionHandler> MakeHandler(
216 std::shared_ptr<const CompiledProgram> program, std::string_view flow,
217 RunOptions options = {});
218
226absl::StatusOr<actions::ActionHandler> MakeEntryHandler(
227 std::shared_ptr<const CompiledProgram> program, RunOptions options = {});
228
229} // namespace a11::flow
230
231#endif // A11_FLOW_RUNTIME_H_
A11's unit of work: the Action and its supporting types.
Schemas describing an action's typed interface and its settings.
One flow file, compiled: the plans, the graphs, and the tree they borrow.
Definition runtime.h:63
const std::string & source_name() const
Definition runtime.h:80
const Program & program() const
Definition runtime.h:76
std::vector< std::string > ExternalActions() const
Runtime identities of external actions called by this composition.
Definition runtime.cc:168
const std::vector< ResolvedFlow > & flows() const
The flows in the order they were declared.
Definition runtime.h:87
static absl::StatusOr< std::shared_ptr< CompiledProgram > > Compile(std::string source, std::string source_name={}, const ModuleSources &modules={}, ModuleResolver resolver={}, CompilationLimits limits={}, bool single_item_slots=true)
Compile source, or fail with the first error the way flow.loads does.
Definition runtime.cc:26
const ResolvedFlow *absl_nullable Entry() const
The file's entry point – flow { ... } – or nullptr.
Definition runtime.cc:215
friend struct RuntimeAccess
Definition runtime.h:110
const SingleItemAnalysis *absl_nullable SingleItems(std::string_view flow) const
Verified transport evidence for an enabled compilation, or nullptr.
Definition runtime.cc:145
const PreparedExpressions & prepared() const
Definition runtime.h:107
const ResolvedFlow *absl_nullable Flow(std::string_view name) const
The flow of this name, or nullptr. Never the entry flow.
Definition runtime.cc:192
const std::string & source() const
Definition runtime.h:78
nlohmann::json Optimizations() const
Explain this compilation's transport choices using the native envelope.
Definition runtime.cc:151
const std::vector< Diagnostic > & diagnostics() const
Definition runtime.h:82
std::string name
The declaration name and its colon.
Definition format.cc:50
bool single_item_slots
Definition main.cc:149
CompilationLimits limits
Definition main.cc:148
Definition catalogue.cc:29
constexpr size_t kQueueDepth
Maximum values a pipe may hold ahead of its reader.
Definition runtime.h:49
absl::StatusOr< actions::ActionHandler > MakeEntryHandler(std::shared_ptr< const CompiledProgram > program, RunOptions options)
The action handler that runs the program's entry flow.
Definition runtime.cc:248
ActionDeclaration DeclareAction(const actions::ActionSchema &schema)
Definition runtime_schema.cc:108
std::function< absl::StatusOr< ModuleSource >(std::string_view reference, std::string_view importer)> ModuleResolver
Definition module.h:39
absl::StatusOr< actions::ActionHandler > MakeHandler(std::shared_ptr< const CompiledProgram > program, std::string_view flow, RunOptions options)
The action handler that runs one flow of program.
Definition runtime.cc:224
absl::flat_hash_map< std::string, std::string > ModuleSources
Definition module.h:37
absl::StatusOr< actions::ActionSchema > FlowSchema(const FlowPlan &plan, const Program *absl_nullable shapes=nullptr)
The [actions::ActionSchema] a flow presents.
Definition action.h:66
stores::ChunkStoreReaderOptions options
Definition runtime_streams.cc:31
The full typed interface of an action.
Definition schema.h:144
Import an action interface and representable object metadata for generation.
Definition runtime.h:134
std::vector< Diagnostic > diagnostics
Definition runtime.h:137
std::vector< DtoPlan > types
Definition runtime.h:136
FlowPlan interface
Definition runtime.h:135
Host-controlled bounds shared by parsing, linking and semantic analysis.
Definition limits.h:24
One compiled flow: what a caller sees, and what the runtime will do.
Definition plan.h:157
Execution-frame storage policy, independent of Flow semantics.
Definition runtime.h:178
std::shared_ptr< FrameStats > stats
Definition runtime.h:184
size_t max_reserved_bytes
Maximum frame capacity across an invocation and its program's local calls.
Definition runtime.h:183
size_t cache_limit_bytes
Maximum cached frame capacity per runner; zero disables caching.
Definition runtime.h:180
Requested frame capacity, including block headers and unused optional slots.
Definition runtime.h:163
std::atomic< size_t > reuses
Definition runtime.h:165
std::atomic< size_t > cached_bytes
Definition runtime.h:171
std::atomic< size_t > activations
Definition runtime.h:166
std::atomic< size_t > peak_cached_bytes
Definition runtime.h:172
std::atomic< size_t > reserved_bytes
Definition runtime.h:167
std::atomic< size_t > peak_reserved_bytes
Definition runtime.h:168
std::atomic< size_t > active_frames
Definition runtime.h:173
std::atomic< size_t > peak_active_frames
Definition runtime.h:174
std::atomic< size_t > peak_live_bytes
Definition runtime.h:170
std::atomic< size_t > allocations
Definition runtime.h:164
std::atomic< size_t > live_bytes
Definition runtime.h:169
The flows a file declares, and everything wrong with it.
Definition parser.h:34
Immutable, bounded literal preparation shared by execution activations.
Definition values.h:532
Every flow and shape one source file declares.
Definition plan.h:200
A whole file, resolved.
Definition resolve.h:178
Program program
Definition resolve.h:179
std::vector< ResolvedFlow > flows
Definition resolve.h:180
std::vector< Diagnostic > diagnostics
Definition resolve.h:181
One flow, resolved: its plan, its names, and what is wrong with it.
Definition resolve.h:155
Definition runtime.h:187
std::shared_ptr< ExecutionSnapshot > snapshot
Execution-local pinned registry bindings, shared by transitive flows.
Definition runtime.h:191
std::shared_ptr< net::WireStream > dispatch_stream
For a flow a client runs over a session it already holds: the call steps that belong to the peer are ...
Definition runtime.h:205
FrameOptions frames
Definition runtime.h:207
std::shared_ptr< TransportStats > transport_stats
Definition runtime.h:188
std::shared_ptr< HostBridge > bridge
Who answers the questions only the host can: coercion into a registered type, and reading and writing...
Definition runtime.h:195
Definition single_item.h:41
Optional per-run counters; transport pumps count actual fiber entry.
Definition runtime.h:146
std::atomic< size_t > active_writer_groups
Definition runtime.h:156
std::atomic< size_t > literal_transfers
Definition runtime.h:155
std::atomic< size_t > slots
Definition runtime.h:152
std::atomic< size_t > transfer_tasks
Definition runtime.h:153
std::atomic< size_t > buffer_pumps
Definition runtime.h:149
std::atomic< size_t > inline_producers
Definition runtime.h:150
std::atomic< size_t > slot_pumps
Definition runtime.h:148
std::atomic< size_t > peak_writer_groups
Definition runtime.h:157
std::atomic< size_t > queue_readers
Definition runtime.h:151
std::atomic< size_t > bus_pumps
Definition runtime.h:147
std::atomic< size_t > virtual_groups
Definition runtime.h:154