Internal type containing data and types common to internal types Server_session_impl and Client_session_impl which are the respective true cores of Server_session and Client_session respectively. More...

#include <session_base.hpp>

Inheritance diagram for ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >:

[legend]

Collaboration diagram for ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >:

[legend]

Classes
class	Graceful_finisher
	Optional to use by subclasses, this operates a simple state machine that carries out a graceful-session-end handshake procedure. More...

Public Types
using	Persistent_mq_handle_from_cfg = std::conditional_t<!S_MQS_ENABLED, transport::Null_peer, std::conditional_t< S_MQ_TYPE_OR_NONE==schema::MqType::POSIX, transport::Posix_mq_handle, transport::Bipc_mq_handle > >
	Relevant only if S_MQS_ENABLED, this is the Persistent_mq_handle-concept impl type specified by the user via `S_MQ_TYPE_OR_NONE`. More...

using	Channel_obj = std::conditional_t< S_MQS_ENABLED, std::conditional_t< S_TRANSMIT_NATIVE_HANDLES, transport::Mqs_socket_stream_channel< true, Persistent_mq_handle_from_cfg >, transport::Mqs_channel< true, Persistent_mq_handle_from_cfg > >, std::conditional_t< S_TRANSMIT_NATIVE_HANDLES, transport::Socket_stream_channel< true >, transport::Socket_stream_channel_of_blobs< true > > >
	See Session_mv (or Session concept). More...

using	Channels = std::vector< Channel_obj >
	See Session_mv. Note: If changed from `vector` please update those doc headers too. More...

using	Mdt_payload_obj = Mdt_payload
	See Session_mv (or Session concept). More...

using	Mdt_reader_ptr = boost::shared_ptr< typename transport::struc::schema::Metadata< Mdt_payload_obj >::Reader >
	See Session_mv (or Session concept). More...

using	Mdt_builder = typename transport::struc::schema::Metadata< Mdt_payload_obj >::Builder
	See Session_mv (or Session concept). More...

using	Mdt_builder_ptr = boost::shared_ptr< Mdt_builder >
	See Session_mv (or Session concept). More...

using	Structured_msg_builder_config = transport::struc::Heap_fixed_builder::Config
	See Session_mv (or Session concept). More...

using	Structured_msg_reader_config = transport::struc::Heap_reader::Config
	See Session_mv (or Session concept). More...

Public Member Functions
const Shared_name &	srv_namespace () const
	See Server_session_impl, Client_session_impl. More...

const Shared_name &	cli_namespace () const
	See Server_session_impl, Client_session_impl. More...

const Client_app *	cli_app_ptr () const
	See Server_session_impl, Client_session_impl. More...

Shared_name	cur_ns_store_mutex_absolute_name () const
	Computes the name of the interprocess named-mutex used to control reading/writing to the file storing (written by server, read by client) the value for srv_namespace(). More...

fs::path	cur_ns_store_absolute_path () const
	Computes the absolute path to file storing (written by server, read by client) the value for srv_namespace(). More...

Shared_name	session_master_socket_stream_acceptor_absolute_name () const
	Computes the absolute name at which the server shall set up a transport::Native_socket_stream_acceptor to which client shall transport::Native_socket_stream::sync_connect() in order to establish a PEER-state session. More...

Static Public Member Functions
static Structured_msg_builder_config	heap_fixed_builder_config (flow::log::Logger *logger_ptr)
	See Session_mv::heap_fixed_builder_config() (1-arg). More...

static Structured_msg_reader_config	heap_reader_config (flow::log::Logger *logger_ptr)
	See Session_mv::heap_reader_config() (1-arg). More...

Public Attributes
const Server_app &	m_srv_app_ref
	Reference to Server_app (referring to local process in Server_session_impl, opposing process in Client_session_impl). More...

Static Public Attributes
static constexpr bool	S_MQS_ENABLED = S_MQ_TYPE_OR_NONE != schema::MqType::NONE
	See Session_mv. More...

static constexpr bool	S_SOCKET_STREAM_ENABLED = (!S_MQS_ENABLED) \|\| S_TRANSMIT_NATIVE_HANDLES
	See Session_mv. More...

Protected Types
using	Master_structured_channel = transport::struc::Channel_via_heap< transport::Socket_stream_channel< true >, schema::detail::SessionMasterChannelMessageBody< Mdt_payload_obj > >
	The (internally used) session master channel is a transport::struc::Channel of this concrete type. More...

