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

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.

Definition at line 46 of file blob_transport.hpp.

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_moved See 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

src	Source 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_err See above.

Parameters

on_done_func See 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

period See 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

src	Source 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

blob	A binary blob to send; behavior undefined unless `blob.size() >= 1`.
err_code	See 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.

Member Data Documentation

◆ S_RESOURCE_TYPE_ID

const Shared_name ipc::transport::Blob_sender::S_RESOURCE_TYPE_ID

static

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

Definition at line 52 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_sender() [1/3]

◆ Blob_sender() [2/3]

◆ Blob_sender() [3/3]

◆ ~Blob_sender()

Member Function Documentation

◆ async_end_sending()

◆ auto_ping()

◆ end_sending()

◆ operator=()

◆ send_blob()

◆ send_blob_max_size()

Member Data Documentation

◆ S_RESOURCE_TYPE_ID