Implements Session concept on the Server_app end: a Session that is emitted in almost-PEER state by local Session_server accepting a connection by an opposing Client_session_mv::sync_connect(). More...

#include <server_session.hpp>

Inheritance diagram for ipc::session::Server_session_mv< Server_session_impl_t >:

[legend]

Collaboration diagram for ipc::session::Server_session_mv< Server_session_impl_t >:

[legend]

Public Types
using	Base = Session_mv< Server_session_impl_t >
	Short-hand for our base class. To the user: note its `public` API is inherited. More...

Public Types inherited from ipc::session::Session_mv< Server_session_impl_t >
using	Channel_obj = typename Impl::Channel_obj
	Implements Session API per contract. More...

using	Channels = typename Impl::Channels
	Container (`vector<>`) of Channel_obj. More...

using	Mdt_payload_obj = typename Impl::Mdt_payload_obj
	Implements Session API per contract. More...

using	Mdt_builder = typename Impl::Mdt_builder
	Implements Session API per contract. More...

using	Mdt_builder_ptr = typename Impl::Mdt_builder_ptr
	Implements Session API per contract. More...

using	Mdt_reader_ptr = typename Impl::Mdt_reader_ptr
	Implements Session API per contract. More...

using	Structured_channel = typename transport::struc::Channel_via_heap< Channel_obj, Message_body >
	Implements Session API per contract. More...

using	Structured_msg_builder_config = typename Impl::Structured_msg_builder_config
	Implements Session API per contract. More...

using	Structured_msg_reader_config = typename Impl::Structured_msg_builder_config
	Implements Session API per contract. More...

Public Member Functions
const Client_app *	client_app () const
	The opposing application is described by a Client_app; this is that description. More...

template<typename Task_err , typename On_passive_open_channel_handler >
bool	init_handlers (Task_err &&on_err_func_arg, On_passive_open_channel_handler &&on_passive_open_channel_func_arg)
	To be invoked by public user upon first obtaining `*this`: memorizes the given on-error and on-passive-open handlers thus moving this Server_session_mv to PEER state wherein it is a formal Session concept impl. More...

template<typename Task_err >
bool	init_handlers (Task_err &&on_err_func_arg)
	Alternative to the other init_handlers(). More...

Public Member Functions inherited from ipc::session::Session_mv< Server_session_impl_t >
	Session_mv ()
	Implements Session API per contract. More...

	Session_mv (Session_mv &&src)
	Implements Session API per contract. More...

	Session_mv (const Session_mv &)=delete
	Copy ction is disallowed.

	~Session_mv ()
	Implements Session API per contract. More...

Session_mv &	operator= (Session_mv &&src)
	Implements Session API per contract. More...

Session_mv &	operator= (const Session_mv &)=delete
	Copy assignment is disallowed.

Mdt_builder_ptr	mdt_builder ()
	Implements Session API per contract. More...

bool	open_channel (Channel_obj target_channel, const Mdt_builder_ptr &mdt, Error_code err_code=0)
	Implements Session API per contract. More...

bool	open_channel (Channel_obj target_channel, Error_code err_code=0)
	Implements Session API per contract. More...

const Session_token &	session_token () const
	Implements Session API per contract. More...

transport::struc::Heap_fixed_builder::Config	heap_fixed_builder_config ()
	Utility that obtains a heap-based (non-zero-copy) Struct_builder::Config, constructed with the most efficient yet safe values, for transport::struc::Msg_out (out-messages) compatible with Structured_channel upgraded-from Channel_obj channels opened via `*this` Session_mv. More...

transport::struc::Heap_reader::Config	heap_reader_config ()
	Deserializing counterpart to non-`static` heap_fixed_builder_config(). More...

flow::log::Logger *	get_logger () const
	Returns logger (possibly null). More...

const flow::log::Component &	get_log_component () const
	Returns log component. More...

Protected Member Functions
	Server_session_mv (flow::log::Logger *logger_ptr, const Server_app &srv_app_ref, transport::sync_io::Native_socket_stream &&master_channel_sock_stm)
	For use by internal user Session_server_impl: constructor. More...