using	Master_structured_channel_ptr = boost::shared_ptr< Master_structured_channel >
	Handle to Master_structured_channel. More...

using	Master_structured_channel_observer = boost::weak_ptr< Master_structured_channel >
	Observer of Master_structured_channel_ptr. See its doc header. More...

using	On_passive_open_channel_func = Function< void(Channel_obj &&new_channel, Mdt_reader_ptr &&new_channel_mdt)>
	Concrete function type for the on-passive-open handler (if any), used for storage. More...

Protected Member Functions
	Session_base (const Client_app &cli_app_ref, const Server_app &srv_app_ref, flow::async::Task_asio_err &&on_err_func, On_passive_open_channel_func &&on_passive_open_channel_func_or_empty_arg)
	Constructs: Client_session_impl form (the user is the one constructing the object, though in NULL state). More...

	Session_base (const Server_app &srv_app_ref)
	Constructs: Server_session_impl form (Session_server is the one constructing the object, though in NULL state, before log-in has completed, but after the socket-stream connection has been established). More...

void	set_srv_namespace (Shared_name &&srv_namespace_new)
	Sets srv_namespace() (do not call if already set). More...

void	set_cli_namespace (Shared_name &&cli_namespace_new)
	Sets cli_namespace() (do not call if already set). More...

void	set_cli_app_ptr (const Client_app *cli_app_ptr_new)
	Sets cli_app_ptr() (do not call if already set). More...

void	set_on_passive_open_channel_func (On_passive_open_channel_func &&on_passive_open_channel_func)
	Sets on_passive_open_channel_func_or_empty() (do not call if already set; do not call if user intends for passive-opens to be disabled on this side). More...

void	set_on_err_func (flow::async::Task_asio_err &&on_err_func_arg)
	Sets on_err_func() (do not call if already set). More...

bool	on_err_func_set () const
	Returns `true` if and only if set_on_err_func() has been called. More...

const On_passive_open_channel_func &	on_passive_open_channel_func_or_empty () const
	The on-passive-open handler (may be empty even in final state, meaning user wants passive-opens disabled on this side). More...

void	hose (const Error_code &err_code)
	Marks this session as hosed for (truthy) reason `err_code`; and synchronously invokes on-error handler; only invoke if not already hosed(). More...

bool	hosed () const
	Returns `true` if and only if hose() has been called. More...

Static Protected Attributes
static constexpr util::Fine_duration	S_OPEN_CHANNEL_TIMEOUT = boost::chrono::seconds(60)
	Internal timeout for `open_channel()`. More...

static constexpr size_t	S_MQS_MAX_MSG_SZ = 8 * 1024
	The max sendable MQ message size as decided by Server_session_impl::make_channel_mqs() (and imposed on both sides, both directions), if S_MQS_ENABLED and Server_session_impl::S_SHM_ENABLED is `false`, when a channel is opened (regardless of which side did the active-open or requested pre-opening at session start). More...

Private Attributes
std::atomic< const Client_app * >	m_cli_app_ptr
	See cli_app_ptr(). More...

Shared_name	m_srv_namespace
	See srv_namespace(). More...

Shared_name	m_cli_namespace
	See cli_namespace(). More...

flow::async::Task_asio_err	m_on_err_func
	See set_on_err_func(). More...

On_passive_open_channel_func	m_on_passive_open_channel_func_or_empty
	See on_passive_open_channel_func_or_empty(). More...

Error_code	m_peer_state_err_code_or_ok
	Starts falsy; becomes forever truthy (with a specific Error_code that will not change thereafter) once hose() is called (with that truthy value). More...

Detailed Description

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload>
class ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >

Internal type containing data and types common to internal types Server_session_impl and Client_session_impl which are the respective true cores of Server_session and Client_session respectively.

A Server_session_impl and Client_session_impl share many basic properties, some public. For example consider that a Server_session_impl on this side has 1 counterpart Client_session_impl on the other side (or vice versa); for both it is salient which Server_app is on the server side and which Client_app is on the client side. In terms of types/constants, on each side the two Session objects must be identically configured via various template params which results in non-trivial type aliases like the highly significant Channel_obj, exposed in the Session concept, and constants like S_SOCKET_STREAM_ENABLED.

Regarding data: an operational (PEER-state) Session (on either end) will need various members to be set before it is indeed in PEER state. This object stores such data, usually unset at first, and features protected setters to invoke once each, until all are set permanently for PEER state.

Session_base also has a protected inner class, Session_base::Graceful_finisher which certain variations (for which this is necessary) of Server_session_impl and Client_session_impl use to carry out a graceful-session-end handshake procedure. This is here in Session_base – despite being somewhat more algorithmic/stateful than the other stuff here – essentially because the Graceful_finisher (if needed at all) on each side acts completely symmetrically. Other items tend to be (internally) asymmetrical in behavior between Server_session_impl and Client_session_impl (and variants). More info on Session_base::Graceful_finisher in its own doc header.

Template Parameters

Mdt_payload	See Server_session, Client_session (or Session concept).
S_MQ_TYPE_OR_NONE	See Server_session, Client_session.
S_TRANSMIT_NATIVE_HANDLES	See Server_session, Client_session.

Definition at line 67 of file session_base.hpp.

Member Typedef Documentation

◆ Channel_obj

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Channel_obj = std::conditional_t<S_MQS_ENABLED, std::conditional_t <S_TRANSMIT_NATIVE_HANDLES, transport::Mqs_socket_stream_channel<true, Persistent_mq_handle_from_cfg>, transport::Mqs_channel<true, Persistent_mq_handle_from_cfg> >, std::conditional_t <S_TRANSMIT_NATIVE_HANDLES, transport::Socket_stream_channel<true>, transport::Socket_stream_channel_of_blobs<true> >>

See Session_mv (or Session concept).

Definition at line 111 of file session_base.hpp.

◆ Channels

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Channels = std::vector<Channel_obj>

See Session_mv. Note: If changed from vector please update those doc headers too.

Definition at line 122 of file session_base.hpp.

◆ Master_structured_channel

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Master_structured_channel = transport::struc::Channel_via_heap<transport::Socket_stream_channel<true>, schema::detail::SessionMasterChannelMessageBody <Mdt_payload_obj> >

protected

The (internally used) session master channel is a transport::struc::Channel of this concrete type.

Rationale for the chosen knob values:

