Flow-IPC 1.0.2
Flow-IPC project: Public API.
Public Types | Public Member Functions | List of all members
ipc::transport::Mqs_channel< SIO, Persistent_mq_handle, Native_handle_sender, Native_handle_receiver > Class Template Reference

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...
 
Channeloperator= (Channel &&src)
 Move-assigns from src; *this acts as if destructed; src becomes as-if default-cted (therefore in ??? state). More...
 
Channeloperator= (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_objblob_snd () const
 Pointer to the immutable owned Blob_sender_obj; null if yet initialized. More...
 
Blob_sender_objblob_snd ()
 Pointer to the mutable owned Blob_sender_obj; null if yet initialized. More...
 
const Blob_receiver_objblob_rcv () const
 Pointer to the immutable owned Blob_receiver_obj; null if not yet initialized. More...
 
Blob_receiver_objblob_rcv ()
 Pointer to the mutable owned Blob_receiver_obj; null if not yet initialized. More...
 
const Native_handle_sender_objhndl_snd () const
 Pointer to the immutable owned Native_handle_sender_obj; null if not yet initialized. More...
 
Native_handle_sender_objhndl_snd ()
 Pointer to the mutable owned Native_handle_sender_obj; null if not yet initialized. More...
 
const Native_handle_receiver_objhndl_rcv () const
 Pointer to the immutable owned Native_handle_receiver_obj; null if not yet initialized. More...
 
Native_handle_receiver_objhndl_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...
 

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:

As a result:

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_handleImplements that concept.
Native_handle_senderImplements that concept (in transport:: or transport::sync_io::) if handles pipe enabled; otherwise Null_peer.
Native_handle_receiverAnalogously.
SIOSelects 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_ptrLogger to use for logging subsequently.
nickname_strSee nickname().
mq_outOpen 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_inOpen 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_codeSee above.

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