template<typename Session_server_impl_t , typename Task_err , typename Cli_app_lookup_func , typename Cli_namespace_func , typename Pre_rsp_setup_func , typename N_init_channels_by_srv_req_func , typename Mdt_load_func >
void	async_accept_log_in (Session_server_impl_t srv, typename Base::Channels init_channels_by_srv_req, typename Base::Mdt_reader_ptr mdt_from_cli_or_null, typename Base::Channels init_channels_by_cli_req, Cli_app_lookup_func &&cli_app_lookup_func, Cli_namespace_func &&cli_namespace_func, Pre_rsp_setup_func &&pre_rsp_setup_func, N_init_channels_by_srv_req_func &&n_init_channels_by_srv_req_func, Mdt_load_func &&mdt_load_func, Task_err &&on_done_func)
	For use by internal user Session_server: called no more than once, ideally immediately following ctor, this attempts to get `*this` asynchronously to almost-PEER state by undergoing the log-in request/response (plus, if needed, init-channel-opening) procedure (the other side of which is done by Client_session_impl::sync_connect()). More...

Protected Member Functions inherited from ipc::session::Session_mv< Server_session_impl_t >
const Session_base_obj &	base () const
	Provides `const` access to Session_base super-object. More...

Impl_ptr &	impl ()
	pImpl target; particularly for sub-classes that must add to the above `public` API. More...

const Impl_ptr &	impl () const
	pImpl target; particularly for sub-classes that must add to the above `public` API. More...

Related Functions
(Note that these are not member functions.)
template<typename Server_session_impl_t >
std::ostream &	operator<< (std::ostream &os, const Server_session_mv< Server_session_impl_t > &val)
	Prints string representation of the given `Server_session_mv` to the given `ostream`. More...

Related Functions inherited from ipc::session::Session_mv< Server_session_impl_t >
std::ostream &	operator<< (std::ostream &os, const Session_mv< Server_session_impl_t > &val)
	Prints string representation of the given `Session_mv` to the given `ostream`. More...

Additional Inherited Members
Static Public Member Functions inherited from ipc::session::Session_mv< Server_session_impl_t >
static transport::struc::Heap_fixed_builder::Config	heap_fixed_builder_config (flow::log::Logger *logger_ptr)
	Utility that obtains a heap-based (non-zero-copy) Struct_builder::Config, constructed with the most efficient yet safe values, for transport::struc::Msg_out (out-messages) compatible with Structured_channel upgraded-from Channel_obj channels opened via this Session_mv type. More...

static transport::struc::Heap_reader::Config	heap_reader_config (flow::log::Logger *logger_ptr)
	Deserializing counterpart to `static` heap_fixed_builder_config(). More...

Static Public Attributes inherited from ipc::session::Session_mv< Server_session_impl_t >
static constexpr schema::ShmType	S_SHM_TYPE
	Implements Session API per contract. More...

static constexpr bool	S_SHM_ENABLED
	Implements Session API per contract. More...

static constexpr bool	S_MQS_ENABLED
	Compile-time-known constant indicating whether Channel_obj shall use a blobs pipe over message queues (MQs). More...

static constexpr bool	S_SOCKET_STREAM_ENABLED
	Compile-time-known constant indicating whether Channel_obj shall use socket stream for any type of pipe. More...

Protected Types inherited from ipc::session::Session_mv< Server_session_impl_t >
using	Impl = Server_session_impl_t
	Short-hand for pImpl-lite impl type. This shall be the deepest impl sub-class desired. More...

using	Session_base_obj = typename Impl::Session_base_obj
	Short-hand for Impl's Session_base super-class. More...

using	Impl_ptr = std::experimental::propagate_const< boost::movelib::unique_ptr< Impl > >
	Short-hand for `const`-respecting wrapper around Impl for the pImpl idiom. See impl(). More...

Detailed Description

template<typename Server_session_impl_t>
class ipc::session::Server_session_mv< Server_session_impl_t >

Implements Session concept on the Server_app end: a Session that is emitted in almost-PEER state by local Session_server accepting a connection by an opposing Client_session_mv::sync_connect().

By "almost-PEER state" we mean that the user, upon obtaining a new Server_session_mv, must still call init_handlers() to enter PEER state. See overview of Session hierarchy in namespace ipc::session doc header; then come back here if desired.

It is unusual to use Server_session_mv template directly. If you do wish to set up a server-side session peer, and you do not require SHM support, then use Server_session alias template; target it with a Session_server::async_accept() call. The server-specific API, particularly init_handlers(), is in Server_session_mv and documented here. The side-agnostic API – active once PEER state is achieved – is described by Session (concept) doc header and implemented concretely by Session_mv which is our public, non-virtual super-class.

