Flow-IPC 3.0.0
Flow-IPC project: Full implementation reference.
Namespaces | Classes | Typedefs | Functions
ipc::transport Namespace Reference

Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) between pairs of processes. More...

Namespaces

namespace  asio_local_stream_socket
 Additional (versus boost.asio) APIs for advanced work with local (Unix domain) stream and connected-datagram sockets including transmission of native handles through them; and peer process credentials acquisition.
 
namespace  error
 Namespace containing the ipc::transport module's extension of boost.system error conventions, so that that API can return codes/messages from within its own new set of error codes/messages.
 
namespace  stat
 Stats-related sub-namespace, for ADL segregation and general organization.
 
namespace  struc
 Sub-module of Flow-IPC module ipc::transport providing transmission of structured messages specifically.
 
namespace  sync_io
 sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.
 

Classes

class  Bipc_mq_handle
 Implements the Persistent_mq_handle concept by thinly wrapping bipc::message_queue, which is boost.interprocess's persistent message queue API. More...
 
class  Blob_receiver
 A documentation-only concept defining the behavior of an object capable of reliably/in-order receiving of discrete messages, each containing a binary blob. More...
 
class  Blob_sender
 A documentation-only concept defining the behavior of an object capable of reliably/in-order sending of discrete messages, each containing a binary blob. More...
 
class  Blob_stream_mq_base
 Base of Blob_stream_mq_sender and Blob_stream_mq_receiver containing certain static facilities, particularly for post-abort persistent resource cleanup. More...
 
class  Blob_stream_mq_base_impl
 Internal implementation of Blob_stream_mq_base class template; and common utilities used by Blob_stream_mq_sender_impl and Blob_stream_mq_receiver_impl (static items only as of this writing). More...
 
class  Blob_stream_mq_receiver
 Implements Blob_receiver concept by using an adopted Persistent_mq_handle MQ handle to an MQ (message queue) of that type, such as a POSIX or bipc MQ. More...
 
class  Blob_stream_mq_receiver_base
 Similar to Blob_stream_mq_base but contains non-class-template-parameter-dependent Blob_stream_mq_receiver items. More...
 
class  Blob_stream_mq_receiver_impl
 Internal, non-movable pImpl-lite implementation of Blob_stream_mq_receiver class template. More...
 
class  Blob_stream_mq_sender
 Implements Blob_sender concept by using an adopted Persistent_mq_handle MQ handle to an MQ (message queue) of that type, such as a POSIX or bipc MQ. More...
 
class  Blob_stream_mq_sender_impl
 Internal, non-movable pImpl-lite implementation of Blob_stream_mq_sender class template. More...
 
class  Channel
 Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the other for transmitting native handle+blob combos; hence a Blob_sender + Blob_receiver, a Native_handle_sender + Native_handle_receiver, or both. More...
 
class  Generic_msg_batch_in
 Straightforward Msg_batch_in concept implementation (as taken by API {Blob|Native_handle}_receiver::async_receive_*_batch() concept) usable by any receiver engaging in emulated batching. More...
 
class  Mqs_channel
 A Channel with at least a blobs pipe consisting of two MQs of type Persistent_mq_handle (template arg 1); and possibly a handles pipe as governed by template args 2 and 3 which default to Null_peer (in which case the handles pipe is disabled). More...
 
class  Mqs_socket_stream_channel
 A Channel with a blobs pipe consisting of 2 MQs of type Persistent_mq_handle (template arg); and a handles pipe over a Unix domain socket connection. More...
 
class  Msg_batch_in
 A documentation-only concept defining the behavior of an object that is a key aspect of batch-receiving functionality, namely as arg to Native_handle_receiver::async_receive_native_handle_batch() (if t-param S_NO_HNDLS is false) or Blob_receiver::async_receive_blob_batch() (if NO_HNDLS == true). More...
 
class  Native_handle_receiver
 A documentation-only concept defining the behavior of an object capable of reliably/in-order receiving of discrete messages, each containing a native handle, a binary blob, or both. More...
 
class  Native_handle_sender
 A documentation-only concept defining the behavior of an object capable of reliably/in-order sending of discrete messages, each containing a native handle, a binary blob, or both. More...
 
class  Native_socket_stream
 Implements both Native_handle_sender and Native_handle_receiver concepts by using a Unix domain socket, allowing high-performance but non-zero-copy transmission of discrete messages, each containing a native handle, a binary blob, or both. More...
 
class  Native_socket_stream_acceptor
 A server object that binds to a Shared_name and listens for incoming Native_socket_stream connect attempts to that name; and yields connected-peer sync_io::Native_socket_stream objects, one per counterpart opposing *_connect(). More...
 
class  Native_socket_stream_cfg
 Grouping of compile-type config/knobs (such as type aliases, constants) governing some of the behavior of Native_socket_stream and sync_io::Native_socket_stream, the latter in particular being a core IPC transport in Flow-IPC. More...
 
class  Native_socket_stream_impl
 Internal, non-movable pImpl-lite implementation of Native_socket_stream class. More...
 
class  Native_socket_stream_msg_batch_in
 Msg_batch_in concept implementation for at least sync_io::Native_socket_stream (as taken by APIs Native_socket_stream::async_receive_blob_batch() and Native_socket_stream::async_receive_native_handle_batch()) for high-speed natively batched receiving. More...
 
struct  Native_socket_stream_msg_batch_in_privileged
 This is the friend facade of Native_socket_stream_msg_batch_in that exposes private APIs hidden from public user by providing public access to them; this is used internally by at least sync_io::Native_socket_stream impl. More...
 
class  Null_peer
 Dummy type for use as a template param to Channel when either the blobs pipe or handles pipe is disabled; as well as to mark a given peer object as not having a counterpart form: a sync_io object shall have its using Sync_io_obj = Null_peer and conversely for async-I/O guys and their Async_io_objs. More...
 
class  Persistent_mq_handle
 A documentation-only concept defining the behavior of an object representing a light-weight handle to a message queue, capable of receiving/sending discrete messages in non-blocking/blocking/timed-blocking fashion, as well as some support for polling/waiting and interruptions thereof. More...
 
class  Posix_mq_handle
 Implements the Persistent_mq_handle concept by wrapping the POSIX message queue API (see man mq_overview). More...
 
class  Protocol_negotiator
 A simple state machine that, assuming the opposing side of a comm pathway uses an equivalent state machine, helps negotiate the protocol version to speak over that pathway, given each side being capable of speaking a range of protocol versions and reporting the highest such version to the other side. More...
 
class  Socket_stream_channel
 A Channel with a handles pipe only (no blobs pipe) that uses a Unix domain socket connection as the underlying transport for that pipe. More...
 
class  Socket_stream_channel_of_blobs
 A Channel with a blobs pipe only (no handles pipe) that uses a Unix domain socket connection as the underlying transport for that pipe. More...
 

Typedefs

using Native_handle = util::Native_handle
 Convenience alias for the commonly used type util::Native_handle. More...
 
using Shared_name = util::Shared_name
 Convenience alias for the commonly used type util::Shared_name. More...
 
using Posix_mq_sender = Blob_stream_mq_sender< Posix_mq_handle >
 Convenience alias: Blob_sender via unidirectional POSIX MQ (message queue). More...
 
using Posix_mq_receiver = Blob_stream_mq_receiver< Posix_mq_handle >
 Convenience alias: Blob_receiver via unidirectional POSIX MQ (message queue). More...
 
using Bipc_mq_sender = Blob_stream_mq_sender< Bipc_mq_handle >
 Convenience alias: Blob_sender via unidirectional bipc MQ (message queue). More...
 
using Bipc_mq_receiver = Blob_stream_mq_receiver< Bipc_mq_handle >
 Convenience alias: Blob_receiver via unidirectional bipc MQ (message queue). More...
 
using Posix_mqs_channel_of_blobs = Mqs_channel< false, Posix_mq_handle >
 Convenience alias: Channel peer (Blob_sender, Blob_receiver) at one end of full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs (message queues). More...
 
using Bipc_mqs_channel_of_blobs = Mqs_channel< false, Bipc_mq_handle >
 Convenience alias: Channel peer (Blob_sender, Blob_receiver) at one end of full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs (message queues). More...
 
using Posix_mqs_socket_stream_channel = Mqs_socket_stream_channel< false, Posix_mq_handle >
 Convenience alias: Channel peer (Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver) at one end of a full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs (message queues), transmitting blobs only; and a full-duplex pipe over a Unix domain stream connection, transmitting native-handle-and/or-meta-blob messages. More...
 
using Bipc_mqs_socket_stream_channel = Mqs_socket_stream_channel< false, Bipc_mq_handle >
 Convenience alias: Channel peer (Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver) at one end of a full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional bipc MQs (message queues), transmitting blobs only; and a full-duplex pipe over a Unix domain stream connection, transmitting native-handle-and/or-meta-blob messages. More...
 

Functions

template<typename Msg_resource_t , bool NO_HNDLS>
std::ostream & operator<< (std::ostream &os, const Generic_msg_batch_in< Msg_resource_t, NO_HNDLS > &val)
 Prints string representation of the given Generic_msg_batch_in to the given ostream. More...
 
void swap (Bipc_mq_handle &val1, Bipc_mq_handle &val2)
 Implements Persistent_mq_handle related concept: Swaps two objects. More...
 
std::ostream & operator<< (std::ostream &os, const Bipc_mq_handle &val)
 Prints string representation of the given Bipc_mq_handle to the given ostream. More...
 
template<typename Persistent_mq_handle >
std::ostream & operator<< (std::ostream &os, const Blob_stream_mq_receiver< Persistent_mq_handle > &val)
 Prints string representation of the given Blob_stream_mq_receiver to the given ostream. More...
 
template<typename Persistent_mq_handle >
std::ostream & operator<< (std::ostream &os, const Blob_stream_mq_sender< Persistent_mq_handle > &val)
 Prints string representation of the given Blob_stream_mq_sender to the given ostream. More...
 
std::ostream & operator<< (std::ostream &os, const Null_peer &val)
 Dummy that is never invoked. More...
 
template<typename Blob_sender_t , typename Blob_receiver_t , typename Native_handle_sender_t , typename Native_handle_receiver_t >
std::ostream & operator<< (std::ostream &os, const Channel< Blob_sender_t, Blob_receiver_t, Native_handle_sender_t, Native_handle_receiver_t > &val)
 Prints string representation of the given Channel to the given ostream. More...
 
template<typename Persistent_mq_handle >
std::ostream & operator<< (std::ostream &os, const Blob_stream_mq_receiver_impl< Persistent_mq_handle > &val)
 Prints string representation of the given Blob_stream_mq_receiver_impl to the given ostream. More...
 
template<typename Persistent_mq_handle >
std::ostream & operator<< (std::ostream &os, const Blob_stream_mq_sender_impl< Persistent_mq_handle > &val)
 Prints string representation of the given Blob_stream_mq_sender to the given ostream. More...
 
std::ostream & operator<< (std::ostream &os, const Native_socket_stream_impl &val)
 Prints string representation of the given Native_socket_stream_impl to the given ostream. More...
 
std::ostream & operator<< (std::ostream &os, const Native_socket_stream &val)
 Prints string representation of the given Native_socket_stream to the given ostream. More...
 
std::ostream & operator<< (std::ostream &os, const Native_socket_stream_acceptor &val)
 Prints string representation of the given Native_socket_stream_acceptor to the given ostream. More...
 
template<typename Msg_resource_t >
std::ostream & operator<< (std::ostream &os, const Native_socket_stream_msg_batch_in< Msg_resource_t > &val)
 Prints string representation of the given Native_socket_stream_msg_batch_in to the given ostream. More...
 
void swap (Persistent_mq_handle &val1, Persistent_mq_handle &val2)
 Swaps two objects. More...
 
void swap (Posix_mq_handle &val1, Posix_mq_handle &val2)
 Implements Persistent_mq_handle related concept: Swaps two objects. More...
 
std::ostream & operator<< (std::ostream &os, const Posix_mq_handle &val)
 Prints string representation of the given Posix_mq_handle to the given ostream. More...
 

Detailed Description

Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) between pairs of processes.

See namespace ipc doc header for an overview of Flow-IPC modules including how ipc::transport relates to the others. Then return here. A synopsis follows:

See also
The guided Manual chapters Sessions: Opening Channels (obtaining channels), Structured Message Transport (Structured Channels) and Structured Message Transport: Messages As Long-lived Data Structures / Advanced Topics (structured transport), and Transport Core Layer: Transmitting Unstructured Data (unstructured transport) cover these topics.

The main transport features of ipc::transport are: class template struc::Channel (for structured message and native handle transport) and various lower-level utilities (Channel; blob/handle streams; message queue (MQ) streams). Structured transmission facilities (struc::Channel being the main guy) are segregated in sub-namespace transport::struc.

Generally speaking, to communicate (via struc::Channel and others), the two processes A and B that intend to talk must have established a broad conversation called a session within which all communication occurs. In fact, a transport::struc::Channel wraps a transport::Channel, and the latter can be established, in factory-ish fashion and otherwise, from an ipc::session::Session. Hence, see namespace ipc::session doc header to learn about establishing/terminating sessions. Once you have a session::Session, you can actually use main ipc::transport facilities.

That said: ipc::transport does not require ipc::session to be used: One can instantiate all the various IPC mechanisms therein directly. ipc::session provides the lifecycle and organization to make this as simple as possible (but no simpler). In that sense ipc::transport has the essential building blocks; ipc::session provides access to those building blocks in one possible fashion – for example by establishing a naming convention for the various required Shared_names taken by the various ipc::transport constructors. Formally speaking there can certainly be other fashions of organizing ipc::transport resources. Therefore the API design of ipc::transport is not rigid.

Typedef Documentation

◆ Bipc_mq_receiver

Convenience alias: Blob_receiver via unidirectional bipc MQ (message queue).

Tip: In sync_io sub-namespace there is the sync_io-pattern counterpart.

Definition at line 123 of file transport_fwd.hpp.

◆ Bipc_mq_sender

Convenience alias: Blob_sender via unidirectional bipc MQ (message queue).

Tip: In sync_io sub-namespace there is the sync_io-pattern counterpart.

Definition at line 116 of file transport_fwd.hpp.

◆ Bipc_mqs_channel_of_blobs

Convenience alias: Channel peer (Blob_sender, Blob_receiver) at one end of full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs (message queues).

Tip: In sync_io sub-namespace there is the sync_io-pattern counterpart.

Definition at line 139 of file transport_fwd.hpp.

◆ Bipc_mqs_socket_stream_channel

Convenience alias: Channel peer (Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver) at one end of a full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional bipc MQs (message queues), transmitting blobs only; and a full-duplex pipe over a Unix domain stream connection, transmitting native-handle-and/or-meta-blob messages.

Tip: In sync_io sub-namespace there is the sync_io-pattern counterpart.

Definition at line 159 of file transport_fwd.hpp.

◆ Native_handle

Convenience alias for the commonly used type util::Native_handle.

Definition at line 92 of file transport_fwd.hpp.

◆ Posix_mq_receiver

Convenience alias: Blob_receiver via unidirectional POSIX MQ (message queue).

Tip: In sync_io sub-namespace there is the sync_io-pattern counterpart.

Definition at line 109 of file transport_fwd.hpp.

◆ Posix_mq_sender

Convenience alias: Blob_sender via unidirectional POSIX MQ (message queue).

Tip: In sync_io sub-namespace there is the sync_io-pattern counterpart.

Definition at line 102 of file transport_fwd.hpp.

◆ Posix_mqs_channel_of_blobs

Convenience alias: Channel peer (Blob_sender, Blob_receiver) at one end of full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs (message queues).

Tip: In sync_io sub-namespace there is the sync_io-pattern counterpart.

Definition at line 131 of file transport_fwd.hpp.

◆ Posix_mqs_socket_stream_channel

Convenience alias: Channel peer (Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver) at one end of a full-duplex (bidirectional) pipe composed of 2 opposite-facing unidirectional POSIX MQs (message queues), transmitting blobs only; and a full-duplex pipe over a Unix domain stream connection, transmitting native-handle-and/or-meta-blob messages.

Tip: In sync_io sub-namespace there is the sync_io-pattern counterpart.

Definition at line 149 of file transport_fwd.hpp.

◆ Shared_name

Convenience alias for the commonly used type util::Shared_name.

Definition at line 95 of file transport_fwd.hpp.

Function Documentation

◆ operator<<() [1/13]

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

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 1046 of file bipc_mq_handle.cpp.

◆ operator<<() [2/13]

template<typename Persistent_mq_handle >
std::ostream & operator<< ( std::ostream &  os,
const Blob_stream_mq_receiver< Persistent_mq_handle > &  val 
)

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

If object is default-cted (or moved-from), this will output something graceful indicating this.

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 463 of file blob_stream_mq_rcv.hpp.

◆ operator<<() [3/13]

template<typename Persistent_mq_handle >
std::ostream & operator<< ( std::ostream &  os,
const Blob_stream_mq_receiver_impl< Persistent_mq_handle > &  val 
)

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 389 of file blob_stream_mq_rcv_impl.hpp.

◆ operator<<() [4/13]

template<typename Persistent_mq_handle >
std::ostream & operator<< ( std::ostream &  os,
const Blob_stream_mq_sender< Persistent_mq_handle > &  val 
)

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

If object is default-cted (or moved-from), this will output something graceful indicating this.

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 549 of file blob_stream_mq_snd.hpp.

◆ operator<<() [5/13]

template<typename Persistent_mq_handle >
std::ostream & operator<< ( std::ostream &  os,
const Blob_stream_mq_sender_impl< Persistent_mq_handle > &  val 
)

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 390 of file blob_stream_mq_snd_impl.hpp.

◆ operator<<() [6/13]

template<typename Blob_sender_t , typename Blob_receiver_t , typename Native_handle_sender_t , typename Native_handle_receiver_t >
std::ostream & operator<< ( std::ostream &  os,
const Channel< Blob_sender_t, Blob_receiver_t, Native_handle_sender_t, Native_handle_receiver_t > &  val 
)

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 2527 of file channel.hpp.

◆ operator<<() [7/13]

template<typename Msg_resource_t , bool NO_HNDLS>
std::ostream & operator<< ( std::ostream &  os,
const Generic_msg_batch_in< Msg_resource_t, NO_HNDLS > &  val 
)

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 431 of file batch.hpp.

◆ operator<<() [8/13]

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

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

Friend of Native_socket_stream.

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 182 of file native_socket_stream.cpp.

◆ operator<<() [9/13]

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

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 488 of file native_socket_stream_acceptor.cpp.

◆ operator<<() [10/13]

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

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 236 of file native_socket_stream_impl.cpp.

◆ operator<<() [11/13]

template<typename Msg_resource_t >
std::ostream & operator<< ( std::ostream &  os,
const Native_socket_stream_msg_batch_in< Msg_resource_t > &  val 
)

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 1482 of file native_socket_stream_batch.hpp.

◆ operator<<() [12/13]

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

Dummy that is never invoked.

It must still exist in order for Channel to build successfully with at least 1 Null_peer template arg.

Assertion may trip if this is invoked. Formally behavior is undefined.

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 30 of file channel.cpp.

◆ operator<<() [13/13]

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

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

Parameters
osStream to which to write.
valObject to serialize.
Returns
os.

Definition at line 1397 of file posix_mq_handle.cpp.

◆ swap() [1/3]

void swap ( Bipc_mq_handle &  val1,
Bipc_mq_handle &  val2 
)

◆ swap() [2/3]

void swap ( Persistent_mq_handle &  val1,
Persistent_mq_handle &  val2 
)

Swaps two objects.

Constant-time. Suitable for standard ADL-swap pattern using std::swap; swap(val1, val2);.

Parameters
val1Object.
val2Object.

◆ swap() [3/3]

void swap ( Posix_mq_handle &  val1,
Posix_mq_handle &  val2 
)

Implements Persistent_mq_handle related concept: Swaps two objects.

Parameters
val1Object.
val2Object.

Definition at line 581 of file posix_mq_handle.cpp.

Referenced by ipc::transport::Posix_mq_handle::operator=().

Here is the caller graph for this function: