Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::struc proper – most notably the concepts ipc::transport::struc::Struct_builder and ipc::transport::struc::Struct_reader – and items related to them. More...

Namespaces
namespace	arena_lend
	See parent ipc::transport::struc::shm and at least sub-namespace ipc::transport::struc::shm::arena_lend::jemalloc.

namespace	classic
	As of this writing certain convenience aliases supplied for the SHM-classic SHM-provider as pertains to zero-copy structured message passing with that SHM-provider.

namespace	error
	Analogous to ipc::transport::struc::error but applies to the sub-namespace ipc::transport::struc::shm – errors having to do with structured messaging with zero-copy backed by SHM.

Classes
class	Builder
	Implements Struct_builder concept with maximal zero-copy perf by (1) storing the actual user-schema-controlled message using the SHM provider of choice, in SHM, and (2) straightforwardly allocating 1 segment in regular heap and placing the SHM handle there for transmission over IPC. More...

class	Builder_base
	shm::Builder base that contains non-parameterized `public` items such as tag types and constants. More...

class	Capnp_message_builder
	A `capnp::MessageBuilder` used by shm::Builder: similar to a `MallocMessageBuilder` with the `GROW_HEURISTICALLY` alloc-strategy but allocating via a SHM provider (of template-arg-specific type) in SHM instead of the heap via `malloc()`. More...

class	Reader
	Implements Struct_reader concept by interpreting a serialization by shm::Builder with the same template params. More...

Functions
template<typename Shm_arena >
std::ostream &	operator<< (std::ostream &os, const Capnp_message_builder< Shm_arena > &val)
	Prints string representation of the given `Capnp_message_builder` to the given `ostream`. More...

template<typename Shm_arena >
std::ostream &	operator<< (std::ostream &os, const Builder< Shm_arena > &val)
	Prints string representation of the given `Builder` to the given `ostream`. More...

template<typename Shm_arena >
std::ostream &	operator<< (std::ostream &os, const Reader< Shm_arena > &val)
	Prints string representation of the given `Reader` to the given `ostream`. More...

void	capnp_set_lent_shm_handle (schema::ShmHandle::Builder *shm_handle_root, const flow::util::Blob_sans_log_context &lend_result)
	Utility that saves the result of a `Shm_session1::lend_object<T>(const shared_ptr<T>&)` result into the given capnp-generated `ShmHandle`-typed field. More...

void	capnp_get_shm_handle_to_borrow (const schema::ShmHandle::Reader &shm_handle_root, flow::util::Blob_sans_log_context *arg_to_borrow)
	Utility that's the reverse of capnp_set_lent_shm_handle() to be invoked on the deserializing side. More...

Detailed Description

Segregates zero-copy/SHM implementations of concepts residing in parent namespace ipc::transport::struc proper – most notably the concepts ipc::transport::struc::Struct_builder and ipc::transport::struc::Struct_reader – and items related to them.

This namespace proper is focused on struc::shm::Builder and struc::shm::Reader, templates which enable (in a SHM-provider-parameterized way) zero-copyable structured messages by implementing the aforementioned pair of concepts respectively.

Sub-namespaces, including struc::shm::classic and struc::shm::arena_lend::jemalloc as of this writing, pertain to SHM-provider-specific items relevant (at least) to that pair of templates (Builder and Reader). In particular, e.g., struc::shm::classic::Builder is the concrete type that implements a zero-copy Struct_builder using the ipc::shm::classic SHM-provider (and similarly for Reader). For user convenience and generic coding ease, each SHM-provider shall provide that pair of aliases (Builder and Reader) in a sub-namespace in some reasonable way mirroring the SHM-provider core's namespace path. (Hence note that SHM-classic provider core is in ipc::shm::classic, hence the Builder and Reader aliases are in ipc::transport::struc::shm::classic accordingly.)

(If that didn't read like some sort of comprehensible English, you probably need not worry about it. In particular if you use ipc::session to set up your IPC, you'll have access to higher-level aliases to make it all simple – while internally they'll most likely use the stuff in the preceding paragraph. E.g., ipc::session::shm::classic::Session_mv::Structured_channel is your guy... no Builders or Readers in sight about which you would need to worry.)

Function Documentation

◆ capnp_get_shm_handle_to_borrow()

void ipc::transport::struc::shm::capnp_get_shm_handle_to_borrow	(	const schema::ShmHandle::Reader &	shm_handle_root,
		flow::util::Blob_sans_log_context *	arg_to_borrow
	)

Utility that's the reverse of capnp_set_lent_shm_handle() to be invoked on the deserializing side.

Parameters

shm_handle_root	`ShmHandle` reader to access. Behavior undefined if was not set by capnp_set_lent_shm_handle().
arg_to_borrow	Shall be set to what to pass to `borrow_object<T>()` (non-null pointer or behavior undefined/assertion may trip). `arg_to_borrow->get_logger()` shall not be modified; so set it to what you want, if you want.

◆ capnp_set_lent_shm_handle()

void ipc::transport::struc::shm::capnp_set_lent_shm_handle	(	schema::ShmHandle::Builder *	shm_handle_root,
		const flow::util::Blob_sans_log_context &	lend_result
	)

Utility that saves the result of a Shm_session1::lend_object<T>(const shared_ptr<T>&) result into the given capnp-generated ShmHandle-typed field.

On the deserializing end, one can get back this value via capnp_get_shm_handle_to_borrow() and pass it to Shm_session2::borrow_object<T>() to yield a shared_ptr<T> equivalent to the original passed to lend_object().

Shm_session1 and Shm_session2 supported, respectively, include:

shm::classic::Pool_arena, shm::classic::Pool_arena (sic);
shm::arena_lend::jemalloc::Shm_session, shm::arena_lend::jemalloc::Shm_session (sic);
session::shm::classic::Client_session, session::shm::classic::Server_session;
- vice versa;
session::shm::arena_lend::jemalloc::Client_session, session::shm::arena_lend::jemalloc::Server_session;
- vice versa;
shm::Builder::Session pointee, shm::Reader::Session pointee.

Parameters

shm_handle_root	Non-null (or behavior undefined/assertion may trip) pointer to `ShmHandle` builder to mutate.
lend_result	What `lend_object<T>()` returned. Not `.empty()`, or behavior undefined (assertion may trip). Reminder: if that returned `.empty()`, the session is likely hosed, and you cannot transmit SHM objects between the two endpoints, so there is no point in calling us.

◆ operator<<() [1/3]

template<typename Shm_arena >

std::ostream & operator<<	(	std::ostream &	os,
		const Builder< Shm_arena > &	val
	)

Prints string representation of the given Builder to the given ostream.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator<<() [2/3]

template<typename Shm_arena >

std::ostream & operator<<	(	std::ostream &	os,
		const Capnp_message_builder< Shm_arena > &	val
	)

Prints string representation of the given Capnp_message_builder to the given ostream.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

◆ operator<<() [3/3]

template<typename Shm_arena >

std::ostream & operator<<	(	std::ostream &	os,
		const Reader< Shm_arena > &	val
	)

Prints string representation of the given Reader to the given ostream.

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

Namespaces

Classes

Functions

Detailed Description

Function Documentation

◆ capnp_get_shm_handle_to_borrow()

◆ capnp_set_lent_shm_handle()

◆ operator<<() [1/3]

◆ operator<<() [2/3]

◆ operator<<() [3/3]