MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
StreamBackend.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "NetworkBackend.hpp"
4
8
9#include <expected>
10
11#if defined(_WIN32) || defined(_WIN64)
12#include <windows.h>
13#endif
14
15#include <asio/io_context.hpp>
16#include <asio/steady_timer.hpp>
17
18#if defined(_WIN32) || defined(_WIN64)
19#ifdef ERROR
20#undef ERROR
21#endif
22#endif
23
24namespace MayaFlux::Core {
25
26namespace detail {
27
30
31 inline StreamFramer make_stream_framer(FramingPolicy framing, size_t max_message_size)
32 {
33 if (framing == FramingPolicy::LINE) {
34 return StreamFramer { std::in_place_type<Transitive::Protocol::LineFramer>,
35 max_message_size != 0 ? max_message_size : Transitive::Protocol::default_max_line };
36 }
37 if (framing == FramingPolicy::NONE) {
38 return StreamFramer { std::in_place_type<Transitive::Protocol::RawChunkFramer> };
39 }
40 return StreamFramer { std::in_place_type<Transitive::Protocol::LengthPrefixFramer>,
41 max_message_size != 0 ? max_message_size : Transitive::Protocol::default_max_frame, true };
42 }
43
44 /**
45 * @brief A transport whose stream opens in one synchronous call instead of async_connect
46 */
47 template <typename Transport>
48 concept SynchronousOpen = requires(typename Transport::Stream& stream, const EndpointInfo& info) {
49 { Transport::open(stream, info) } -> std::same_as<asio::error_code>;
50 };
51
52 /**
53 * @brief A synchronous-open transport that holds the endpoint in OPENING for a while after the open
54 */
55 template <typename Transport>
56 concept HasSettle = requires(const EndpointInfo& info) {
57 { Transport::settle_time(info) } -> std::convertible_to<std::chrono::milliseconds>;
58 };
59
60 /**
61 * @brief A transport that prepares the stream just before the endpoint reports OPEN
62 */
63 template <typename Transport>
64 concept HasReady = requires(typename Transport::Stream& stream, const EndpointInfo& info) {
65 Transport::ready(stream, info);
66 };
67
68 template <typename Transport>
69 concept HasControlLines = requires(typename Transport::Stream& stream, std::optional<bool> level) {
70 { Transport::set_control_lines(stream, level, level) } -> std::same_as<bool>;
71 };
72
73 template <typename Transport>
74 concept HasBreak = requires(typename Transport::Stream& stream) {
75 { Transport::send_break(stream) } -> std::same_as<bool>;
76 };
77
78 /**
79 * @brief What a listener holds, which a transport without listeners does not have
80 */
81 template <typename Transport, bool = Transport::listens>
82 struct AcceptSide {
83 typename Transport::Protocol::acceptor acceptor;
84 typename Transport::Protocol::socket pending_socket;
85 typename Transport::Bound bound;
86
87 explicit AcceptSide(asio::io_context& ctx)
88 : acceptor(ctx)
89 , pending_socket(ctx)
90 {
91 }
92 };
93
94 template <typename Transport>
95 struct AcceptSide<Transport, false> {
96 explicit AcceptSide(asio::io_context&) { }
97 };
98
99}
100
101/**
102 * @class StreamBackend
103 * @brief Connection-oriented reliable message transport over an Asio stream protocol
104 *
105 * Everything that does not depend on the stream type lives here: listener and
106 * connection bookkeeping, async accept, connect and reconnect, the framed receive
107 * chain and the framed send. A Transport policy supplies what differs, so TCP and
108 * Unix domain sockets are two instances of one backend.
109 *
110 * A Transport provides:
111 * - Stream: the connection's Asio stream, with async_read_some, close and
112 * asio::async_write (a protocol's socket, or asio::serial_port).
113 * - Config: a struct with auto_reconnect and reconnect_interval_ms.
114 * - id, label, name: the NetworkTransport, a log label and the backend name.
115 * - automatic_framing: what FramingPolicy::AUTO means.
116 * - describe(info) for logs and peer_label(info) for the sender string of a receive.
117 * - listens: whether the transport has listeners. If so, also Protocol (an Asio stream
118 * protocol), Bound (what a listener holds while bound, default constructible),
119 * is_listener(info), bind(acceptor, info), release(bound) and
120 * describe_accepted(socket, listener, accepted).
121 * - Either connect_target(info), which names where async_connect goes, or
122 * open(stream, info), a synchronous open returning an asio::error_code.
123 *
124 * With a synchronous open, open_endpoint returns 0 when the first open fails and
125 * auto_reconnect is off. With it on, the endpoint enters RECONNECTING and retries.
126 *
127 * A transport may also provide, each optional:
128 * - settle_time(info): how long the endpoint stays OPENING after the open, before
129 * reads begin, for boards that restart on open.
130 * - ready(stream, info): called as the endpoint becomes OPEN, after any settle time.
131 * - set_control_lines(stream, dtr, rts) and send_break(stream), each returning bool,
132 * behind INetworkBackend::set_control_lines and send_break. They run on the
133 * caller's thread against an OPEN endpoint and return false otherwise.
134 *
135 * Endpoints are listeners or connections. A listener announces each accepted
136 * connection through the state callback as a new endpoint whose parent_id is the
137 * listener. Messages are delimited by EndpointInfo::framing, chosen per endpoint
138 * and inherited by a listener's connections. AUTO and LENGTH_PREFIX are a four byte
139 * big-endian length followed by the payload, where a zero length, or one above
140 * max_message_size (64 MiB by default), closes the connection. LINE delivers each LF
141 * terminated line as a message and drops a line over max_message_size (1 MiB by
142 * default) without closing the connection. NONE is raw bytes: each
143 * read is delivered as one message with no boundaries, and a send writes its payload
144 * as it is. CHUNKED is refused.
145 *
146 * All I/O is async on the shared io_context. The connection and listener tables are
147 * lock free snapshots and no lock or guard is held while a callback runs, so a callback
148 * may send, close an endpoint or open another from inside itself.
149 *
150 * send encodes the frame on the caller's thread and posts it to the io thread, where each
151 * connection keeps a queue with one write in flight, so frames from any number of threads
152 * reach the peer whole and in the order they were posted. It returns true once the frame is
153 * accepted, and false when the connection is not open, the payload cannot be encoded, or
154 * the peer has left more than four times max_message_size unread (256 MiB by default). A
155 * failed write is reported through the state callback and drops what was still queued.
156 */
157template <typename Transport>
159public:
160 using Config = typename Transport::Config;
161
162 /**
163 * @brief Construct with config and a reference to the shared io_context
164 * @param config Transport specific configuration.
165 * @param context The io_context owned by NetworkSubsystem.
166 */
167 StreamBackend(const Config& config, asio::io_context& context);
168 ~StreamBackend() override;
169
170 StreamBackend(const StreamBackend&) = delete;
174
175 bool initialize() override;
176 void start() override;
177 void stop() override;
178 void shutdown() override;
179
180 [[nodiscard]] bool is_initialized() const override { return m_initialized.load(); }
181 [[nodiscard]] bool is_running() const override { return m_running.load(); }
182
183 [[nodiscard]] NetworkTransport get_transport() const override { return Transport::id; }
184 [[nodiscard]] std::string get_name() const override { return std::string(Transport::name); }
185 [[nodiscard]] std::string get_version() const override { return "1.0"; }
186
187 uint64_t open_endpoint(const EndpointInfo& info) override;
188 void close_endpoint(uint64_t endpoint_id) override;
189 [[nodiscard]] EndpointState get_endpoint_state(uint64_t endpoint_id) const override;
190 [[nodiscard]] std::vector<EndpointInfo> get_endpoints() const override;
191
192 bool send(uint64_t endpoint_id, const uint8_t* data, size_t size) override;
193 bool send_to(uint64_t endpoint_id, const uint8_t* data, size_t size,
194 const std::string& address, uint16_t port) override;
195
196 [[nodiscard]] size_t get_write_backlog(uint64_t endpoint_id) const override;
197
198 bool set_control_lines(uint64_t endpoint_id, std::optional<bool> dtr, std::optional<bool> rts) override;
199 bool send_break(uint64_t endpoint_id) override;
200
203
204 /**
205 * @brief Set the endpoint id allocator (called by NetworkSubsystem)
206 *
207 * Required for listener-accepted connections that need globally
208 * unique ids. Set before start().
209 */
210 void set_endpoint_id_allocator(std::function<uint64_t()> allocator) override
211 {
212 m_allocate_endpoint_id = std::move(allocator);
213 }
214
215private:
216 static constexpr size_t k_default_read_size = size_t { 64 } * 1024;
217
218 using Stream = typename Transport::Stream;
219
220 /**
221 * One connection. info is fixed once the connection is published, and state, which the
222 * io thread writes and any thread reads, is atomic. The socket, the read buffer and the
223 * framer belong to the io thread. Handlers hold a shared_ptr, so a connection that
224 * close_endpoint removes stays valid until the handlers that still hold it return.
225 */
227 using Frame = std::shared_ptr<const std::vector<uint8_t>>;
228
230 std::atomic<EndpointState> state { EndpointState::CLOSED };
231 std::atomic<bool> closed { false };
232 std::atomic<size_t> pending_bytes { 0 };
234 std::vector<uint8_t> read_buffer;
236 std::unique_ptr<asio::steady_timer> reconnect_timer;
237 std::unique_ptr<asio::steady_timer> settle_timer;
238 std::vector<Frame> outbox;
239 size_t outbox_head {};
240 bool writing {};
241 bool is_outbound {};
242
243 ConnectionState(asio::io_context& ctx, FramingPolicy framing, size_t max_message_size, size_t read_size)
244 : socket(ctx)
245 , read_buffer(read_size != 0 ? read_size : k_default_read_size)
246 , framer(detail::make_stream_framer(framing, max_message_size))
247 {
248 }
249
250 [[nodiscard]] EndpointInfo snapshot() const
251 {
252 EndpointInfo copy = info;
253 copy.state = state.load();
254 return copy;
255 }
256
257 /**
258 * The outbox is a vector with a head index, not a deque: it is touched only by the io
259 * thread, it rarely holds more than a frame or two, and a vector reuses its storage
260 * where a deque allocates a block per few elements, which on MSVC is one per frame.
261 */
262 void push(Frame frame) { outbox.push_back(std::move(frame)); }
263
264 [[nodiscard]] bool has_queued() const { return outbox_head < outbox.size(); }
265
266 [[nodiscard]] const Frame& front() const { return outbox[outbox_head]; }
267
268 void pop()
269 {
270 outbox[outbox_head++].reset();
271 if (outbox_head == outbox.size()) {
272 outbox.clear();
273 outbox_head = 0;
274 } else if (outbox_head >= 64 && outbox_head * 2 >= outbox.size()) {
275 outbox.erase(outbox.begin(), outbox.begin() + static_cast<std::ptrdiff_t>(outbox_head));
276 outbox_head = 0;
277 }
278 }
279 };
280
283 std::atomic<bool> closed { false };
285
286 explicit ListenerState(asio::io_context& ctx)
287 : accept(ctx)
288 {
289 }
290 };
291
292 using ConnectionPtr = std::shared_ptr<ConnectionState>;
293 using ListenerPtr = std::shared_ptr<ListenerState>;
296
298 asio::io_context& m_context;
299
300 std::atomic<bool> m_initialized { false };
301 std::atomic<bool> m_running { false };
302
305
308 std::function<uint64_t()> m_allocate_endpoint_id;
309
310 [[nodiscard]] static constexpr FramingPolicy resolve_framing(FramingPolicy framing)
311 {
312 return framing == FramingPolicy::AUTO ? Transport::automatic_framing : framing;
313 }
314
315 [[nodiscard]] ConnectionPtr find_connection(uint64_t endpoint_id) const;
316 [[nodiscard]] ListenerPtr find_listener(uint64_t endpoint_id) const;
317
318 void close_listener(ListenerState& listener);
320 void start_write(const ConnectionPtr& conn);
321 void drop_queued_writes(ConnectionState& conn);
322 void start_connect(const ConnectionPtr& conn);
323 void on_connect_complete(const ConnectionPtr& conn, const asio::error_code& ec);
324 void finish_open(const ConnectionPtr& conn);
325 void cancel_timers(ConnectionState& conn);
326 void start_accept(const ListenerPtr& listener);
328 void on_bytes_received(const ConnectionPtr& conn, const asio::error_code& ec, size_t bytes);
329 void on_connection_error(const ConnectionPtr& conn, const asio::error_code& ec);
331 void transition_state(ConnectionState& conn, EndpointState new_state);
332};
333
334} // namespace MayaFlux::Core
Abstract interface for network transport backends.
ListenerPtr find_listener(uint64_t endpoint_id) const
void schedule_reconnect(const ConnectionPtr &conn)
void shutdown() override
Release all resources, close all endpoints.
Memory::FlatMap< uint64_t, ListenerPtr > ListenerTable
Memory::SnapshotCell< ConnectionTable > m_connections
void on_connection_error(const ConnectionPtr &conn, const asio::error_code &ec)
void set_receive_callback(NetworkReceiveCallback callback) override
Register the receive callback.
ConnectionPtr find_connection(uint64_t endpoint_id) const
void start() override
Start receive threads and accept connections.
bool send_break(uint64_t endpoint_id) override
Hold the transmit line of an open serial endpoint in break.
StreamBackend(const Config &config, asio::io_context &context)
Construct with config and a reference to the shared io_context.
void cancel_timers(ConnectionState &conn)
StreamBackend(const StreamBackend &)=delete
NetworkTransport get_transport() const override
void close_listener(ListenerState &listener)
bool is_initialized() const override
std::shared_ptr< ConnectionState > ConnectionPtr
void transition_state(ConnectionState &conn, EndpointState new_state)
Memory::SnapshotCell< ListenerTable > m_listeners
StreamBackend & operator=(const StreamBackend &)=delete
void drop_queued_writes(ConnectionState &conn)
StreamBackend & operator=(StreamBackend &&)=delete
void start_write(const ConnectionPtr &conn)
static constexpr FramingPolicy resolve_framing(FramingPolicy framing)
bool is_running() const override
void start_receive_chain(const ConnectionPtr &conn)
void enqueue_write(const ConnectionPtr &conn, ConnectionState::Frame frame)
void set_endpoint_id_allocator(std::function< uint64_t()> allocator) override
Set the endpoint id allocator (called by NetworkSubsystem).
bool send_to(uint64_t endpoint_id, const uint8_t *data, size_t size, const std::string &address, uint16_t port) override
Send data to a specific address through an endpoint.
void close_endpoint(uint64_t endpoint_id) override
Close an endpoint and release its resources.
size_t get_write_backlog(uint64_t endpoint_id) const override
Bytes accepted by send and not yet written to the peer.
std::shared_ptr< ListenerState > ListenerPtr
StreamBackend(StreamBackend &&)=delete
void on_bytes_received(const ConnectionPtr &conn, const asio::error_code &ec, size_t bytes)
EndpointState get_endpoint_state(uint64_t endpoint_id) const override
Query the current state of an endpoint.
std::string get_version() const override
void stop() override
Stop receive threads without releasing resources.
std::string get_name() const override
bool initialize() override
Initialise backend resources (sockets, SHM segments, etc.).
std::vector< EndpointInfo > get_endpoints() const override
List all endpoints currently managed by this backend.
void start_connect(const ConnectionPtr &conn)
Memory::FlatMap< uint64_t, ConnectionPtr > ConnectionTable
bool set_control_lines(uint64_t endpoint_id, std::optional< bool > dtr, std::optional< bool > rts) override
Set the DTR and RTS lines of an open serial endpoint.
bool send(uint64_t endpoint_id, const uint8_t *data, size_t size) override
Send data through an endpoint.
void set_state_callback(EndpointStateCallback callback) override
Register the endpoint state change callback.
void on_connect_complete(const ConnectionPtr &conn, const asio::error_code &ec)
void start_accept(const ListenerPtr &listener)
void finish_open(const ConnectionPtr &conn)
uint64_t open_endpoint(const EndpointInfo &info) override
Open a new endpoint.
Map kept as one sorted vector, cheap to copy.
Definition FlatMap.hpp:21
Lock-free cell holding one immutable snapshot of a value, read without blocking.
Messages with a four byte big-endian length before each payload.
Definition Framing.hpp:203
Splits a byte stream into lines, whatever the chunking.
Definition Framing.hpp:112
A transport that prepares the stream just before the endpoint reports OPEN.
A synchronous-open transport that holds the endpoint in OPENING for a while after the open.
A transport whose stream opens in one synchronous call instead of async_connect.
std::variant< Transitive::Protocol::LengthPrefixFramer, Transitive::Protocol::LineFramer, Transitive::Protocol::RawChunkFramer > StreamFramer
StreamFramer make_stream_framer(FramingPolicy framing, size_t max_message_size)
std::function< void( uint64_t endpoint_id, const uint8_t *data, size_t size, std::string_view sender_addr)> NetworkReceiveCallback
Callback signature for inbound data on an endpoint.
EndpointState
Observable connection state for an endpoint.
NetworkTransport
Identifies the transport protocol a backend implements.
std::function< void( const EndpointInfo &info, EndpointState previous, EndpointState current)> EndpointStateCallback
Callback signature for endpoint state changes.
FramingPolicy
How messages are delimited on the wire.
constexpr size_t default_max_line
Definition Framing.hpp:20
constexpr size_t default_max_frame
Definition Framing.hpp:21
Describes one logical send/receive endpoint managed by a backend.
std::shared_ptr< const std::vector< uint8_t > > Frame
ConnectionState(asio::io_context &ctx, FramingPolicy framing, size_t max_message_size, size_t read_size)
std::unique_ptr< asio::steady_timer > reconnect_timer
std::unique_ptr< asio::steady_timer > settle_timer
void push(Frame frame)
The outbox is a vector with a head index, not a deque: it is touched only by the io thread,...
detail::AcceptSide< Transport > accept
Transport::Protocol::acceptor acceptor
AcceptSide(asio::io_context &ctx)
Transport::Protocol::socket pending_socket
What a listener holds, which a transport without listeners does not have.
The framer for raw streams: every push is one message, with nothing to reassemble.
Definition Framing.hpp:355