ipc::shm::arena_lend Namespace Reference

ipc::shm sub-module providing the SHM-provider family based on the arena-lending paradigm: each process allocates in its own arena(s), lending the resulting objects to other processes, which can read them but not allocate (nor deallocate) in that arena. More...

Namespaces
namespace	error
	Namespace containing the ipc::shm::arena_lend module's (including SHM-jemalloc's) extension of boost.system error conventions, so that that API can return codes/messages from within its own new set of error codes/messages.
namespace	jemalloc
	ipc::shm sub-module with the SHM-jemalloc SHM-provider. See ipc::shm doc header for introduction.
namespace	stat
	Stats-related sub-namespace, for ADL segregation and general organization.

Classes
class	Borrower_allocator_arena
	When borrowing STL-compliant in-SHM data structures, use this type as the Arena template parameter to shm::stl::Stateless_allocator (or equivalent). More...
struct	Set_logger_tag
	Tag type for the Action_registry that fans out set_logger() calls to all arena-lend singletons. More...

Typedefs
template<typename T >
using	Obj_handle = std::shared_ptr< T >
	Determines the shared_ptr variety returned by A::construct() and S::borrow_object() for any arena-lending SHM-provider, where for a given SHM-provider A is the arena type (SHM-jemalloc: jemalloc::Ipc_arena), S is the SHM-session type (SHM-jemalloc: session::shm::arena_lend::jemalloc::Shm_session). More...
using	Shared_name = util::Shared_name
	Short-hand for util::Shared_name; used in particular for SHM pool names at least.
using	owner_id_t = util::process_id_t
	Alias for an identifier of the owner (essentially namespace of collection_id_ts) of shared information.
using	collection_id_t = uint32_t
	Identifier type for a shared memory pool collection. More...
using	Set_logger_registry = flow::util::Action_registry< Set_logger_tag, flow::log::Logger * >
	The Action_registry that fans out set_logger() calls to all SHM-arena-lend singletons. More...

Functions
void	set_logger (flow::log::Logger *logger_ptr)
	Convenience function that sets (or clears) the Logger used by all SHM-arena-lend singleton subsystems. More...

Detailed Description

ipc::shm sub-module providing the SHM-provider family based on the arena-lending paradigm: each process allocates in its own arena(s), lending the resulting objects to other processes, which can read them but not allocate (nor deallocate) in that arena.

As of this writing there is one arena-lending SHM-provider available out-of-the-box, SHM-jemalloc (see sub-namespace arena_lend::jemalloc). The present namespace contains items applicable to any arena-lending provider, with provider-specific items in such sub-namespaces.

See also

ipc::shm doc header for an overview of the available SHM-provider families and how they compare.

Typedef Documentation

collection_id_t

using ipc::shm::arena_lend::collection_id_t = typedef uint32_t

Identifier type for a shared memory pool collection.

Todo:

Determine proper size of identifier.

Obj_handle

template<typename T >

using ipc::shm::arena_lend::Obj_handle = typedef std::shared_ptr<T>

Determines the shared_ptr variety returned by A::construct() and S::borrow_object() for any arena-lending SHM-provider, where for a given SHM-provider A is the arena type (SHM-jemalloc: jemalloc::Ipc_arena), S is the SHM-session type (SHM-jemalloc: session::shm::arena_lend::jemalloc::Shm_session).

Opportunistic background

For a given SHM-provider, those 2 APIs are the only sources of first-class a/k/a outer object handles. An outer object is by definition one constructed by an arena A or IPC-transmitted and re-obtained borrower-side via SHM-session S. The a.construct() call involves at least allocating, in SHM, sizeof(T) bytes; further inner allocations are possible if T uses the proper SHM-capable allocator (we recommend stl::Stateless_allocator); for example if T is vector then the vector ctor invocation during a.construct() might perform an inner allocation, as might a subsequent .resize().

Template Parameters

T	Outer object type.

Set_logger_registry

using ipc::shm::arena_lend::Set_logger_registry = typedef flow::util::Action_registry<Set_logger_tag, flow::log::Logger*>

The Action_registry that fans out set_logger() calls to all SHM-arena-lend singletons.

The end user is likely to not need to directly reference this: use arena_lend::set_logger() free function.

Function Documentation

set_logger()

void ipc::shm::arena_lend::set_logger

(

flow::log::Logger *

logger_ptr

)

Convenience function that sets (or clears) the Logger used by all SHM-arena-lend singleton subsystems.

Typical usage brackets main():

ipc::shm::arena_lend::set_logger(&my_logger); // startup
// ... application runs ...
ipc::shm::arena_lend::set_logger(nullptr);    // teardown (before Logger is destroyed)

Parameters

logger_ptr

Pointer to the Logger to use, or null to disable logging.