To be able to open_channel() (and hence passive-open) a Channel_obj that can transmit native handles, certainly a handles pipe is required to transmit half of each socket-pair. That said, an Mqs_channel would work fine if S_SOCKET_STREAM_ENABLED is false. The real reason at least a handles pipe is required is that to establish this channel – unlike subsequent channels in the session – a client-server flow is required. This connection establishment is not possible with MQs, so of the available options only a socket stream would work.
- There is no bulky data transfers over this channel, so adding a parallel MQ-based blobs pipe is overkill even if it could help performance; more so since the master channel is unlikely to be used frequently (open_channel() on either side shouldn't be that frequent). Since, again, the minute differences in perf versus a Unix-domain-socket-based transport are unlikely to be significant in this use case, it is easier to use a socket stream which lacks any kernel-persistent cleanup considerations – or even just distinct naming considerations for that matter.
- So: use a transport::Socket_stream_channel.
Use the specially tailored (internal) session master channel capnp schema, whose key messages cover (at least):
- session log-in at the start;
- open-channel request/response.
As of this writing, for serializing/deserializing, it's either the heap-allocating engine on either side, or it's something SHM-based (which could be faster). However at least some SHM-based builders/readers themselves (internally) require a transport::Channel to function, which would require a Session typically, creating a cyclical feature dependency. Plus, SHM has cleanup considerations. So a heap-based engine on either side is the natural choice. The cost is some perf: one copies from heap into the session master transport; and from there into heap on the other side. In this context that's not a significant perf loss.

Definition at line 352 of file session_base.hpp.

◆ Master_structured_channel_observer

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Master_structured_channel_observer = boost::weak_ptr<Master_structured_channel>

protected

Observer of Master_structured_channel_ptr. See its doc header.

Definition at line 369 of file session_base.hpp.

◆ Master_structured_channel_ptr

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Master_structured_channel_ptr = boost::shared_ptr<Master_structured_channel>

protected

Handle to Master_structured_channel.

Rationale for type chosen

It's a handle at all, because at first and possibly later there may be no session master channel, so a null value is useful. (Though, std::optional could be used instead.) It's a ref-counted pointer as opposed to unique_ptr so that it can be observed via Master_structured_channel_observer (weak_ptr) which is not (and cannot) be available for unique_ptr. The observing is needed tactically for certain async lambda needs.

Definition at line 366 of file session_base.hpp.

◆ Mdt_builder

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Mdt_builder = typename transport::struc::schema::Metadata<Mdt_payload_obj>::Builder

See Session_mv (or Session concept).

Definition at line 132 of file session_base.hpp.

◆ Mdt_builder_ptr

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Mdt_builder_ptr = boost::shared_ptr<Mdt_builder>

See Session_mv (or Session concept).

Definition at line 136 of file session_base.hpp.

◆ Mdt_payload_obj

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Mdt_payload_obj = Mdt_payload

See Session_mv (or Session concept).

Definition at line 125 of file session_base.hpp.

◆ Mdt_reader_ptr

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Mdt_reader_ptr = boost::shared_ptr<typename transport::struc::schema::Metadata<Mdt_payload_obj>::Reader>

See Session_mv (or Session concept).

Definition at line 128 of file session_base.hpp.

◆ On_passive_open_channel_func

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::On_passive_open_channel_func = Function<void (Channel_obj&& new_channel, Mdt_reader_ptr&& new_channel_mdt)>

protected

Concrete function type for the on-passive-open handler (if any), used for storage.

Definition at line 372 of file session_base.hpp.

◆ Persistent_mq_handle_from_cfg

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Persistent_mq_handle_from_cfg = std::conditional_t<!S_MQS_ENABLED, transport::Null_peer, std::conditional_t<S_MQ_TYPE_OR_NONE == schema::MqType::POSIX, transport::Posix_mq_handle, transport::Bipc_mq_handle> >

Relevant only if S_MQS_ENABLED, this is the Persistent_mq_handle-concept impl type specified by the user via S_MQ_TYPE_OR_NONE.

Definition at line 103 of file session_base.hpp.

◆ Structured_msg_builder_config

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Structured_msg_builder_config = transport::struc::Heap_fixed_builder::Config

See Session_mv (or Session concept).

Definition at line 139 of file session_base.hpp.

◆ Structured_msg_reader_config

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

using ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Structured_msg_reader_config = transport::struc::Heap_reader::Config

See Session_mv (or Session concept).

Definition at line 142 of file session_base.hpp.

Constructor & Destructor Documentation

◆ Session_base() [1/2]

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Session_base	(	const Client_app &	cli_app_ref,
		const Server_app &	srv_app_ref,
		flow::async::Task_asio_err &&	on_err_func,
		On_passive_open_channel_func &&	on_passive_open_channel_func_or_empty_arg
	)

explicitprotected

Constructs: Client_session_impl form (the user is the one constructing the object, though in NULL state).

The values taken as args are set permanently (undefined behavior/assertion may trip if an attempt is made to modify one via mutator). The remaining values must be set via mutator before PEER state.

Parameters

cli_app_ref	See cli_app_ptr().
srv_app_ref	See m_srv_app_ref.
on_err_func	On-error handler from user.
on_passive_open_channel_func_or_empty_arg	On-passive-open handler from user (empty if user wishes the disable passive-opens on this side).

Definition at line 819 of file session_base.hpp.

◆ Session_base() [2/2]

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Session_base ( const Server_app & srv_app_ref )

explicitprotected

Constructs: Server_session_impl form (Session_server is the one constructing the object, though in NULL state, before log-in has completed, but after the socket-stream connection has been established).

The values taken as args are set permanently (undefined behavior/assertion may trip if an attempt is made to modify one via mutator). The remaining values must be set via mutator before PEER state.

Parameters

srv_app_ref See m_srv_app_ref.

Definition at line 838 of file session_base.hpp.

Member Function Documentation

◆ cli_app_ptr()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

const Client_app * ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cli_app_ptr

See Server_session_impl, Client_session_impl.

However in Session_base this value may be not-yet-set (null), or set (and immutable from then on). Note the value to which we refer is the actual pointer. (The Client_app that is pointed-to, itself, is certainly immutable too.)

This value shall be set from the start in a Client_session_impl but determined during a given Server_session_impl's log-in (the opposing Client_session_impl will transmit the Client_app::m_name). The log-in shall complete the Server_session's entry to PEER state.

Returns: See above.

Definition at line 906 of file session_base.hpp.

◆ cli_namespace()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

const Shared_name & ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cli_namespace

See Server_session_impl, Client_session_impl.

However in Session_base this value may be not-yet-set (empty), or set (and immutable from then on).

This value shall be generated uniquely (within some context) for each new Server_session produced by Session_server; and Client_session_impl shall find that out while logging in (last part of entering PEER state).

Returns: See above.

Definition at line 918 of file session_base.hpp.

◆ cur_ns_store_absolute_path()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

fs::path ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cur_ns_store_absolute_path

Computes the absolute path to file storing (written by server, read by client) the value for srv_namespace().

The file is located as cur_ns_store_absolute_path().

This may be called anytime.

Returns: See above.

Definition at line 986 of file session_base.hpp.

References ipc::util::IPC_KERNEL_PERSISTENT_RUN_DIR.

◆ cur_ns_store_mutex_absolute_name()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

Shared_name ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::cur_ns_store_mutex_absolute_name

Computes the name of the interprocess named-mutex used to control reading/writing to the file storing (written by server, read by client) the value for srv_namespace().

The file is located as cur_ns_store_absolute_path().

This may be called anytime.

Returns: See above.

Definition at line 953 of file session_base.hpp.

References ipc::session::build_conventional_shared_name(), ipc::util::Shared_name::ct(), ipc::util::Shared_name::S_RESOURCE_TYPE_ID_MUTEX, and ipc::util::Shared_name::S_SENTINEL.

Here is the call graph for this function:

◆ heap_fixed_builder_config()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Structured_msg_builder_config ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::heap_fixed_builder_config ( flow::log::Logger * logger_ptr )

static

See Session_mv::heap_fixed_builder_config() (1-arg).

Parameters

logger_ptr See above.

Returns: See above.

Definition at line 1020 of file session_base.hpp.

◆ heap_reader_config()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Structured_msg_reader_config ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::heap_reader_config ( flow::log::Logger * logger_ptr )

static

See Session_mv::heap_reader_config() (1-arg).

Parameters

logger_ptr See above.

Returns: See above.

Definition at line 1165 of file session_base.hpp.

◆ hose()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

void ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::hose ( const Error_code & err_code )

protected

Marks this session as hosed for (truthy) reason err_code; and synchronously invokes on-error handler; only invoke if not already hosed().

This utility is important and has certain pre-conditions (behavior undefined if not met; assertion may trip):

*this must be in PEER state. In particular on_err_func_set() must return true.
hosed() must return false.
err_code must be truthy (non-success).
This must be invoked from a thread such that it is OK to synchronously invoke on-error handler. As of this writing this is Server_session_impl's or Client_session_impl's thread W in practice, which is how thread safety of hose() versus hosed() is also guaranteed by those users.

Parameters

err_code Truthy error.

Definition at line 937 of file session_base.hpp.

Referenced by ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Graceful_finisher::Graceful_finisher().

Here is the caller graph for this function:

◆ hosed()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

bool ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::hosed

protected

Returns true if and only if hose() has been called.

If so then m_on_err_func has been executed already. *this must be in PEER state. In particular on_err_func_set() must return true.

Returns: Ditto.

Definition at line 946 of file session_base.hpp.

Referenced by ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::Graceful_finisher::Graceful_finisher().

Here is the caller graph for this function:

◆ on_err_func_set()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

bool ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::on_err_func_set

protected

Returns true if and only if set_on_err_func() has been called.

Returns: See above.

Definition at line 931 of file session_base.hpp.

◆ on_passive_open_channel_func_or_empty()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

const Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::On_passive_open_channel_func & ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::on_passive_open_channel_func_or_empty

protected

The on-passive-open handler (may be empty even in final state, meaning user wants passive-opens disabled on this side).

Returns: See above.

Definition at line 925 of file session_base.hpp.

◆ session_master_socket_stream_acceptor_absolute_name()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

Shared_name ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::session_master_socket_stream_acceptor_absolute_name

Computes the absolute name at which the server shall set up a transport::Native_socket_stream_acceptor to which client shall transport::Native_socket_stream::sync_connect() in order to establish a PEER-state session.

This must be called no earlier than set_srv_namespace(); otherwise behavior undefined (assertion may trip).

Returns: See above.

Definition at line 999 of file session_base.hpp.

References ipc::session::build_conventional_shared_name(), ipc::util::Shared_name::ct(), ipc::transport::Native_socket_stream_acceptor::S_RESOURCE_TYPE_ID, and ipc::util::Shared_name::S_SENTINEL.

Here is the call graph for this function:

◆ set_cli_app_ptr()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

void ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::set_cli_app_ptr ( const Client_app * cli_app_ptr_new )

protected

Sets cli_app_ptr() (do not call if already set).

Parameters

cli_app_ptr_new Value.

Definition at line 857 of file session_base.hpp.

◆ set_cli_namespace()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

void ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::set_cli_namespace ( Shared_name && cli_namespace_new )

protected

Sets cli_namespace() (do not call if already set).

Parameters

cli_namespace_new Value.

Definition at line 880 of file session_base.hpp.

References ipc::util::Shared_name::S_SENTINEL.

◆ set_on_err_func()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

void ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::set_on_err_func ( flow::async::Task_asio_err && on_err_func_arg )

protected

Sets on_err_func() (do not call if already set).

Parameters

on_err_func_arg Value.

Definition at line 897 of file session_base.hpp.

◆ set_on_passive_open_channel_func()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

void ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::set_on_passive_open_channel_func ( On_passive_open_channel_func && on_passive_open_channel_func )

protected

Sets on_passive_open_channel_func_or_empty() (do not call if already set; do not call if user intends for passive-opens to be disabled on this side).

Parameters

on_passive_open_channel_func Value.

Definition at line 890 of file session_base.hpp.

◆ set_srv_namespace()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

void ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::set_srv_namespace ( Shared_name && srv_namespace_new )

protected

Sets srv_namespace() (do not call if already set).

Parameters

srv_namespace_new Value.

Definition at line 870 of file session_base.hpp.

References ipc::util::Shared_name::S_SENTINEL.

◆ srv_namespace()

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

const Shared_name & ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::srv_namespace

See Server_session_impl, Client_session_impl.

However in Session_base this value may be not-yet-set (empty), or set (and immutable from then on).

This value shall be known and immutable from construction for Server_session_impl, since server namespace – PID as of this writing – can be determined from the start on the server side and applies to every server session that Session_server produces. Client_session_impl, however, determines it at the latest possible moment which is at Client_session_impl::async_connect() time, at which point it needs to determine the PID via PID file.

Returns: See above.

Definition at line 912 of file session_base.hpp.

Member Data Documentation

◆ m_cli_app_ptr

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

std::atomic<const Client_app*> ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::m_cli_app_ptr

private

See cli_app_ptr().

Rationale for it being `atomic<>`

It is for the following specific reason. Consider ostream<< of *this. *this is really either in Client_session_impl or Server_session_impl. In both cases these ostream<<s access only m_srv_app_ref, which is immutable throughout (so no problem there) and m_cli_app_ptr. For Client_session_impl m_cli_app_ptr is also immutable throughout (so no problem there). For Server_session_impl however it does change in one spot: Server_session_impl::async_accept_log_in() internal async handler for the log-in request shall, on success, call set_cli_app_ptr() and change it from null to non-null. This could cause concurrent access to the data member, even though it's a mere pointer (but we don't count on the alleged "atomicity" of this; it is generally considered not safe).

Now, as of this writing, there's exactly one spot where ostream<< could be invoked from thread U while it is being assigned in thread W: async_accept_log_in() is called by our internal code in Session_server and only once; the only thing that can occur in thread U until the log-in response handler is executed is that Server_session_impl dtor is called. Before that dtor stops that thread W, it does print the Server_session_impl once as of this writing. Therefore, out of sheer caution, this guy is atomic<>. That said there could be other such invocations, as code might change during maintenance in the future, in which case this atomic<>ness will quietly come in handy.

Definition at line 783 of file session_base.hpp.

◆ m_cli_namespace

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

Shared_name ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::m_cli_namespace

private

See cli_namespace().

Definition at line 789 of file session_base.hpp.

◆ m_on_err_func

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

flow::async::Task_asio_err ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::m_on_err_func

private

See set_on_err_func().

Definition at line 792 of file session_base.hpp.

◆ m_on_passive_open_channel_func_or_empty

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

On_passive_open_channel_func ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::m_on_passive_open_channel_func_or_empty

private

See on_passive_open_channel_func_or_empty().

Definition at line 795 of file session_base.hpp.

◆ m_peer_state_err_code_or_ok

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

Error_code ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::m_peer_state_err_code_or_ok

private

Starts falsy; becomes forever truthy (with a specific Error_code that will not change thereafter) once hose() is called (with that truthy value).

Note hose() may not be called before PEER state, which implies m_on_err_func is non-empty.

Concurrency

See hose() and hosed() doc headers. TL;DR: It is up to the caller to only call those, basically, from thread W only.

Definition at line 806 of file session_base.hpp.

◆ m_srv_app_ref

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

const Server_app& ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::m_srv_app_ref

Reference to Server_app (referring to local process in Server_session_impl, opposing process in Client_session_impl).

This is known from construction and immutable (both the reference, of course, and the Server_app itself).

Definition at line 243 of file session_base.hpp.

◆ m_srv_namespace

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

Shared_name ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::m_srv_namespace

private

See srv_namespace().

Definition at line 786 of file session_base.hpp.

◆ S_MQS_ENABLED

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

constexpr bool ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::S_MQS_ENABLED = S_MQ_TYPE_OR_NONE != schema::MqType::NONE

staticconstexpr

See Session_mv.

Definition at line 74 of file session_base.hpp.

◆ S_MQS_MAX_MSG_SZ

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

constexpr size_t ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::S_MQS_MAX_MSG_SZ = 8 * 1024

staticconstexprprotected

The max sendable MQ message size as decided by Server_session_impl::make_channel_mqs() (and imposed on both sides, both directions), if S_MQS_ENABLED and Server_session_impl::S_SHM_ENABLED is false, when a channel is opened (regardless of which side did the active-open or requested pre-opening at session start).

If *this belongs to Server_session_impl, that's what this is. If it belongs to Client_session_impl, then this is what the opposing process – if they're using the same code! – will have decided.

Our own heap_fixed_builder_config(), forwarded to Session_mv::heap_fixed_builder_config(), similarly uses this constant in a matching way.

Note: If Server_session_impl::S_SHM_ENABLED is true, then a different (much smaller) MQ message size limit is configured. In that case, also, heap_fixed_builder_config() is not relevant and should not be used.

While it looks simple, there is a number of subtleties one must understand if ever considering changing it.

bipc versus POSIX MQs

As of this writing the same constant value is used for both types of MQ configurable. The actual value is chosen due to a certain aspect of POSIX MQs (discussed just below); and we reuse it for bipc, though we absolutely do not have to, for simplicity/for lack of better ideas at the moment. It would be possible to bifurcate those two cases if really desired.

Why 8Ki?

By default in Linux POSIX MQs this happens to be the actual limit for # of unread messages – visible in /proc/sys/fs/mqueue/msgsize_max – so we cannot go higher typically. However that file can be modified. For now we assume a typical environment; or at least that it will not go below this typical default. If did try a higher number here, opening of MQs by server will likely emit an error and refuse (Server_session_impl::make_channel_mqs()).

Things to consider if changing the value away from the above

Contemplate why you're doing it. bipc MQs are seen (in Boost source) to be a simple zero-copy data structure in an internally maintained kernel-persistent SHM pool; while I (ygoldfel) haven't verified via kernal source, likely Linux POSIX MQ impl is something very similar (reasoning omitted but trust me). So copy perf should not be a factor; only RAM use and the functional ability to transmit messages of a certain size.
- If the plan is to use transport::struc::Heap_fixed_builder-backed for structured messages (via transport::struc::Channel), then the max size is quite important: if a leaf in your message exceeds this size when serialized, it is a fatal error.
- If, however, the plan is to use SHM-backing (e.g., via shm::classic::*_session), then this constant does not get used (a much smaller value does – so small it would be ~meaningless to decrease it).
Suppose you have changed this value, and suppose the Heap_fixed_builder-based use case does matter. If ipc has not yet been released in production, ever, then it's fine (assuming, that is, it'll work in the first place given the aforementioned /proc/sys/... limit for POSIX MQs). If it has been released then there is an annoying subtlety to consider:
- If you can guarantee (via release process) that the client and server will always use the same ipc software, then you're still fine. Just change this value; done. Otherwise though:
- There's the unfortunate caveat that is Session_base::heap_fixed_builder_config(). There you will note it says that the server decides (for both sides) what this value is. In that case that method will be correct in the server process; but if the client process is speaking to a different version of the server, with a different value for S_MQS_MAX_MSG_SZ, then that is a potential bug.
  - Therefore it would be advisable to not mess with it (again... once a production version is out there). If you do mess with it, there are ways to ensure it all works out anyway: logic could be added wherein the client specifies its own S_MQS_MAX_MSG_SZ when issuing an open-channel request, and the server must honor it in its Server_session_impl::make_channel_mqs(). So it can be done – just know that in that case you'll have to actually add such logic; or somewhat break heap_fixed_builder_config(). The reason I (ygoldfel) have not done this already is it seems unlikely (for various reasons listed above) that tweaking this value is of much practical value.

