Flow-IPC 1.0.2
Flow-IPC project: Public API.
|
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>
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_sender & | operator= (Blob_sender &&src) |
Move-assigns from src ; *this acts as if destructed; src becomes as-if default-cted (therefore in NULL state). More... | |
Blob_sender & | operator= (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. | |
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.
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.
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.
sync_io_core_in_peer_state_moved | See Native_handle_sender concept. |
ipc::transport::Blob_sender::Blob_sender | ( | Blob_sender && | src | ) |
Move-constructs from src
; src
becomes as-if default-cted (therefore in NULL state).
src | Source object. For reasonable uses of src after this ctor returns: see default ctor doc header. |
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.
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.
Task_err | See above. |
on_done_func | See above. |
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.
period | See above. |
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.
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
.
src | Source object. For reasonable uses of src after this ctor returns: see default ctor doc header. |
*this
. 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.
blob | A binary blob to send; behavior undefined unless blob.size() >= 1 . |
err_code | See above. |
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.