|
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 receiving of discrete messages, each containing a binary blob. More...
#include <blob_transport.hpp>
Public Member Functions | |
| Blob_receiver () | |
| Default ctor: Creates a peer object in NULL (neither connected nor connecting) state. More... | |
| Blob_receiver (sync_io::Blob_receiver &&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_receiver (Blob_receiver &&src) | |
Move-constructs from src; src becomes as-if default-cted (therefore in NULL state). More... | |
| Blob_receiver (const Blob_receiver &)=delete | |
| Disallow copying. | |
| ~Blob_receiver () | |
| Destroys this peer endpoint which will end the conceptual incoming-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_receiver & | operator= (Blob_receiver &&src) |
Move-assigns from src; *this acts as if destructed; src becomes as-if default-cted (therefore in NULL state). More... | |
| Blob_receiver & | operator= (const Blob_receiver &)=delete |
| Disallow copying. | |
| size_t | receive_blob_max_size () const |
In PEER state: Returns min target_blob.size() such that (1) async_receive_blob() shall not fail with error::Code::S_INVALID_ARGUMENT (only if S_BLOB_UNDERFLOW_ALLOWED is false; otherwise not relevant), and (2) it shall never fail with error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE. More... | |
| template<typename Task_err_sz > | |
| bool | async_receive_blob (const util::Blob_mutable &target_blob, Task_err_sz &&on_done_func) |
In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Blob_sender::send_blob() or "Blob_sender::*end_sending()" – and receives it into the given target locations, reliably and in-order. More... | |
| bool | idle_timer_run (util::Fine_duration timeout) |
| In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is, once at least the specified time has passed since the last received low-level traffic (or this call, whichever most recently occurred), to emit the pipe-hosing error error::Code::S_RECEIVER_IDLE_TIMEOUT. More... | |
Static Public Attributes | |
| static const Shared_name | S_RESOURCE_TYPE_ID |
Shared_name relative-folder fragment (no separators) identifying this resource type. Equals _sender's. | |
| static constexpr bool | S_BLOB_UNDERFLOW_ALLOWED = value |
If false then blob.size() > receive_blob_max_size() in PEER-state async_receive_blob() shall yield non-pipe-hosing error::Code::INVALID_ARGUMENT, and it shall never yield pipe-hosing error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE; else the latter may occur, while the former shall never occur for that reason. More... | |
A documentation-only concept defining the behavior of an object capable of reliably/in-order receiving of discrete messages, each containing a binary blob.
This is paired with the Blob_sender concept which defines sending of such messages.
The concept is exactly identical to Native_handle_receiver 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 receive_blob_max_size() here corresponds to receive_meta_blob_max_size() there.
Therefore we keep the documentation very light, only pointing out the differences against Native_handle_receiver – which are summarized in the preceding paragraph. All other notes from Native_handle_receiver apply here.
| ipc::transport::Blob_receiver::Blob_receiver | ( | ) |
Default ctor: Creates a peer object in NULL (neither connected nor connecting) state.
All notes from Native_handle_receiver() default ctor doc header apply.
| ipc::transport::Blob_receiver::Blob_receiver | ( | sync_io::Blob_receiver && | 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_receiver::Blob_receiver | ( | Blob_receiver && | 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_receiver::~Blob_receiver | ( | ) |
Destroys this peer endpoint which will end the conceptual incoming-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_receiver() doc header apply.
| bool ipc::transport::Blob_receiver::async_receive_blob | ( | const util::Blob_mutable & | target_blob, |
| Task_err_sz && | on_done_func | ||
| ) |
In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Blob_sender::send_blob() or "Blob_sender::*end_sending()" – and receives it into the given target locations, reliably and in-order.
All notes from Native_handle_receiver::async_receive_native_handle() doc header apply. In particular watch out for the semantics regarding target_blob.size() and potential resulting errors.
| Task_err_sz | See above. |
| target_blob | target_blob.data()... shall be written to by the time on_done_func() is executed with a falsy code, bytes numbering N, where N is passed to that callback. N shall not exceed target_blob.size(). See above. |
| on_done_func | See above. |
| bool ipc::transport::Blob_receiver::idle_timer_run | ( | util::Fine_duration | timeout | ) |
In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is, once at least the specified time has passed since the last received low-level traffic (or this call, whichever most recently occurred), to emit the pipe-hosing error error::Code::S_RECEIVER_IDLE_TIMEOUT.
All notes from Native_handle_receiver::idle_timer_run() doc header apply.
| timeout | See above. |
| Blob_receiver & ipc::transport::Blob_receiver::operator= | ( | Blob_receiver && | 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. | size_t ipc::transport::Blob_receiver::receive_blob_max_size | ( | ) | const |
In PEER state: Returns min target_blob.size() such that (1) async_receive_blob() shall not fail with error::Code::S_INVALID_ARGUMENT (only if S_BLOB_UNDERFLOW_ALLOWED is false; otherwise not relevant), and (2) it shall never fail with error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE.
Please see "Blob underflow semantics" (for Native_handle_receiver, but applied in common-sense fashion to us) for explanation of these semantics.
Always the same value once in PEER state. The opposing Native_handle_sender::send_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.
|
staticconstexpr |
If false then blob.size() > receive_blob_max_size() in PEER-state async_receive_blob() shall yield non-pipe-hosing error::Code::INVALID_ARGUMENT, and it shall never yield pipe-hosing error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE; else the latter may occur, while the former shall never occur for that reason.
1.9.4