Flow-IPC 1.0.2
Flow-IPC project: Public API.
Public Member Functions | Static Public Attributes | List of all members
ipc::transport::Blob_sender Class Reference

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

#include <blob_transport.hpp>

Collaboration diagram for ipc::transport::Blob_sender:
[legend]

Public Member Functions

 Blob_sender ()
 Default ctor: Creates a peer object in NULL (neither connected nor connecting) state. More...
 
 Blob_sender (sync_io::Blob_sender &&sync_io_core_in_peer_state_moved)
 sync_io-core-adopting ctor: Creates a peer object in PEER state by subsuming a sync_io core in that state. More...
 
 Blob_sender (Blob_sender &&src)
 Move-constructs from src; src becomes as-if default-cted (therefore in NULL state). More...
 
 Blob_sender (const Blob_sender &)=delete
 Disallow copying.
 
 ~Blob_sender ()
 Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state, and if it is still active) and cancels any pending completion handlers by invoking them ASAP with error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER. More...
 
Blob_senderoperator= (Blob_sender &&src)
 Move-assigns from src; *this acts as if destructed; src becomes as-if default-cted (therefore in NULL state). More...
 
Blob_senderoperator= (const Blob_sender &)=delete
 Disallow copying.
 
size_t send_blob_max_size () const
 In PEER state: Returns max blob.size() such that send_blob() shall not fail due to too-long payload with error::Code::S_INVALID_ARGUMENT. More...
 
bool send_blob (const util::Blob_const &blob, Error_code *err_code=0)
 In PEER state: Synchronously, non-blockingly sends one discrete message, reliably and in-order, to the opposing peer; the message consists of the provided binary blob (of length at least 1 byte). More...
 
template<typename Task_err >
bool async_end_sending (Task_err &&on_done_func)
 Equivalent to send_blob() but sends a graceful-close message instead of the usual payload; the opposing peer's Blob_receiver shall receive it reliably and in-order via Blob_receiver::async_receive_blob() in the form of Error_code = error::Code::S_RECEIVES_FINISHED_CANNOT_RECEIVE. More...
 
bool end_sending ()
 Equivalent to async_end_sending(F) wherein F() does nothing. More...
 
bool auto_ping ()
 In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level messages that are ignored except that they reset any idle timer as enabled via Blob_receiver::idle_timer_run() (or similar). More...
 

Static Public Attributes

static const Shared_name S_RESOURCE_TYPE_ID
 Shared_name relative-folder fragment (no separators) identifying this resource type. Equals _receiver's.
 

Detailed Description

A documentation-only concept defining the behavior of an object capable of reliably/in-order sending of discrete messages, each containing a binary blob.

This is paired with the Blob_receiver concept which defines reception of such messages.

The concept is exactly identical to Native_handle_sender except that in the latter each message consists of 0-1 native handles and 0-1 binary blobs; whereas here it is always exactly 1 of the latter. More precisely, each message contains 1 binary blob, whose length must be at least 1 byte. You may interpret notes in common-sense fashion; for example send_blob_max_size() here corresponds to send_meta_blob_max_size() there.

Therefore we keep the documentation very light, only pointing out the differences against Native_handle_sender – which are summarized in the preceding paragraph. All other notes from Native_handle_sender apply here.

See also
Native_handle_sender, an identical concept with 1 feature (native handle transmission) added.

Constructor & Destructor Documentation

◆ Blob_sender() [1/3]

ipc::transport::Blob_sender::Blob_sender ( )

Default ctor: Creates a peer object in NULL (neither connected nor connecting) state.

All notes from Native_handle_sender() default ctor doc header apply.

◆ Blob_sender() [2/3]

ipc::transport::Blob_sender::Blob_sender ( sync_io::Blob_sender &&  sync_io_core_in_peer_state_moved)

sync_io-core-adopting ctor: Creates a peer object in PEER state by subsuming a sync_io core in that state.

Parameters
sync_io_core_in_peer_state_movedSee Native_handle_sender concept.

◆ Blob_sender() [3/3]

ipc::transport::Blob_sender::Blob_sender ( Blob_sender &&  src)

Move-constructs from src; src becomes as-if default-cted (therefore in NULL state).

Parameters
srcSource object. For reasonable uses of src after this ctor returns: see default ctor doc header.

◆ ~Blob_sender()

ipc::transport::Blob_sender::~Blob_sender ( )

Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state, and if it is still active) and cancels any pending completion handlers by invoking them ASAP with error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER.

All notes from ~Native_handle_sender() doc header apply.

Member Function Documentation

◆ async_end_sending()

template<typename Task_err >
bool ipc::transport::Blob_sender::async_end_sending ( Task_err &&  on_done_func)

Equivalent to send_blob() but sends a graceful-close message instead of the usual payload; the opposing peer's Blob_receiver shall receive it reliably and in-order via Blob_receiver::async_receive_blob() in the form of Error_code = error::Code::S_RECEIVES_FINISHED_CANNOT_RECEIVE.

All notes from Native_handle_sender::async_end_sending() doc header apply.

Template Parameters
Task_errSee above.
Parameters
on_done_funcSee above.
Returns
See above.

◆ auto_ping()

bool ipc::transport::Blob_sender::auto_ping ( )

In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level messages that are ignored except that they reset any idle timer as enabled via Blob_receiver::idle_timer_run() (or similar).

All notes from Native_handle_receiver::auto_ping() doc header apply.

Parameters
periodSee above.
Returns
See above.

◆ end_sending()

bool ipc::transport::Blob_sender::end_sending ( )

Equivalent to async_end_sending(F) wherein F() does nothing.

All notes from Native_handle_sender::end_sending() doc header apply.

Returns
See above.

◆ operator=()

Blob_sender & ipc::transport::Blob_sender::operator= ( Blob_sender &&  src)

Move-assigns from src; *this acts as if destructed; src becomes as-if default-cted (therefore in NULL state).

No-op if &src == this.

See also
~Blob_sender().
Parameters
srcSource object. For reasonable uses of src after this ctor returns: see default ctor doc header.
Returns
*this.

◆ send_blob()

bool ipc::transport::Blob_sender::send_blob ( const util::Blob_const blob,
Error_code err_code = 0 
)

In PEER state: Synchronously, non-blockingly sends one discrete message, reliably and in-order, to the opposing peer; the message consists of the provided binary blob (of length at least 1 byte).

Providing a null blob results in undefined behavior (assertion may trip).

All notes from Native_handle_sender::send_native_handle() doc header apply.

Parameters
blobA binary blob to send; behavior undefined unless blob.size() >= 1.
err_codeSee above.
Returns
See above.

◆ send_blob_max_size()

size_t ipc::transport::Blob_sender::send_blob_max_size ( ) const

In PEER state: Returns max blob.size() such that send_blob() shall not fail due to too-long payload with error::Code::S_INVALID_ARGUMENT.

Always the same value once in PEER state. The opposing Native_handle_receiver::receive_blob_max_size()` shall return the same value (in the opposing object potentially in a different process).

If *this is not in PEER state (in particular if it is default-cted or moved-from), returns zero; else a positive value.

Returns
See above.

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