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	sync_io
	`sync_io`-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport::struc.

Classes
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 `public` items such as tag types and constants. More...

class	Heap_fixed_builder
	Implements Struct_builder concept by straightforwardly allocating fixed-size segments on-demand in the regular heap and serializing directly inside those segments. More...

class	Heap_fixed_builder_capnp_message_builder
	A `capnp::MessageBuilder` used by Heap_fixed_builder: similar to a `capnp::MallocMessageBuilder` with the FIXED_SIZE alloc-strategy but with framing 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...

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 Message_body >
using	Channel_via_heap = Channel< Channel_obj, Message_body, 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	Capnp_msg_builder_interface = ::capnp::MessageBuilder
	Alias for capnp's MessageBuilder interface. Rationale: as part of our API, we use our identifier style.

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 * >
	Sequence of 1+ `Blob` pointers to blobs which must stay alive while these pointers may be dereferenced, intended here to refer to a capnp serialization of a capnp-`struct`. 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...

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 Message_body , typename Struct_builder_t >
std::ostream &	operator<< (std::ostream &os, const Msg_out< Message_body, Struct_builder_t > &val)
	Prints string representation of the given `Msg_out` to the given `ostream`. More...

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

template<typename Channel_obj , typename Message_body , typename Struct_builder_config , typename Struct_reader_config >
std::ostream &	operator<< (std::ostream &os, const Channel< Channel_obj, Message_body, Struct_builder_config, Struct_reader_config > &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.

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 like 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 Message_body >

using ipc::transport::struc::Channel_via_heap = typedef Channel<Channel_obj, Message_body, 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 countrepart 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_ptrs

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

Sequence of 1+ Blob pointers to blobs which must stay alive while these pointers may be dereferenced, intended here to refer to a capnp serialization of a capnp-struct.

In each Blob [begin(), end()) is the serialization itself; and space before begin() and starting with end() may be reserved for framing prefix/postfix to preserve zero-copy when transmitting such serializations over an IPC "wire."

◆ 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).

Function Documentation

◆ operator<<() [1/5]

template<typename Channel_obj , typename Message_body , typename Struct_builder_config , typename Struct_reader_config >

std::ostream & operator<<	(	std::ostream &	os,
		const Channel< Channel_obj, Message_body, Struct_builder_config, Struct_reader_config > &	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/5]

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/5]

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/5]

template<typename Message_body , typename Struct_reader_config >

std::ostream & operator<<	(	std::ostream &	os,
		const Msg_in< Message_body, Struct_reader_config > &	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/5]

template<typename Message_body , typename Struct_builder_t >

std::ostream & operator<<	(	std::ostream &	os,
		const Msg_out< Message_body, 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.

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ Channel_via_heap

◆ msg_id_t

◆ Segment_ptrs

◆ Session_token

Function Documentation

◆ operator<<() [1/5]

◆ operator<<() [2/5]

◆ operator<<() [3/5]

◆ operator<<() [4/5]

◆ operator<<() [5/5]