Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifically. More...

Namespaces
namespace	error
	Analogous to ipc::transport::error but applies to the sub-namespace ipc::transport::struc – errors having to do with structured messaging.

namespace	shm
	Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::struc proper – most notably the concepts ipc::transport::struc::Struct_builder and ipc::transport::struc::Struct_reader – and items related to them.

namespace	stat
	Stats-related sub-namespace, for ADL segregation and general organization.

namespace	sync_io
	`sync_io`-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport::struc.

Classes
class	Capped_sz_capnp_message_builder
	Simple utility: a capnp `MessageBuilder` operating over a single, contiguous, user-supplied area in virtual memory. More...

class	Capped_sz_capnp_message_reader
	Simple utility: a capnp `MessageReader` operating over a single, contiguous, user-supplied area in virtual memory. More...

class	Channel
	Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel over which unstructured messages and optionally native handles can be transported), this template is the central pillar of the ipc::transport::struc (structured layer), capable of communicating structured capnp-schema-based messages (and native handles). More...

class	Channel_base
	`Channel` base that contains non-parameterized items such as tag types and constants. More...

class	Heap_fixed_builder
	~Simplest possible impl of Struct_builder concept that represents the capnp payload directly in heap memory (outer serialization only), with a segment-allocation strategy similar to `capnp::MallocMessageBuilder`. More...

class	Heap_fixed_builder_capnp_message_builder
	A `capnp::MessageBuilder` used by Heap_fixed_builder: similar to a `capnp::MallocMessageBuilder` (albeit with somewhat different accounting/knobs) and with framing/header space around the allocated segment(s). More...

class	Heap_reader
	Implements Struct_reader concept by straightforwardly interpreting a serialization by Heap_fixed_builder or any other builder that produces segments directly readable via `SegmentArrayMessageReader`. More...

class	Msg_in
	A structured in-message instance suitable as received and emittable (to user) by struc::Channel. More...

class	Msg_out
	A structured out-message suitable to be sent via struc::Channel::send() (et al). More...

struct	Null_session
	Value for Struct_builder::Session when no extra information is needed when serializing Struct_builder for subsequent sending to another process. More...

struct	Ostreamable_capnp_brief
	Proxy object referring to a capnp `Reader` for straightforward output via overloaded `ostream<<`: one-line/potentially-truncated form. More...

struct	Ostreamable_capnp_full
	Proxy object referring to a capnp `Reader` for straightforward output via overloaded `ostream<<`: multi-line/pretty-printed/indented/full-length form. More...

struct	Split_segment
	Simple structure describing how a pre-split single segment was turned into 2+ post-split component sub-segments. More...

class	Struct_builder
	A documentation-only concept defining the behavior of an object capable of zero-copy-serializing, similar to `capnp::MessageBuilder` but geared to transmission over pipe-like IPC transports. More...

class	Struct_reader
	A documentation-only concept that is, conceptually, roughly what `capnp::MessageReader` is to `capnp::MessageBuilder`, to be used on an in-message serialized by a counterpart Struct_builder, having been transmitted over an IPC transmitter of blobs. More...

Typedefs
template<typename Channel_obj , typename Msg_body_t >
using	Channel_via_heap = Channel< Channel_obj, Msg_body_t, Heap_fixed_builder::Config, Heap_reader::Config >
	Convenience alias: Use this when constructing a struc::Channel with tag Channel_base::S_SERIALIZE_VIA_HEAP. More...

using	Session_token = boost::uuids::uuid
	A type used by struc::Channel for internal safety/security/auth needs. More...

using	Segment_ptrs = std::vector< flow::util::Blob_sans_log_context * >
	Sequence of 1+ segment descriptions, each representing a live writable segment (of a capnp serialization of a capnp-`struct`) and optional header/prefix area immediately preceding it. More...

using	Segment_bufs = std::vector< util::Blob_const >
	Simpler cousin of Segment_ptrs, this represents the IPC-transmissible representation of a capnp serialization of a capnp-`struct` including any framing header(s), expressed as simply a sequence of N read-only views, each containing a pointer to header-if-any-followed-by-serialization-segment and the size in bytes thereof. More...

using	Split_segments = std::vector< Split_segment >
	A simple data structure describing the segments (if any) in a Segment_bufs (or similar) structure which had to be split (presumably due to size constraints); by following the indices/sizes into a post-split Segment_bufs one can join the appropriate elements so as to obtain the original pre-split segments. More...

using	Segment_blob_in = flow::util::Blob_sans_log_context
	Short-hand for a high-performance blob structure that represents an IPC-incoming (sub-)segment 1+ of which make up the outer serialization of a given Msg_in. More...

using	msg_id_t = uint64_t
	Message ID uniquely identifying outgoing message (Msg_out, among all other `Msg_out`s), per channel; and similarly incoming message (Msg_in, among `Msg_in`s), per channel. More...

using	Capnp_msg_builder_interface = ::capnp::MessageBuilder
	Alias for capnp's MessageBuilder interface. Rationale: as part of our API, we use our identifier style.

using	Capnp_msg_reader_interface = ::capnp::MessageReader
	Alias for capnp's MessageReader interface. Rationale: as part of our API, we use our identifier style.

Functions
std::ostream &	operator<< (std::ostream &os, const Heap_fixed_builder &val)
	Prints string representation of the given `Heap_fixed_builder` to the given `ostream`. More...

std::ostream &	operator<< (std::ostream &os, const Heap_reader &val)
	Prints string representation of the given `Heap_reader` to the given `ostream`. More...

template<typename Body_t , typename Struct_builder_t >
std::ostream &	operator<< (std::ostream &os, const Msg_out< Body_t, Struct_builder_t > &val)
	Prints string representation of the given `Msg_out` to the given `ostream`. More...

template<typename Body_t , typename Reader_config_t >
std::ostream &	operator<< (std::ostream &os, const Msg_in< Body_t, Reader_config_t > &val)
	Prints string representation of the given `Msg_in` to the given `ostream`. More...

template<typename Capnp_reader >
Ostreamable_capnp_brief< Capnp_reader >	ostreamable_capnp_brief (const Capnp_reader &capnp_reader)
	Convenience function that returns an object passable to `ostream<<` to print a one-line/potentially-truncated representation to that stream, given an arbitrary capnp `Reader`. More...

template<typename Capnp_reader >
Ostreamable_capnp_full< Capnp_reader >	ostreamable_capnp_full (const Capnp_reader &capnp_reader)
	Convenience function that returns an object passable to `ostream<<` to print a multi-line/pretty-printed/indented/full-length representation to that stream, given an arbitrary capnp `Reader`. More...

template<typename Capnp_reader >
std::ostream &	operator<< (std::ostream &os, const Ostreamable_capnp_brief< Capnp_reader > &val)
	Prints string representation (one-line/potentially-truncated form) of the given capnp `Reader`, via proxy object, to the given `ostream`. More...

template<typename Capnp_reader >
std::ostream &	operator<< (std::ostream &os, const Ostreamable_capnp_full< Capnp_reader > &val)
	Prints string representation (multi-line/pretty-printed/indented/full-length form) of the given capnp `Reader`, via proxy object, to the given `ostream`. More...

template<typename Owned_channel_t , typename Msg_body_t , typename Builder_config_t , typename Reader_config_t >
std::ostream &	operator<< (std::ostream &os, const Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t > &val)
	Prints string representation of the given struc::Channel to the given `ostream`. More...

Variables
const Session_token	NULL_SESSION_TOKEN = boost::uuids::nil_uuid()
	A value for which `.is_nil()` is true.

const Null_session	NULL_SESSION
	The only necessary value of empty-type Null_session.

Detailed Description

Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifically.

See ipc::transport doc header. As that notes, the big daddy here is struc::Channel.

See also: The guided Manual chapters Structured Message Transport (Structured Channels) and Structured Message Transport: Messages As Long-lived Data Structures / Advanced Topics cover these topics.

Be aware of sub-namespace ipc::transport::struc::shm which concerns itself with end-to-end-zero-copyable messages leveraging in-SHM storage. Normally there's no need for the user to know or worry about it, but for advanced applications, particularly extensions and customizations, one might delve into this area of the code. Otherwise it'll be used silently as important glue between various systems. Your journey would likely start with the struc::Builder concept doc header which would then lead you to struc::shm::Builder impl. That might lead you to specific SHM-providers like ipc::shm::classic.

Typedef Documentation

◆ Channel_via_heap

template<typename Channel_obj , typename Msg_body_t >

using ipc::transport::struc::Channel_via_heap = typedef Channel<Channel_obj, Msg_body_t, Heap_fixed_builder::Config, Heap_reader::Config>

Convenience alias: Use this when constructing a struc::Channel with tag Channel_base::S_SERIALIZE_VIA_HEAP.

See Channel_base::Serialize_via_heap doc header for when/how to use.

Tip: Sync_io_obj member alias will get you the sync_io-pattern counterpart.

◆ msg_id_t

using ipc::transport::struc::msg_id_t = typedef uint64_t

Message ID uniquely identifying outgoing message (Msg_out, among all other Msg_outs), per channel; and similarly incoming message (Msg_in, among Msg_ins), per channel.

0 is a sentinel value and not a valid user message ID. A message ID pertains to a sent or received instance of a user-created Msg_out (and its in-message counterpart Msg_in). A given Msg_out can be sent 2+ times through a given struc::Channel and even a different struc::Channel; a different message ID will pertain to each of those times for a given struc::Channel. Therefore there is no msg_id_t inside a user Msg_out.

This type is in the public API, as the message ID is made available in certain contexts for:

referring to an earlier-sent message, such as in struc::Channel::undo_expect_responses(); and
logging/reporting.

◆ Segment_blob_in

using ipc::transport::struc::Segment_blob_in = typedef flow::util::Blob_sans_log_context

Short-hand for a high-performance blob structure that represents an IPC-incoming (sub-)segment 1+ of which make up the outer serialization of a given Msg_in.

Its exact semantics are context-dependent, so it's best to read the API or context to determine such details.

◆ Segment_bufs

using ipc::transport::struc::Segment_bufs = typedef std::vector<util::Blob_const>

Simpler cousin of Segment_ptrs, this represents the IPC-transmissible representation of a capnp serialization of a capnp-struct including any framing header(s), expressed as simply a sequence of N read-only views, each containing a pointer to header-if-any-followed-by-serialization-segment and the size in bytes thereof.

Note that while Segment_ptrs contains info on header size, this Segment_bufs does not: So to properly interpret the given Blob_const element, one must know the size of the header therein (if any; by convention we can say that no header => header size is 0 => segment = entire Blob_const).

◆ Segment_ptrs

using ipc::transport::struc::Segment_ptrs = typedef std::vector<flow::util::Blob_sans_log_context*>

Sequence of 1+ segment descriptions, each representing a live writable segment (of a capnp serialization of a capnp-struct) and optional header/prefix area immediately preceding it.

As of this writing this is specifically 1+ Basic_blob pointers to blobs that directly represent those segments+header(s) which must stay alive while these pointers may be dereferenced. In each Basic_blob [begin(), end()) is the serialization segment itself; and space before begin() (of size start()) may be reserved for framing prefix/header to preserve zero-copy when transmitting such serializations over an IPC "wire." (Area after end() up to capacity() could represent a framing postfix, though as of this writing we assume only a header might exist, for simplicity. As long as possible we shall avoid adding a postfix into the design.)

Rationale

