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 Types
template<typename Msg_resource >
using	Blob_batch_in = Msg_batch_in< Msg_resource, true >
	See `async_receive_*_batch()` argument `batch`. More...

using	Blob_rcv_stats = value
	Return type, typically a `struct`, for blob_receive_stats(). More...

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) async_receive_blob_batch() shall not similarly fail, and (3) neither shall ever 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...

template<typename Msg_resource , typename Task_err >
bool	async_receive_blob_batch (Blob_batch_in< Msg_resource > *batch, bool assume_would_block, Task_err &&on_done_func)
	In PEER state: Asynchronously awaits 1+ discrete message(s) – as sent by the opposing peer via Blob_sender::send_blob() or `"Blob_sender::end_sending()"` – and receives them into the target locations as described by `batch` slots, reliably and in-order. More...

bool	idle_timer_run (util::Fine_duration timeout=default_value)
	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...

Blob_rcv_stats	blob_receive_stats () const
	Returns the accumulated transport statistics as of this call. More...

void	blob_receive_stats_reset ()
	Resets the transport statistics as of this call. 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() or `batch->target_payload_size() < receive_blob_max_size()` in PEER-state async_receive_blob_batch() 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...

static constexpr size_t	S_RCV_BLOB_BATCH_SZ_RECOMMENDATION = value
	All notes from Native_handle_receiver::S_RCV_NATIVE_HANDLE_BATCH_SZ_RECOMMENDATION doc header apply. 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 230 of file blob_transport.hpp.

Member Typedef Documentation

◆ Blob_batch_in

template<typename Msg_resource >

using ipc::transport::Blob_receiver::Blob_batch_in = Msg_batch_in<Msg_resource, true>

See async_receive_*_batch() argument batch.

Definition at line 256 of file blob_transport.hpp.

◆ Blob_rcv_stats

using ipc::transport::Blob_receiver::Blob_rcv_stats = value

Return type, typically a struct, for blob_receive_stats().

In addition: the impl must choose one of the following paths. Note that stat::Blob_rcv_stats defines statistics relevant to any concept impl of Blob_receiver.

This type is stat::Blob_rcv_stats. Therefore, given a value S of this type, you can count on this: using ipc::transport::stat::blob_rcv_stats; assert(&(blob_rcv_stats(S)) == &S).
- That is: your impl adds no stats beyond the concept-level ones.
This type is not stat::Blob_rcv_stats but contains one via some type of composition. Therefore your Blob_receiver impl must be accompanied (in the same namespace, for ADL) with a free function such that this works: using ipc::transport::stat::blob_rcv_stats; const stat::Blob_rcv_stats& core_stats = blob_rcv_stats(S).
- That is: your impl adds some stats on top of the concept-level ones.

Definition at line 272 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.

Additionally, a corollary to counterpart concept Blob_sender requirements: this method shall never yield size_t n_rcvd = 0 to on_done_func(), as it is not allowed to send an empty message (blob). (Native_handle_sender is allowed to do so, but only if such an empty meta-blob is paired with a non-null Native_handle.)

Informal suggestion w/r/t a `Native_handle_sender` that is also a `Blob_sender`

Suppose you have class X (e.g., Native_socket_stream is such a class) that implements both concepts. Suppose an X is on the opposing side of a *this. Then we informally recommend that this async_receive_blob() detect the situation wherein the opposing X:

used send_native_handle(hndl, blob, ...) or equivalent; and
that method or equivalent sent no hndl (e.g., the above method was passed hndl that contained no handle: hndl.null() == true).

It should emit an error in that case. Flow-IPC itself uses error::Code::S_BLOB_RECEIVER_GOT_NON_BLOB.

This is technically not a formal requirement. It's just nice, as it detects a user misbehavior as opposed to an internal impl bug.

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.

◆ async_receive_blob_batch()

template<typename Msg_resource , typename Task_err >

bool ipc::transport::Blob_receiver::async_receive_blob_batch	(	Blob_batch_in< Msg_resource > *	batch,
		bool	assume_would_block,
		Task_err &&	on_done_func
	)

In PEER state: Asynchronously awaits 1+ discrete message(s) – as sent by the opposing peer via Blob_sender::send_blob() or "Blob_sender::*end_sending()" – and receives them into the target locations as described by *batch slots, reliably and in-order.

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

Additionally, a corollary to counterpart concept Blob_sender requirements: this method shall never yield a slot (index idx) such that batch->result_payload_blob(idx) == 0; meaning an empty blob was received. That is because it is not allowed to send an empty message (blob). (Native_handle_sender is allowed to do so, but only if such an empty meta-blob is paired with a non-null Native_handle.)

Template Parameters

Msg_resource	See above.
Task_err	See above.

Parameters

batch	See above. However note that Blob_batch_in<Msg_resource>::result_payload_hndl() (the would-be method itself) shall not exist, as `Blob_batch_in<M>` is `Msg_batch_in<M, true>`; note the `NO_HNDLS = true`.
assume_would_block	See above.
on_done_func	See above.

Returns: Same notes as for async_receive_blob().

◆ blob_receive_stats()

Blob_rcv_stats ipc::transport::Blob_receiver::blob_receive_stats ( ) const

Returns the accumulated transport statistics as of this call.

If not in PEER state returns a zeroed-out stats object.

See also: Blob_rcv_stats doc header about how to obtain a transport::stat::Blob_rcv_stats core from the returned struct.

Thread-safe: can be called concurrently with any other method including async_receive_*(). The returned copy is a consistent snapshot.

Returns: Stats snapshot by value.

◆ blob_receive_stats_reset()

void ipc::transport::Blob_receiver::blob_receive_stats_reset ( )

Resets the transport statistics as of this call.

The formal meaning of a reset is discussed in flow::util::stat doc header. If not in PEER state this is a no-op.

Thread-safe: can be called concurrently with any other method including async_receive_*().

◆ idle_timer_run()

bool ipc::transport::Blob_receiver::idle_timer_run ( util::Fine_duration timeout = default_value )

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) async_receive_blob_batch() shall not similarly fail, and (3) neither shall ever 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 Blob_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() or batch->target_payload_size() < receive_blob_max_size() in PEER-state async_receive_blob_batch() 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_receiver concept doc header; they apply equally here.

Definition at line 247 of file blob_transport.hpp.

◆ S_RCV_BLOB_BATCH_SZ_RECOMMENDATION

constexpr size_t ipc::transport::Blob_receiver::S_RCV_BLOB_BATCH_SZ_RECOMMENDATION = value

staticconstexpr

All notes from Native_handle_receiver::S_RCV_NATIVE_HANDLE_BATCH_SZ_RECOMMENDATION doc header apply.

Definition at line 250 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 236 of file blob_transport.hpp.

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

transport/blob_transport.hpp

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ Blob_batch_in

◆ Blob_rcv_stats

Constructor & Destructor Documentation

◆ Blob_receiver() [1/3]

◆ Blob_receiver() [2/3]

◆ Blob_receiver() [3/3]

◆ ~Blob_receiver()

Member Function Documentation

◆ async_receive_blob()

Informal suggestion w/r/t a Native_handle_sender that is also a Blob_sender

◆ async_receive_blob_batch()

◆ blob_receive_stats()

◆ blob_receive_stats_reset()

◆ idle_timer_run()

◆ operator=()

◆ receive_blob_max_size()

Member Data Documentation

◆ S_BLOB_UNDERFLOW_ALLOWED

◆ S_RCV_BLOB_BATCH_SZ_RECOMMENDATION

◆ S_RESOURCE_TYPE_ID

Informal suggestion w/r/t a `Native_handle_sender` that is also a `Blob_sender`