Definition at line 321 of file session_base.hpp.

◆ S_OPEN_CHANNEL_TIMEOUT

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

constexpr util::Fine_duration ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::S_OPEN_CHANNEL_TIMEOUT = boost::chrono::seconds(60)

staticconstexprprotected

Internal timeout for open_channel().

The value

We initially tried something much less generous, 500ms. It worked fine, but some people encountered the timeout due to unrelated reasons, and it was natural to blame it on the timeout. This much longer timeout should make it obvious, in such a situation, that it's not about some slowness inside Flow-IPC but a pathological application problem – particularly around session-open time. For example not calling Server_session_impl::init_handlers(), or calling it late, as of this writing can cause issues with this.

The downside is it makes Session::open_channel() potentially blocking formally speaking, whereas 500ms could still claim to be non-blocking. It's a matter of perspective really. This value just seems to cause less confusion. We might reconsider the whole thing however.

Definition at line 262 of file session_base.hpp.

◆ S_SOCKET_STREAM_ENABLED

template<schema::MqType S_MQ_TYPE_OR_NONE, bool S_TRANSMIT_NATIVE_HANDLES, typename Mdt_payload >

constexpr bool ipc::session::Session_base< S_MQ_TYPE_OR_NONE, S_TRANSMIT_NATIVE_HANDLES, Mdt_payload >::S_SOCKET_STREAM_ENABLED = (!S_MQS_ENABLED) || S_TRANSMIT_NATIVE_HANDLES

staticconstexpr

See Session_mv.

Definition at line 77 of file session_base.hpp.

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

session/detail/session_base.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Types

Protected Member Functions

Static Protected Attributes

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Channel_obj

◆ Channels

◆ Master_structured_channel

◆ Master_structured_channel_observer

◆ Master_structured_channel_ptr

Rationale for type chosen

◆ Mdt_builder

◆ Mdt_builder_ptr

◆ Mdt_payload_obj

◆ Mdt_reader_ptr

◆ On_passive_open_channel_func

◆ Persistent_mq_handle_from_cfg

◆ Structured_msg_builder_config

◆ Structured_msg_reader_config

Constructor & Destructor Documentation

◆ Session_base() [1/2]

◆ Session_base() [2/2]

Member Function Documentation

◆ cli_app_ptr()

◆ cli_namespace()

◆ cur_ns_store_absolute_path()

◆ cur_ns_store_mutex_absolute_name()

◆ heap_fixed_builder_config()

◆ heap_reader_config()

◆ hose()

◆ hosed()

◆ on_err_func_set()

◆ on_passive_open_channel_func_or_empty()

◆ session_master_socket_stream_acceptor_absolute_name()

◆ set_cli_app_ptr()

◆ set_cli_namespace()

◆ set_on_err_func()

◆ set_on_passive_open_channel_func()

◆ set_srv_namespace()

◆ srv_namespace()

Member Data Documentation

◆ m_cli_app_ptr

Rationale for it being atomic<>

◆ m_cli_namespace

◆ m_on_err_func

◆ m_on_passive_open_channel_func_or_empty

◆ m_peer_state_err_code_or_ok

Concurrency

◆ m_srv_app_ref

◆ m_srv_namespace

◆ S_MQS_ENABLED

◆ S_MQS_MAX_MSG_SZ

bipc versus POSIX MQs

Why 8Ki?

Things to consider if changing the value away from the above

◆ S_OPEN_CHANNEL_TIMEOUT

The value

◆ S_SOCKET_STREAM_ENABLED

Rationale for it being `atomic<>`