Why represent the segment+header as Basic_blob specifically? Answer: The relevant serialization engine(s) could internally represent data structures (namely segments and frame-prefix and such) however they want, and indeed by choosing Basic_blob* here essentially we force that impl to be specifically that. That is a very reasonable structure (and less-feature-filled, slightly-higher-performing than the derivative Blob), but why force it? Indeed, as regards a public API, something merely describing locations and sizes inside the data structure of choice would be stylistically more direct and therefore more flexible/better. To wit Segment_bufs (sequence of pointer + size pairs essentially) is almost such a thing; just it's not quite enough, because it does not directly/intuitively represent the header/prefix areas that might precede segments (but instead merely the segments themselves). So we choose Basic_blob* simply because it is (1) a decent choice for all impls in practice and (2) sufficiently-well describes both segments and frame headers nearby. It is slightly inflexible but acceptable overall.

Todo:: As per nearby Rationale comment, Segment_ptrs element type would ideally be a view into Blob-or-similar instead of actual Basic_blob*, to decouple impl from API more cleanly. One approach might be to develop a flow::util class/template, a peer of the flow::util::Blob hierarchy, that specifically represents a view into a Blob-type-thing (perhaps 1 variant for mutable, 1 variant for immutable), perhaps analogously to how span<uint8_t> + span<const uint8_t> is each a view into vector<uint8_t> (minus the latter's capacity). It would therefore store a pointer, a size, a capacity, and a start-index – representing a main buffer (size() in size), N-byte header/prefix (N = start()), and M-byte postfix (M = capacity() - start() - size()). (A more economical buffer+header version – directly applicable here – might store all of those minus the capacity, meaning there is no postfix area.) Possible names might be Blob_view_const (read-only view into buffer plus header plus postfix), Blob_view_mutable (same plus writable access), Prefixed_byte_span_const (Blob_view_const minus postfix area), Prefixed_byte_span_mutable (Blob_view_mutable minus postfix area). Segment_ptrs would likely be vector<Prefixed_byte_span_mutable>.

◆ Session_token

using ipc::transport::struc::Session_token = typedef boost::uuids::uuid

A type used by struc::Channel for internal safety/security/auth needs.

See in particular struc::Channel constructors, both the regular-channel one and the session-master-channel one. That said: The user of ipc::transport (aided by ipc::session) structured layer shall generally be unconcerned with this, in practice, as ipc::session machinery will take care of:

setting up the session master struc::Channel which will generate this token during initial setup (log-in); and
setting up further struc::Channels as requested by the user (the preceding bullet's token shall be passed to each new struc::Channel and expected internally in all messages).

However, if one plans to create a struc::Channel directly (as ipc::session does), then one must have some limited understanding of this guy's existence (if not the internal details).

◆ Split_segments

using ipc::transport::struc::Split_segments = typedef std::vector<Split_segment>

A simple data structure describing the segments (if any) in a Segment_bufs (or similar) structure which had to be split (presumably due to size constraints); by following the indices/sizes into a post-split Segment_bufs one can join the appropriate elements so as to obtain the original pre-split segments.

The order of Split_segments is strictly from left to right. A reasonable join algorithm, therefore, would iterate over a Split_segments in reverse order; for each Split_segment join the 2+ segments in the post-split Segment_bufs (or similar) described therein, in-place. By doing this in reverse order, handling Split_segment A before B will not invalidate the start-index member in B.

By convention Split_segments shall include a Split_segment only if a segment actually needed to be split.

Function Documentation

◆ operator<<() [1/7]

template<typename Owned_channel_t , typename Msg_body_t , typename Builder_config_t , typename Reader_config_t >

std::ostream & operator<<	(	std::ostream &	os,
		const Channel< Owned_channel_t, Msg_body_t, Builder_config_t, Reader_config_t > &	val
	)

Prints string representation of the given struc::Channel to the given ostream.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator<<() [2/7]

std::ostream & operator<<	(	std::ostream &	os,
		const Heap_fixed_builder &	val
	)

Prints string representation of the given Heap_fixed_builder to the given ostream.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator<<() [3/7]

std::ostream & operator<<	(	std::ostream &	os,
		const Heap_reader &	val
	)

Prints string representation of the given Heap_reader to the given ostream.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator<<() [4/7]

template<typename Body_t , typename Reader_config_t >

std::ostream & operator<<	(	std::ostream &	os,
		const Msg_in< Body_t, Reader_config_t > &	val
	)

Prints string representation of the given Msg_in to the given ostream.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator<<() [5/7]

template<typename Body_t , typename Struct_builder_t >

std::ostream & operator<<	(	std::ostream &	os,
		const Msg_out< Body_t, Struct_builder_t > &	val
	)

Prints string representation of the given Msg_out to the given ostream.

Namely it prints via Msg_out::to_ostream(); be sure to read perf notes on that!

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator<<() [6/7]

template<typename Capnp_reader >

std::ostream & ipc::transport::struc::operator<<	(	std::ostream &	os,
		const Ostreamable_capnp_brief< Capnp_reader > &	val
	)

Prints string representation (one-line/potentially-truncated form) of the given capnp Reader, via proxy object, to the given ostream.

Warning: Potentially the entire underlying capnp tree shall be traversed to make the output work (even if ultimately the output is truncated for length). This can be quite slow. Do not use in perf-critical paths, unless verbose-logging (etc.) is enabled.

See also: ostreamable_capnp_brief(): Wrap your Reader capnp_reader (or builder.asReader()) in this call to make use of this output operator conveniently.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator<<() [7/7]

template<typename Capnp_reader >

std::ostream & ipc::transport::struc::operator<<	(	std::ostream &	os,
		const Ostreamable_capnp_full< Capnp_reader > &	val
	)

Prints string representation (multi-line/pretty-printed/indented/full-length form) of the given capnp Reader, via proxy object, to the given ostream.

Warning: Potentially the entire underlying capnp tree shall be traversed to make the output work. This can be quite slow. Do not use in perf-critical paths, unless verbose-logging (etc.) is enabled.

See also: ostreamable_capnp_full(): Wrap your Reader capnp_reader (or builder.asReader()) in this call to make use of this output operator conveniently.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ ostreamable_capnp_brief()

template<typename Capnp_reader >

Ostreamable_capnp_brief< Capnp_reader > ipc::transport::struc::ostreamable_capnp_brief ( const Capnp_reader & capnp_reader )

Convenience function that returns an object passable to ostream<< to print a one-line/potentially-truncated representation to that stream, given an arbitrary capnp Reader.

Parameters

capnp_reader The Reader to presumably print. Tip: if you have a Builder builder to print then pass builder.asReader() here.

Returns: See above.

◆ ostreamable_capnp_full()

template<typename Capnp_reader >

Ostreamable_capnp_full< Capnp_reader > ipc::transport::struc::ostreamable_capnp_full ( const Capnp_reader & capnp_reader )

Convenience function that returns an object passable to ostream<< to print a multi-line/pretty-printed/indented/full-length representation to that stream, given an arbitrary capnp Reader.

Parameters

capnp_reader The Reader to presumably print. Tip: if you have a Builder builder to print then pass builder.asReader() here.

Returns: See above.

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ Channel_via_heap

◆ msg_id_t

◆ Segment_blob_in

◆ Segment_bufs

◆ Segment_ptrs

Rationale

◆ Session_token

◆ Split_segments

Function Documentation

◆ operator<<() [1/7]

◆ operator<<() [2/7]

◆ operator<<() [3/7]

◆ operator<<() [4/7]

◆ operator<<() [5/7]

◆ operator<<() [6/7]

◆ operator<<() [7/7]

◆ ostreamable_capnp_brief()

◆ ostreamable_capnp_full()