MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
MayaFlux::Core::StreamBackend< Transport > Class Template Reference

Connection-oriented reliable message transport over an Asio stream protocol. More...

#include <StreamBackend.hpp>

Inheritance diagram for MayaFlux::Core::StreamBackend< Transport >:
Collaboration diagram for MayaFlux::Core::StreamBackend< Transport >:

Classes

struct  ConnectionState
 One connection. More...
struct  ListenerState

Public Types

using Config = typename Transport::Config

Public Member Functions

void close_endpoint (uint64_t endpoint_id) override
 Close an endpoint and release its resources.
EndpointState get_endpoint_state (uint64_t endpoint_id) const override
 Query the current state of an endpoint.
std::vector< EndpointInfo > get_endpoints () const override
 List all endpoints currently managed by this backend.
std::string get_name () const override
NetworkTransport get_transport () const override
std::string get_version () const override
size_t get_write_backlog (uint64_t endpoint_id) const override
 Bytes accepted by send and not yet written to the peer.
bool initialize () override
 Initialise backend resources (sockets, SHM segments, etc.).
bool is_initialized () const override
bool is_running () const override
uint64_t open_endpoint (const EndpointInfo &info) override
 Open a new endpoint.
StreamBackend & operator= (const StreamBackend &)=delete
StreamBackend & operator= (StreamBackend &&)=delete
bool send (uint64_t endpoint_id, const uint8_t *data, size_t size) override
 Send data through an endpoint.
bool send_break (uint64_t endpoint_id) override
 Hold the transmit line of an open serial endpoint in break.
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.
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.
void set_endpoint_id_allocator (std::function< uint64_t()> allocator) override
 Set the endpoint id allocator (called by NetworkSubsystem).
void set_receive_callback (NetworkReceiveCallback callback) override
 Register the receive callback.
void set_state_callback (EndpointStateCallback callback) override
 Register the endpoint state change callback.
void shutdown () override
 Release all resources, close all endpoints.
void start () override
 Start receive threads and accept connections.
void stop () override
 Stop receive threads without releasing resources.
 StreamBackend (const Config &config, asio::io_context &context)
 Construct with config and a reference to the shared io_context.
 StreamBackend (const StreamBackend &)=delete
 StreamBackend (StreamBackend &&)=delete
 ~StreamBackend () override
Public Member Functions inherited from MayaFlux::Core::INetworkBackend
virtual ~INetworkBackend ()=default

Private Types

using ConnectionPtr = std::shared_ptr<ConnectionState>
using ConnectionTable = Memory::FlatMap<uint64_t, ConnectionPtr>
using ListenerPtr = std::shared_ptr<ListenerState>
using ListenerTable = Memory::FlatMap<uint64_t, ListenerPtr>
using Stream = typename Transport::Stream

Private Member Functions

void cancel_timers (ConnectionState &conn)
void close_listener (ListenerState &listener)
void drop_queued_writes (ConnectionState &conn)
void enqueue_write (const ConnectionPtr &conn, ConnectionState::Frame frame)
ConnectionPtr find_connection (uint64_t endpoint_id) const
ListenerPtr find_listener (uint64_t endpoint_id) const
void finish_open (const ConnectionPtr &conn)
void on_bytes_received (const ConnectionPtr &conn, const asio::error_code &ec, size_t bytes)
void on_connect_complete (const ConnectionPtr &conn, const asio::error_code &ec)
void on_connection_error (const ConnectionPtr &conn, const asio::error_code &ec)
void schedule_reconnect (const ConnectionPtr &conn)
void start_accept (const ListenerPtr &listener)
void start_connect (const ConnectionPtr &conn)
void start_receive_chain (const ConnectionPtr &conn)
void start_write (const ConnectionPtr &conn)
void transition_state (ConnectionState &conn, EndpointState new_state)

Static Private Member Functions

static constexpr FramingPolicy resolve_framing (FramingPolicy framing)

Private Attributes

std::function< uint64_t()> m_allocate_endpoint_id
Config m_config
Memory::SnapshotCell< ConnectionTable > m_connections
asio::io_context & m_context
std::atomic< bool > m_initialized { false }
Memory::SnapshotCell< ListenerTable > m_listeners
NetworkReceiveCallback m_receive_callback
std::atomic< bool > m_running { false }
EndpointStateCallback m_state_callback

Static Private Attributes

static constexpr size_t k_default_read_size = size_t { 64 } * 1024

Detailed Description

template<typename Transport>
class MayaFlux::Core::StreamBackend< Transport >

Connection-oriented reliable message transport over an Asio stream protocol.

Everything that does not depend on the stream type lives here: listener and connection bookkeeping, async accept, connect and reconnect, the framed receive chain and the framed send. A Transport policy supplies what differs, so TCP and Unix domain sockets are two instances of one backend.

A Transport provides:

  • Stream: the connection's Asio stream, with async_read_some, close and asio::async_write (a protocol's socket, or asio::serial_port).
  • Config: a struct with auto_reconnect and reconnect_interval_ms.
  • id, label, name: the NetworkTransport, a log label and the backend name.
  • automatic_framing: what FramingPolicy::AUTO means.
  • describe(info) for logs and peer_label(info) for the sender string of a receive.
  • listens: whether the transport has listeners. If so, also Protocol (an Asio stream protocol), Bound (what a listener holds while bound, default constructible), is_listener(info), bind(acceptor, info), release(bound) and describe_accepted(socket, listener, accepted).
  • Either connect_target(info), which names where async_connect goes, or open(stream, info), a synchronous open returning an asio::error_code.

With a synchronous open, open_endpoint returns 0 when the first open fails and auto_reconnect is off. With it on, the endpoint enters RECONNECTING and retries.

A transport may also provide, each optional:

  • settle_time(info): how long the endpoint stays OPENING after the open, before reads begin, for boards that restart on open.
  • ready(stream, info): called as the endpoint becomes OPEN, after any settle time.
  • set_control_lines(stream, dtr, rts) and send_break(stream), each returning bool, behind INetworkBackend::set_control_lines and send_break. They run on the caller's thread against an OPEN endpoint and return false otherwise.

Endpoints are listeners or connections. A listener announces each accepted connection through the state callback as a new endpoint whose parent_id is the listener. Messages are delimited by EndpointInfo::framing, chosen per endpoint and inherited by a listener's connections. AUTO and LENGTH_PREFIX are a four byte big-endian length followed by the payload, where a zero length, or one above max_message_size (64 MiB by default), closes the connection. LINE delivers each LF terminated line as a message and drops a line over max_message_size (1 MiB by default) without closing the connection. NONE is raw bytes: each read is delivered as one message with no boundaries, and a send writes its payload as it is. CHUNKED is refused.

All I/O is async on the shared io_context. The connection and listener tables are lock free snapshots and no lock or guard is held while a callback runs, so a callback may send, close an endpoint or open another from inside itself.

send encodes the frame on the caller's thread and posts it to the io thread, where each connection keeps a queue with one write in flight, so frames from any number of threads reach the peer whole and in the order they were posted. It returns true once the frame is accepted, and false when the connection is not open, the payload cannot be encoded, or the peer has left more than four times max_message_size unread (256 MiB by default). A failed write is reported through the state callback and drops what was still queued.

Definition at line 158 of file StreamBackend.hpp.


The documentation for this class was generated from the following file: