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

#include <channel.hpp>

Inheritance diagram for ipc::transport::Mqs_channel< SIO, Persistent_mq_handle, Native_handle_sender, Native_handle_receiver >:

[legend]

Collaboration diagram for ipc::transport::Mqs_channel< SIO, Persistent_mq_handle, Native_handle_sender, Native_handle_receiver >:

[legend]

Public Types
using	Mq = Persistent_mq_handle
	Short-hand for the Persistent_mq_handle concrete type used for blobs pipe.

using	Base = Channel< std::conditional_t< SIO, sync_io::Blob_stream_mq_sender< Persistent_mq_handle >, Blob_stream_mq_sender< Persistent_mq_handle > >, std::conditional_t< SIO, sync_io::Blob_stream_mq_receiver< Persistent_mq_handle >, Blob_stream_mq_receiver< Persistent_mq_handle > >, Native_handle_sender, Native_handle_receiver >
	Short-hand for base class.

Public Types inherited from ipc::transport::Channel< std::conditional_t< SIO, sync_io::Blob_stream_mq_sender< Persistent_mq_handle >, Blob_stream_mq_sender< Persistent_mq_handle > >, std::conditional_t< SIO, sync_io::Blob_stream_mq_receiver< Persistent_mq_handle >, Blob_stream_mq_receiver< Persistent_mq_handle > >, Null_peer, Null_peer >
using	Blob_sender_obj = std::conditional_t< SIO, sync_io::Blob_stream_mq_sender< Persistent_mq_handle >, Blob_stream_mq_sender< Persistent_mq_handle > >
	Alias for `Blob_sender` template parameter.

using	Blob_receiver_obj = std::conditional_t< SIO, sync_io::Blob_stream_mq_receiver< Persistent_mq_handle >, Blob_stream_mq_receiver< Persistent_mq_handle > >
	Alias for `Blob_receiver` template parameter.

using	Native_handle_sender_obj = Null_peer
	Alias for `Native_handle_sender` template parameter.

using	Native_handle_receiver_obj = Null_peer
	Alias for `Native_handle_receiver` template parameter.

using	Async_io_obj = Channel< typename Blob_sender_obj::Async_io_obj, typename Blob_receiver_obj::Async_io_obj, typename Native_handle_sender_obj::Async_io_obj, typename Native_handle_receiver_obj::Async_io_obj >
	Assuming S_IS_SYNC_IO_OBJ yields async-I/O counterpart; else yields `Channel<Null_peer, Null_peer, Null_peer, Null_peer>`.

using	Sync_io_obj = Channel< typename Blob_sender_obj::Sync_io_obj, typename Blob_receiver_obj::Sync_io_obj, typename Native_handle_sender_obj::Sync_io_obj, typename Native_handle_receiver_obj::Sync_io_obj >
	Assuming S_IS_ASYNC_IO_OBJ yields `sync_io` counterpart; else yields `Channel<Null_peer, Null_peer, Null_peer, Null_peer>`.

Public Member Functions
	Mqs_channel (flow::log::Logger logger_ptr, util::String_view nickname_str, Mq &&mq_out, Mq &&mq_in, Error_code err_code=0)
	Constructs the Channel in PEER state. More...

	Mqs_channel ()
	Identical to Channel default ctor.

Public Member Functions inherited from ipc::transport::Channel< std::conditional_t< SIO, sync_io::Blob_stream_mq_sender< Persistent_mq_handle >, Blob_stream_mq_sender< Persistent_mq_handle > >, std::conditional_t< SIO, sync_io::Blob_stream_mq_receiver< Persistent_mq_handle >, Blob_stream_mq_receiver< Persistent_mq_handle > >, Null_peer, Null_peer >
	Channel ()
	Default ctor (Channel is in ??? state; intended to be move-assigned). More...

	Channel (flow::log::Logger *logger_ptr, util::String_view nickname_str)
	Constructs Channel in ??? state with the intention to continue initialization via init_blob_pipe() and/or init_native_handle_pipe() call(s). More...

	Channel (Channel &&src)
	Move-constructs from `src`; `src` becomes as-if default-cted (therefore in ??? state). More...

	Channel (const Channel &)=delete
	Copy construction is disallowed.

	~Channel ()
	Destructor: synchronously invokes the destructors for each peer object moved-into `*this` via init_blob_pipe() and/or init_native_handle_pipe(). More...

bool	initialized (bool suppress_log=false) const
	Returns `true` if and only if the required init_blob_pipe() and init_native_handle_pipe() calls have been made, loading exactly the expected peer objects as the template params Blob_sender_obj, Blob_receiver_obj, Native_handle_sender_obj, Native_handle_receiver_obj specify. More...

Channel &	operator= (Channel &&src)
	Move-assigns from `src`; `*this` acts as if destructed; `src` becomes as-if default-cted (therefore in ??? state). More...

Channel &	operator= (const Channel &)=delete
	Copy assignment is disallowed.

Async_io_obj	async_io_obj ()
	Converts a `sync_io`-peer-bearing `this` to a returned async-I/O-peer-bearing new Channel, while `this` becomes as-if default-cted. More...

const Blob_sender_obj *	blob_snd () const
	Pointer to the immutable owned Blob_sender_obj; null if yet initialized. More...

Blob_sender_obj *	blob_snd ()
	Pointer to the mutable owned Blob_sender_obj; null if yet initialized. More...

const Blob_receiver_obj *	blob_rcv () const
	Pointer to the immutable owned Blob_receiver_obj; null if not yet initialized. More...

Blob_receiver_obj *	blob_rcv ()
	Pointer to the mutable owned Blob_receiver_obj; null if not yet initialized. More...

const Native_handle_sender_obj *	hndl_snd () const
	Pointer to the immutable owned Native_handle_sender_obj; null if not yet initialized. More...

Native_handle_sender_obj *	hndl_snd ()
	Pointer to the mutable owned Native_handle_sender_obj; null if not yet initialized. More...

const Native_handle_receiver_obj *	hndl_rcv () const
	Pointer to the immutable owned Native_handle_receiver_obj; null if not yet initialized. More...

Native_handle_receiver_obj *	hndl_rcv ()
	Pointer to the mutable owned Native_handle_receiver_obj; null if not yet initialized. More...

bool	init_blob_pipe (Blob_sender_obj &&snd_and_rcv)
	Completes initialization of the blobs pipe by taking ownership (via move semantics) of an object that is simultaneously the Blob_sender_obj and Blob_receiver_obj for our end of the blobs pipe. More...

bool	init_blob_pipe (Blob_sender_obj &&snd, Blob_receiver_obj &&rcv)
	Completes initialization of the blobs pipe by taking ownership (via move semantics) of separate Blob_sender_obj and Blob_receiver_obj objects for our end of the blobs pipe. More...

bool	init_native_handle_pipe (Native_handle_sender_obj &&snd_and_rcv)
	Analogous to 1-arg init_blob_pipe() but as applied to the handles pipe. More...

bool	init_native_handle_pipe (Native_handle_sender_obj &&snd, Native_handle_receiver_obj &&rcv)
	Analogous to 2-arg init_blob_pipe() but as applied to the handles pipe. More...

size_t	send_blob_max_size () const
	Yields `blob_snd()->` same method. More...

size_t	send_meta_blob_max_size () const
	Yields `hndl_snd()->` same method. More...

size_t	receive_blob_max_size () const
	Yields `blob_rcv()->` same method. More...

size_t	receive_meta_blob_max_size () const
	Yields `hndl_rcv()->` same method. More...

bool	send_blob (const util::Blob_const &blob, Error_code *err_code=0)
	Yields `blob_snd()->` same method. More...

bool	send_native_handle (Native_handle hndl_or_null, const util::Blob_const &meta_blob, Error_code *err_code=0)
	Yields `hndl_snd()->` same method. More...

bool	async_end_sending (Task_err &&on_done_func)
	Performs `hndl_snd()->` and/or `blob_snd()->` same method, synthesizing completion handlers into one if applicable. More...

bool	async_end_sending (Error_code *sync_err_code, Task_err &&on_done_func)
	Performs `hndl_snd()->` and/or `blob_snd()->` same method, synthesizing completions into one if applicable. More...

bool	end_sending ()
	Performs `hndl_snd()->` and/or `blob_snd()->` same method, returning `true` if all (1-2) invoked methods returned `true`; `false` conversely. More...

bool	auto_ping (util::Fine_duration period=boost::chrono::seconds(2))
	Performs `hndl_snd()->` and/or `blob_snd()->` same method, returning `true` if all (1-2) invoked methods returned `true`; `false` conversely. More...

bool	async_receive_blob (Args &&... args)
	Yields `blob_rcv()->` same method. More...

bool	async_receive_native_handle (Args &&... args)
	Yields `hndl_rcv()->` same method. More...

bool	idle_timer_run (util::Fine_duration timeout=boost::chrono::seconds(5))
	Performs `hndl_rcv()->` and/or `blob_rcv()->` same method, returning `true` if all (1-2) invoked methods returned `true`; `false` conversely. More...

bool	replace_event_wait_handles (const Create_ev_wait_hndl_func &create_ev_wait_hndl_func)
	Executes same method on all unique stored peer objects; returns `true` if and only if they all did. More...

bool	start_send_blob_ops (Event_wait_func_t &&ev_wait_func)
	Yields `blob_snd()->` same method. More...

bool	start_send_native_handle_ops (Event_wait_func_t &&ev_wait_func)
	Yields `hndl_snd()->` same method. More...

bool	start_receive_blob_ops (Event_wait_func_t &&ev_wait_func)
	Yields `blob_rcv()->` same method. More...

bool	start_receive_native_handle_ops (Event_wait_func_t &&ev_wait_func)
	Yields `hndl_rcv()->` same method. More...

const std::string &	nickname () const
	Returns nickname, a brief string suitable for logging. More...

Additional Inherited Members
Static Public Attributes inherited from ipc::transport::Channel< std::conditional_t< SIO, sync_io::Blob_stream_mq_sender< Persistent_mq_handle >, Blob_stream_mq_sender< Persistent_mq_handle > >, std::conditional_t< SIO, sync_io::Blob_stream_mq_receiver< Persistent_mq_handle >, Blob_stream_mq_receiver< Persistent_mq_handle > >, Null_peer, Null_peer >
static constexpr bool	S_HAS_2_PIPES
	Useful for generic programming: `true` if and only if types imply both blobs and handles pipes are enabled.

static constexpr bool	S_HAS_BLOB_PIPE_ONLY
	Useful for generic programming: `true` if and only if types imply only the blobs pipe is enabled.

static constexpr bool	S_HAS_NATIVE_HANDLE_PIPE_ONLY
	Useful for generic programming: `true` if and only if types imply only the handles pipe is enabled.

static constexpr bool	S_HAS_BLOB_PIPE
	Useful for generic programming: `true` if and only if types imply at least the blobs pipe is enabled.

static constexpr bool	S_HAS_NATIVE_HANDLE_PIPE
	Useful for generic programming: `true` if and only if types imply at least the handles pipe is enabled.

static constexpr bool	S_IS_SYNC_IO_OBJ
	Useful for generic programming: `true` <=> each non-`Null_peer` peer type (Blob_sender_obj, Blob_receiver_obj, Native_handle_sender_obj, Native_handle_receiver_obj) implements the `sync_io` pattern (by convention living in namespace ipc::transport::sync_io).

static constexpr bool	S_IS_ASYNC_IO_OBJ
	It equals the reverse of S_IS_SYNC_IO_OBJ. More...

Related Functions inherited from ipc::transport::Channel< std::conditional_t< SIO, sync_io::Blob_stream_mq_sender< Persistent_mq_handle >, Blob_stream_mq_sender< Persistent_mq_handle > >, std::conditional_t< SIO, sync_io::Blob_stream_mq_receiver< Persistent_mq_handle >, Blob_stream_mq_receiver< Persistent_mq_handle > >, Null_peer, Null_peer >
std::ostream &	operator<< (std::ostream &os, const Channel< std::conditional_t< SIO, sync_io::Blob_stream_mq_sender< Persistent_mq_handle >, Blob_stream_mq_sender< Persistent_mq_handle > >, std::conditional_t< SIO, sync_io::Blob_stream_mq_receiver< Persistent_mq_handle >, Blob_stream_mq_receiver< Persistent_mq_handle > >, Null_peer, Null_peer > &val)
	Prints string representation of the given `Channel` to the given `ostream`. More...

Detailed Description

template<bool SIO, typename Persistent_mq_handle, typename Native_handle_sender = Null_peer, typename Native_handle_receiver = Null_peer>
class ipc::transport::Mqs_channel< SIO, Persistent_mq_handle, Native_handle_sender, Native_handle_receiver >

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

To use:

Construct, passing in the two MQ peer objects for *this to own.
If and only if you require a handles pipe as well, call init_native_handle_pipe() to complete initialization.

As a result:

send_blob(), async_receive_blob() will work (over MQs).
If one does not call init_native_handle_pipe():
- send_native_handle(), async_receive_native_handle() will not compile.

However it is likely more typical to use Mqs_socket_stream_channel (which extends Mqs_channel) or even more likely its two concrete-type aliases Posix_mqs_socket_stream_channel, Bipc_mqs_socket_stream_channel (and/or sync_io::Posix_mqs_socket_stream_channel, sync_io::Bipc_mqs_socket_stream_channel). Either way init_native_handle_pipe() is then done for the user. If no handles pipe is required, then it is likely one would use Posix_mqs_channel_of_blobs or Bipc_mqs_channel_of_blobs (aliases to Mqs_channel).

Template Parameters

Persistent_mq_handle	Implements that concept.
Native_handle_sender	Implements that concept (in `transport::` or `transport::sync_io::`) if handles pipe enabled; otherwise Null_peer.
Native_handle_receiver	Analogously.
SIO	Selects between `transport::sync_io::` and `transport::` version of held type(s); hence between Channel::S_IS_SYNC_IO_OBJ and Channel::S_IS_ASYNC_IO_OBJ.

Constructor & Destructor Documentation

◆ Mqs_channel()

template<bool SIO, typename Persistent_mq_handle , typename Native_handle_sender , typename Native_handle_receiver >

ipc::transport::Mqs_channel< SIO, Persistent_mq_handle, Native_handle_sender, Native_handle_receiver >::Mqs_channel	(	flow::log::Logger *	logger_ptr,
		util::String_view	nickname_str,
		Mq &&	mq_out,
		Mq &&	mq_in,
		Error_code *	err_code = `0`
	)

explicit

Constructs the Channel in PEER state.

mq_out and mq_in must be suitable for Persistent_mq_handle PEER-state ctor (see it doc header); else behavior is undefined.

If and only if you intend to equip *this with a handles pipe as well, you must call init_native_handle_pipe() to complete initialization.

Error semantics

While the below formally outlines how it all works, informally using this is pretty simple:

If you choose the throwing form (null err_code), then by the nature of C++ *this cannot exist <=> this throws.
If you choose the non-throwing form (non-null err_code), then a truthy *err_code <=> *this is unusable (except to move-to).
Any error is logged.

Formally though:

Firstly: See flow::Error_code docs for error reporting semantics (including the exception/code dichotomy). The bottom line is: If err_code is null, then success <=> this ctor does not throw. If err_code is non-null, then success <=> *err_code is falsy after return. If it is truthy, the *this shall not be used except to invoke destructor or to be moved-to. Otherwise behavior is undefined.

Secondly: The source of error conditions is explicitly the following:

Blob_stream_mq_sender<Mq>(logger_ptr, nickname_str, std::move(mq_out), err_code) may emit an error.
Blob_stream_mq_receiver<Mq>(logger_ptr, nickname_str, std::move(mq_in), err_code) may emit an error.
These are invoked in that order; and if the first fails then the second is not invoked.

Hence the eventualities are as follows:

If neither fails: This ctor will neither throw nor emit a truthy *err_code. Yay!
If one fails: This ctor shall either throw or emit the truthy *err_code associated with the one that did fail. (You cannot know which. Sorry.) Just give up on *this (though technically it can still be moved-to).
Both cannot fail due to the algorithm outlined above.

Parameters

logger_ptr	Logger to use for logging subsequently.
nickname_str	See nickname().
mq_out	Open handle to the underlying MQ for traffic from `this` to opposing peer. The peer object becomes owned by `this` via move. `mq_out` becomes unusable for transmission.
mq_in	Open handle to the underlying MQ for traffic to `this` from* opposing peer. The peer object becomes owned by `*this` via move. `mq_in` becomes unusable for transmission.
err_code	See above.

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

transport/channel.hpp

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Mqs_channel()

Error semantics