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 >:
Collaboration diagram for ipc::transport::Mqs_channel< SIO, Persistent_mq_handle, Native_handle_sender, Native_handle_receiver >:
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... | |
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 >
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
*thisto 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::ortransport::sync_io::) if handles pipe enabled; otherwise Null_peer.Native_handle_receiver Analogously. SIO Selects between transport::sync_io::andtransport::version of held type(s); hence between Channel::S_IS_SYNC_IO_OBJ and Channel::S_IS_ASYNC_IO_OBJ.
Definition at line 1174 of file channel.hpp.
Member Typedef Documentation
◆ Base
template<bool SIO, typename Persistent_mq_handle , typename Native_handle_sender = Null_peer, typename Native_handle_receiver = Null_peer>
| using ipc::transport::Mqs_channel< SIO, Persistent_mq_handle, Native_handle_sender, Native_handle_receiver >::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.
Definition at line 1188 of file channel.hpp.
◆ Mq
template<bool SIO, typename Persistent_mq_handle , typename Native_handle_sender = Null_peer, typename Native_handle_receiver = Null_peer>
| using ipc::transport::Mqs_channel< SIO, Persistent_mq_handle, Native_handle_sender, Native_handle_receiver >::Mq = Persistent_mq_handle |
Short-hand for the Persistent_mq_handle concrete type used for blobs pipe.
Definition at line 1185 of file channel.hpp.
Constructor & Destructor Documentation
◆ Mqs_channel()
template<bool SIO, typename Persistent_mq_handle , typename Native_handle_sender , typename Native_handle_receiver >
|
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++*thiscannot exist <=> this throws. - If you choose the non-throwing form (non-null
err_code), then a truthy*err_code<=>*thisis 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_codeassociated 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 *thisto opposing peer. The peer object becomes owned by*thisvia move.mq_outbecomes unusable for transmission.mq_in Open handle to the underlying MQ for traffic to *thisfrom opposing peer. The peer object becomes owned by*thisvia move.mq_inbecomes unusable for transmission.err_code See above.
Definition at line 2239 of file channel.hpp.
References ipc::transport::Channel< Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver >::init_blob_pipe(), and ipc::transport::Channel< Blob_sender, Blob_receiver, Native_handle_sender, Native_handle_receiver >::initialized().
Here is the call graph for this function:
The documentation for this class was generated from the following file:
- transport/channel.hpp