If you do wish to set up a server-side session peer, but you do require SHM support, then use shm::classic::Server_session or similar (for other SHM-provider(s)); target it with a shm::classic::Session_server::async_accept() (or similar for other SHM-provider(s)). However Server_session (hence Server_session_mv to which it aliases) is its super-class, and until PEER state is reached its API (init_handlers()) remains the only relevant API to use. Once Server_session_mv::init_handlers() puts *this into PEER state, super-class Session_mv (= Session concept) API continues to be relevant. Also in PEER state SHM-relevant additional API members (e.g. shm::classic::Session::app_shm()`) become of interest. The last two sentences describe the situation identically for Client_session_mv as well (see its doc header for context).

Summary hierarchy (contrast with similar spot in Client_session_mv doc header):

Session_mv (Session concept impl)
^– Server_session_mv (adds init_handlers())
=alias= Server_session (parameterizes by transport-configuring knobs = template params)
^– shm::classic::Session_mv (adds session_shm()...; suitable for transport::struc::Channel_base::Serialize_via_session_shm)
^– shm::classic::Server_session (parameterizes by aforementioned knobs = template params)

We may refer to Server_session_mv as Server_session below; particularly since it is likeliest used in that form by the user.

How to use

Per the Session concept a Server_session is open/capable of operation when in PEER state only. A publicly available Server_session object is always in one of 2 states:

Almost-PEER. At this stage you must call init_handlers() to enter PEER state. Until then other APIs will no-op/return sentinel, and no handler will fire.
PEER. At this stage it exactly implements the Session concept. See Session_mv. Reminder: It is not possible to exit PEER state.

Once in PEER state Server_session simply follows Session concept semantics. At this stage our super-class Session_mv implements that concept in particular. See either doc header (Session, Session_mv).

Error handling

Once in PEER state, error handling follows the Session concept (= Session_mv concrete class) doc header. However, up to that point it can emit no errors. You must call init_handlers() first to enter PEER state.

Implementation design/rationale

See section in the same spot of Client_session_mv doc header. A symmetrical situation (w/r/t pImpl-lite design) occurs here. But let's be explicit at the risk of some copy/pasting:

Session_mv is the highest (public) super-class and begins the pImpl-lite-for-movability technique. It pImpl-wraps the Session-concept impl methods/stuff. Server_session_mv merely repeats the same technique but on the API additions at its own level; in particular init_handlers().

The impl object is available via Session_mv::impl() (which is protected). What type does this object have though? Answer: Server_session_impl_t, our template param! This shall be the proper ..._impl internal-use type that matches the level of API (public sub-class) the user chose: E.g.:

Chose Server_session => impl = Server_session_impl.
Chose shm::classic::Server_session => impl = shm::classic::Server_session_impl.

So basically each of the public-API types visible to the user adds the pImpl-wrapping of the methods of the ..._impl type matching their name; and the public/movable-API hierarchy has a parallel internal/non-movable hierarchy, both using public/non-virtual inheritance.

Facade design

Session_server emits a Server_session_mv only once it's in almost-PEER state. Before then it is dealing with it privately. Namely – details are in Server_session_impl – it must

construct it;
call async_accept_log_in() and await its success.

These APIs are protected in Server_session_mv. The detail/ sub-class Server_session_dtl exposes them publicly (but only accessible, by convention, internally; namely by Session_server).

As of this writing the SHM-enabled Session_server variants (e.g., shm::classic::Session_server) do not require any additional internally-accessed APIs. Instead they employ 3 "customization points" using which avoids such a need; see Session_server_impl. Therefore there is no detail/ facade beyond Server_session_dtl.

See also: Server_session_impl doc header.

See also: Session: implemented concept.

Template Parameters

Server_session_impl_t An implementation detail. Use one of the aliases prescribed near the top of this doc header to set this correctly.

Definition at line 122 of file server_session.hpp.

Member Typedef Documentation

◆ Base

template<typename Server_session_impl_t >

using ipc::session::Server_session_mv< Server_session_impl_t >::Base = Session_mv<Server_session_impl_t>

Short-hand for our base class. To the user: note its public API is inherited.

Definition at line 129 of file server_session.hpp.

Constructor & Destructor Documentation

◆ Server_session_mv()

template<typename Server_session_impl_t >

ipc::session::Server_session_mv< Server_session_impl_t >::Server_session_mv	(	flow::log::Logger *	logger_ptr,
		const Server_app &	srv_app_ref,
		transport::sync_io::Native_socket_stream &&	master_channel_sock_stm
	)

explicitprotected

For use by internal user Session_server_impl: constructor.

Invoke async_accept_log_in() to move forward toward PEER state.

Parameters

logger_ptr	Logger to use for logging subsequently.
srv_app_ref	Properties of this server application. The address is copied; the object is not copied.
master_channel_sock_stm	The PEER-state transport::sync_io::Native_socket_stream that just connected to an opposing Client_session_impl. It is moved-to `*this` (and hence becomes `.null()`).

Definition at line 315 of file server_session.hpp.

Member Function Documentation

◆ async_accept_log_in()

template<typename Server_session_impl_t >

template<typename Session_server_impl_t , typename Task_err , typename Cli_app_lookup_func , typename Cli_namespace_func , typename Pre_rsp_setup_func , typename N_init_channels_by_srv_req_func , typename Mdt_load_func >

void ipc::session::Server_session_mv< Server_session_impl_t >::async_accept_log_in	(	Session_server_impl_t *	srv,
		typename Base::Channels *	init_channels_by_srv_req,
		typename Base::Mdt_reader_ptr *	mdt_from_cli_or_null,
		typename Base::Channels *	init_channels_by_cli_req,
		Cli_app_lookup_func &&	cli_app_lookup_func,
		Cli_namespace_func &&	cli_namespace_func,
		Pre_rsp_setup_func &&	pre_rsp_setup_func,
		N_init_channels_by_srv_req_func &&	n_init_channels_by_srv_req_func,
		Mdt_load_func &&	mdt_load_func,
		Task_err &&	on_done_func
	)

protected

For use by internal user Session_server: called no more than once, ideally immediately following ctor, this attempts to get *this asynchronously to almost-PEER state by undergoing the log-in request/response (plus, if needed, init-channel-opening) procedure (the other side of which is done by Client_session_impl::sync_connect()).

On success, on_done_func(Error_code()) is invoked from unspecified thread that is not the user's calling thread. On failure, it does similarly but with a non-success code. If the op does not complete before dtor, then on_done_func(error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER) is invoked at that point.

In the success-case firing, *this is ready to be given to the public user. However it is in almost-PEER state. To achieve PEER state they shall first call init_handlers().

Error_code generated and passed to on_done_func(): session::error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER (see above), those returned by transport::Native_socket_stream::remote_peer_process_credentials(), those emitted by transport::struc::Channel::send(), those emitted by transport::struc::Channel via on-error handler (most likely transport::error::Code::S_RECEIVES_FINISHED_CANNOT_RECEIVE indicating graceful shutdown of opposing process coincidentally during log-in procedure, prematurely ending session while it was starting), error::Code::S_SERVER_MASTER_LOG_IN_REQUEST_CLIENT_APP_DISALLOWED_OR_UNKNOWN, error::Code::S_SERVER_MASTER_LOG_IN_REQUEST_CLIENT_APP_INCONSISTENT_CREDS, those emitted by pre_rsp_setup_func() (in-arg).

Note: If the above list substantially changes, please update Session_server::async_accept() doc header accordingly for user convenience.

Template Parameters

Session_server_impl_t	See `srv`.
Task_err	Handler type matching signature of `flow::async::Task_asio_err`.
Cli_app_lookup_func	Function type that takes a supposed Client_app::m_name and returns the `const Client_app*` with that matching name; or null if it is not a validly registered name according to the data given to the internal user.
Cli_namespace_func	Function type that returns a sufficiently-distinct value for Session_base::cli_namespace(), as Session_base::set_cli_namespace() is required before Server_session can be in PEER state and available to the public user.
Pre_rsp_setup_func	Function type with signature `Error_code F()`.
N_init_channels_by_srv_req_func	See Session_server::async_accept(). Type and arg value forwarded from there.
Mdt_load_func	See Session_server::async_accept(). Type and arg value forwarded from there.

Parameters

srv	The Session_server_impl whose Session_server_impl::async_accept() is invoking the present method. `srv` must exist at least while `this` does, or behavior is undefined. This allows for interaction/cooperation with the "parent" `Session_server` if necessary, such as for shared cross-session resources. Note: you may use `srv->this_session_srv()` to obtain a pointer to the `Session_server`-like object on which the user invoked `async_accept()`. E.g.: Server_session_impl::async_accept_log_in() would get a `Session_server`; shm::classic::Server_session_impl::async_accept_log_in() would get a `shm::classic::Session_server`.
init_channels_by_srv_req	See Session_server::async_accept(). Arg value forwarded from there.
mdt_from_cli_or_null	See Session_server::async_accept(). Arg value forwarded from there.
init_channels_by_cli_req	See Session_server::async_accept(). Arg value forwarded from there.
cli_app_lookup_func	See `Cli_app_lookup_func`.
cli_namespace_func	See `Cli_namespace_func`.
pre_rsp_setup_func	Invoked just before sending successful log-in response to opposing client, which completes the log-in. It takes no arguments – but all `this` accessors up to/including `cli_app_ptr()` shall return real values – and shall return falsy on success; or the reason for failure as Error_code. In the latter case this method shall emit that code as the reason for overall failure. This can be used for setting up resources, such as SHM arena(s), that the client shall count on being available (perhaps at known Shared_name based on `this` accessor values).
n_init_channels_by_srv_req_func	See `N_init_channels_by_srv_req_func`.
mdt_load_func	See `Mdt_load_func`.
on_done_func	See above.

Definition at line 332 of file server_session.hpp.

◆ client_app()

template<typename Server_session_impl_t >

const Client_app * ipc::session::Server_session_mv< Server_session_impl_t >::client_app

The opposing application is described by a Client_app; this is that description.

May be useful in particular when deciding what handlers to set up in init_handlers() when entering PEER state. Returns null if *this is as-if default-cted (i.e., default-cted + not moved-to otherwise; or moved-from).

Returns: Pointer to immutable Client_app; or null if *this is as-if default-cted. The pointer returned, when not straddling a move-to or move-from, is always the same.

Definition at line 323 of file server_session.hpp.

◆ init_handlers() [1/2]

template<typename Server_session_impl_t >

template<typename Task_err >

bool ipc::session::Server_session_mv< Server_session_impl_t >::init_handlers ( Task_err && on_err_func_arg )

Alternative to the other init_handlers().

Using this overload indicates passive-opens are disabled on this side. Otherwise identical to the other init_handlers() overload.

Template Parameters

Task_err See other init_handlers().

Parameters

on_err_func_arg See other init_handlers().

Returns: true normally; false if invoked after already having called an init_handlers() or as-if default-cted.

Definition at line 369 of file server_session.hpp.

◆ init_handlers() [2/2]

template<typename Server_session_impl_t >

template<typename Task_err , typename On_passive_open_channel_handler >

bool ipc::session::Server_session_mv< Server_session_impl_t >::init_handlers	(	Task_err &&	on_err_func_arg,
		On_passive_open_channel_handler &&	on_passive_open_channel_func_arg
	)

To be invoked by public user upon first obtaining *this: memorizes the given on-error and on-passive-open handlers thus moving this Server_session_mv to PEER state wherein it is a formal Session concept impl.

Using this overload indicates passive-opens are enabled on this side.

Suggestion: use client_app() to determine the opposing Client_app, particularly if this Server_app is designed to accept sessions from 2+ Client_apps. (To be clear: Multiple instances (processes) of a given Client_app are always supported. However a given Server_app – specified at Session_server construction time – may well specify only one allowed opposing Client_app.) It is likely that a different on-passive-open handler would be useful depending on Client_app; possibly also different on-error handler.

Template Parameters

Task_err	See Session concept doc header for semantics.
On_passive_open_channel_handler	See Session concept doc header for semantics.

Parameters

on_err_func_arg	On-error handler per semantics in Session concept doc header.
on_passive_open_channel_func_arg	On-passive-open handler per semantics in Session concept doc header.

Returns: true normally; false if invoked after already having called an init_handlers() or as-if default-cted.

Definition at line 359 of file server_session.hpp.

Friends And Related Function Documentation

◆ operator<<()

template<typename Server_session_impl_t >

std::ostream & operator<<	(	std::ostream &	os,
		const Server_session_mv< Server_session_impl_t > &	val
	)

Parameters

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

Returns: os.

Definition at line 375 of file server_session.hpp.

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

session/server_session.hpp
session/session_fwd.hpp

Public Types

Public Member Functions

Protected Member Functions

Related Functions

Additional Inherited Members

Detailed Description

How to use

Error handling

Implementation design/rationale

Facade design

Member Typedef Documentation

◆ Base

Constructor & Destructor Documentation

◆ Server_session_mv()

Member Function Documentation

◆ async_accept_log_in()

◆ client_app()

◆ init_handlers() [1/2]

◆ init_handlers() [2/2]

Friends And Related Function Documentation

◆ operator<<()