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>

Collaboration diagram for ipc::transport::Blob_receiver:

[legend]

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

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

Detailed Description

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.

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

Definition at line 190 of file blob_transport.hpp.

Constructor & Destructor Documentation

◆ Blob_receiver() [1/3]

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.

◆ Blob_receiver() [2/3]

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.

Parameters

sync_io_core_in_peer_state_moved See Native_handle_sender concept.

◆ Blob_receiver() [3/3]

ipc::transport::Blob_receiver::Blob_receiver ( Blob_receiver && src )

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

Parameters

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

◆ ~Blob_receiver()

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.

Member Function Documentation

◆ async_receive_blob()

template<typename Task_err_sz >

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.

Template Parameters

Task_err_sz See above.

Parameters

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.

Returns: See above.

◆ idle_timer_run()

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.

Parameters

timeout See above.

Returns: See above.

◆ operator=()

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.

See also: ~Blob_receiver().

Parameters

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

Returns: *this.

◆ receive_blob_max_size()

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.

Returns: See above.

Member Data Documentation

◆ S_BLOB_UNDERFLOW_ALLOWED

constexpr bool ipc::transport::Blob_receiver::S_BLOB_UNDERFLOW_ALLOWED = 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.

See also: "Blob underflow semantics" in Native_handle_sender concept doc header; they apply equally here.

Definition at line 206 of file blob_transport.hpp.

◆ S_RESOURCE_TYPE_ID

const Shared_name ipc::transport::Blob_receiver::S_RESOURCE_TYPE_ID

static

Shared_name relative-folder fragment (no separators) identifying this resource type. Equals _sender's.

Definition at line 196 of file blob_transport.hpp.

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

transport/blob_transport.hpp

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Blob_receiver() [1/3]

◆ Blob_receiver() [2/3]

◆ Blob_receiver() [3/3]

◆ ~Blob_receiver()

Member Function Documentation

◆ async_receive_blob()

◆ idle_timer_run()

◆ operator=()

◆ receive_blob_max_size()

Member Data Documentation

◆ S_BLOB_UNDERFLOW_ALLOWED

◆ S_RESOURCE_TYPE_ID