Implements Session concept on the Client_app end: a Session_mv that first achieves PEER state by connecting to an opposing Session_server_mv via Client_session_mv::sync_connect(). More...
#include <client_session.hpp>
Public Types | |
| using | Base = Session_mv< Client_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< Client_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 | |
| template<typename On_passive_open_channel_handler , typename Task_err > | |
| Client_session_mv (flow::log::Logger *logger_ptr, const Client_app &cli_app_ref, const Server_app &srv_app_ref, Task_err &&on_err_func, On_passive_open_channel_handler &&on_passive_open_channel_func) | |
| Constructs (passive-opens allowed form) in NULL state. More... | |
| template<typename Task_err > | |
| Client_session_mv (flow::log::Logger *logger_ptr, const Client_app &cli_app_ref, const Server_app &srv_app_ref, Task_err &&on_err_func) | |
| Constructs (passive-opens disallowed form) in NULL state. More... | |
| Mdt_builder_ptr | mdt_builder () |
Implements Session API per contract; plus usable to generate blank mdt argument for advanced sync_connect() overload. More... | |
| bool | sync_connect (Error_code *err_code=0) |
To be invoked in NULL state only, and not as-if default-cted, it synchronously and non-blockingly attempts to connect to an opposing Session_server; and synchronously reports failure or success, the latter showing *this has entered PEER state. More... | |
| bool | sync_connect (const typename Base::Mdt_builder_ptr &mdt, typename Base::Channels *init_channels_by_cli_req_pre_sized=0, typename Base::Mdt_reader_ptr *mdt_from_srv_or_null=0, typename Base::Channels *init_channels_by_srv_req=0, Error_code *err_code=0) |
| Identical to the simpler sync_connect() overload but offers added advanced capabilities: metadata exchange; initial-channel opening. More... | |
| Public Member Functions inherited from ipc::session::Session_mv< Client_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... | |
Related Functions | |
(Note that these are not member functions.) | |
| template<typename Client_session_impl_t > | |
| std::ostream & | operator<< (std::ostream &os, const Client_session_mv< Client_session_impl_t > &val) |
Prints string representation of the given Client_session_mv to the given ostream. More... | |
| Related Functions inherited from ipc::session::Session_mv< Client_session_impl_t > | |
| std::ostream & | operator<< (std::ostream &os, const Session_mv< Client_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< Client_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< Client_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< Client_session_impl_t > | |
| using | Impl = Client_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... | |
| Protected Member Functions inherited from ipc::session::Session_mv< Client_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... | |
Detailed Description
class ipc::session::Client_session_mv< Client_session_impl_t >
Implements Session concept on the Client_app end: a Session_mv that first achieves PEER state by connecting to an opposing Session_server_mv via Client_session_mv::sync_connect().
See overview of Session hierarchy in namespace ipc::session doc header; then come back here if desired.
It is unusual to use Client_session_mv template directly. If you do wish to set up a client-side session peer, and you do not require SHM support, then use Client_session alias template. The client-specific API, particularly ctor and sync_connect(), is in Client_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 client-side session peer, but you do require SHM support, then use shm::classic::Client_session or similar (for other SHM-provider(s)). However Client_session (hence Client_session_mv to which it aliases) is its super-class, and until PEER state is reached its API remains the only relevant API to use. Once Client_session_mv::sync_connect() 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_mv::app_shm()`) become of interest.
Summary hierarchy:
- Session_mv (Session concept impl)
- ^– Client_session_mv (adds sync_connect())
- =alias= Client_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) - =alias= shm::classic::Client_session (parameterizes by aforementioned knobs = template params)
We may refer to Client_session_mv as Client_session below; particularly since it is likeliest used in that form by the user.
How to use
Per the Session concept a Client_session is open/capable of operation when in PEER state only. A Client_session object is always in one of 2 states:
- NULL. In this state, the object is doing nothing; neither connected nor connecting.
- PEER. At this stage it exactly implements the Session concept. See Session_mv. Reminder: It is not possible to exit PEER state.
To get from NULL state to PEER state: Use Session_server on the other side. On this side construct a Client_session (always in NULL state) and invoke sync_connect() which will synchronously and non-blockingly try to move to PEER state (mission accomplished). If the connect fails, it will stay in NULL state. Being moved-from makes a *this as-if default-cted; therefore also moves to NULL state.
Once in PEER state Client_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).
A related reminder:
- sync_connect() or the opposing
async_accept()or both may optionally specify that 1+ init-channels be opened before this and the opposing Session is in PEER state and emitted to user. This may be a sufficient replacement of, or complementary to, active-open/passive-open APIs available once the Session is in PEER state/emitted to user. If not sufficient: - Either side (being a Session_mv = Session) has open_channel(), and hence either side can accept passive-opens when the opposing side invokes open_channel().
- However it is possible to configure either side to not accept passive-opens; meaning to be useful such a side shall be exclusively doing open_channel() (active-opens). One might conclude, then, that Server_session should be passive-opening, while Client_session should be active-opening. That is not the case. In PEER state established on both sides, the 2 sides are identical in this respect. If both sides are configured to accept passive-opens, then there's no question. If one side is so configured, it can be either side. If both sides are so configured, the session is useless, as every open_channel() will fail (unless one has set up init-channels).
- In Client_session, one specifies the on-passive-open handler in ctor; to disable passive-opens use the ctor that omits that handler.
Why no async-connect method, only sync-connect?
Without networking, the other side (Session_server) either exists/is listening; or no. Connecting is a synchronous, non-blocking operation; so an async_connect() API in this context only makes life harder for the user. (However, there are some serious plans to add a networking-capable counterpart (probably via TCP at least) to Native_socket_stream and therefore Client_session_mv; such a networky-client-session class will almost certainly have an async_connect(), while its sync_connect() will probably become potentially blocking.)
- Note
- Impl detail for exposition purposes: transport::Native_socket_stream is used internally by ipc::session to establish internal session-related IPC. That is a Unix domain socket: local stream connection. This can be extended, relatively cheaply in terms of effort, to work over networked-TCP sockets. Based on that work, Client_session and Session_server hierarchies can be relatively cheaply extended to also be network-enabled in some form.
-
If some form of
*thisbecomes network-enabled, open_channel() too will need an async form most likely, while existing open_channel() would become potentially-blocking.
Thread safety and handler invocation semantics
These follow the Session concept policies.
Error handling
Once in PEER state, error handling follows the Session concept (= Session_mv concrete class) doc header. Up to that point (in NULL state) there are no public asynchronous operations; there is just sync_connect() which succeeds or fails synchronously and quickly.
Implementation design/rationale
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. Client_session_mv merely repeats the same technique but on the API additions at its own level; in particular the explicit ctors and especially sync_connect().
The impl object is available via Session_mv::impl() (which is protected). What type does this object have though? Answer: Client_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 Client_session => impl = Client_session_impl.
- Chose shm::classic::Client_session => impl = shm::classic::Client_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.
- See also
- Client_session_impl doc header.
- See also
- Session: implemented concept.
- Template Parameters
-
Client_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 143 of file client_session.hpp.
Member Typedef Documentation
◆ Base
| using ipc::session::Client_session_mv< Client_session_impl_t >::Base = Session_mv<Client_session_impl_t> |
Short-hand for our base class. To the user: note its public API is inherited.
Definition at line 150 of file client_session.hpp.
Constructor & Destructor Documentation
◆ Client_session_mv() [1/2]
|
explicit |
Constructs (passive-opens allowed form) in NULL state.
To be useful, invoke sync_connect() next.
- Parameters
-
logger_ptr Logger to use for logging subsequently. cli_app_ref Properties of this client application. The address is copied; the object is not copied. srv_app_ref Properties of the opposing server application. The address is copied; the object is not copied. on_err_func On-error handler. See Session concept doc header for semantics. on_passive_open_channel_func On-passive-open handler. See Session concept doc header for semantics.
- Template Parameters
-
On_passive_open_channel_handler See Session concept doc header for semantics. Task_err See Session concept doc header for semantics.
Definition at line 376 of file client_session.hpp.
◆ Client_session_mv() [2/2]
|
explicit |
Constructs (passive-opens disallowed form) in NULL state.
To be useful, invoke sync_connect() next.
- Parameters
-
logger_ptr Logger to use for logging subsequently. cli_app_ref Properties of this client application. The address is copied; the object is not copied. srv_app_ref Properties of the opposing server application. The address is copied; the object is not copied. on_err_func On-error handler. See Session concept doc header for semantics.
- Template Parameters
-
Task_err See Session concept doc header for semantics.
Definition at line 390 of file client_session.hpp.
Member Function Documentation
◆ mdt_builder()
| Mdt_builder_ptr ipc::session::Client_session_mv< Client_session_impl_t >::mdt_builder | ( | ) |
Implements Session API per contract; plus usable to generate blank mdt argument for advanced sync_connect() overload.
That is: can additionally be invoked in NULL state (before sync_connect() or between a failed attempt and the next attempt). The return value can be used only as follows; otherwise undefined behavior results:
- If invoked in NULL state: pass to sync_connect().
- If invoked in PEER state: pass to open_channel().
- Returns
- See above.
- See also
- Session::mdt_builder(): implemented concept.
◆ sync_connect() [1/2]
| bool ipc::session::Client_session_mv< Client_session_impl_t >::sync_connect | ( | const typename Base::Mdt_builder_ptr & | mdt, |
| typename Base::Channels * | init_channels_by_cli_req_pre_sized = 0, |
||
| typename Base::Mdt_reader_ptr * | mdt_from_srv_or_null = 0, |
||
| typename Base::Channels * | init_channels_by_srv_req = 0, |
||
| Error_code * | err_code = 0 |
||
| ) |
Identical to the simpler sync_connect() overload but offers added advanced capabilities: metadata exchange; initial-channel opening.
The other overload is identical to sync_connect(mdt_builder(), nullptr, nullptr, nullptr, err_code) and requires the opposing async_accept() to similarly not use the corresponding features.
Client->server metadata exchange
Client may wish to provide information in some way, but without a structured channel – or any channel – yet available, this provides an opportunity to do so in a structured way with a one-off message available at session open, together with the opposing Session object itself.
Similarly to how it is optionally done on a per-channel-open basis (open_channel()): call mdt = mdt_builder(); fill out the resulting capnp structure *mdt; then pass mdt to sync_connect(). Opposing async_accept() shall receive deserializable Mdt_reader together with the freshly-opened Session, though they may choose to ignore it.
To omit using this feature, skip the "fill out the resulting capnp structure" step. You must still call mdt_builder() and pass-in the result. (The other overload does so.)
Server->client metadata exchange
This is the reverse of the above. Whatever the opposing server chose to supply as server->client metadata shall be deserializable at *mdt_from_srv_or_null on successful return from sync_connect(). If mdt_from_srv_or_null is null, the srv->cli metadata shall be ignored.
Init-channels by client request
Once the session is open, open_channel() and the on-passive-open handler may be used to open channels at will. In many use cases, however, a certain number of channels is required immediately before work can really begin (and, frequently, no further channels are even needed). For convenience (to avoid asynchrony/boiler-plate) the init-channels feature will pre-open a requested # of channels making them available right away, together with the freshly-open session – to both sides.
The client may request 0 or more init-channels. They shall be opened and placed into *init_channels_by_cli_req_pre_sized; its ->size() at entry to the method indicates the number of channels requested. If null, it is treated as if ->size() == 0, meaning no init-channels-by-client-request are opened.
Init-channels by server request
This is the reverse of the above. The opposing side shall request 0 or more init-channels-by-server-request; that number of channels shall be opened; and they will be placed into *init_channels_by_srv_req which shall be ->resize()d accordingly on successful return from sync_connect().
init_channels_by_srv_req being null is allowed, but only if the opposing server requests 0 init-channels-by-server-request. Otherwise an error shall be emitted (see below).
- Parameters
-
mdt See above. init_channels_by_cli_req_pre_sized See above: null or pointer to container of Channel_objwith.size()specifying how many channels this side is requesting to be opened on its behalf; each element will be move-assigned a PEER-stateChannel_objon success. Recommend simply ct-ing with(n)or.resize(n)which loads it with default-cted (NULL-state) objects to be replaced. null is treated same as.empty().mdt_from_srv_or_null See above: null or pointer to Readerof metadata which shall be set for access on success.init_channels_by_srv_req See above: null or pointer to container of Channel_objwhich shall be.clear()ed and replaced by a container of PEER-stateChannel_objon success the number being specified by the opposing (server) side. The number may be zero. null is allowed if and only if the number is zero; otherwise error::Code::S_INVALID_ARGUMENT is emitted.err_code See other sync_connect() overload. Note the above target (pointer) args are touched only if no error is emitted via this standard Flow error reporting mechanism.
- Returns
- See other sync_connect() overload.
Definition at line 406 of file client_session.hpp.
◆ sync_connect() [2/2]
| bool ipc::session::Client_session_mv< Client_session_impl_t >::sync_connect | ( | Error_code * | err_code = 0 | ) |
To be invoked in NULL state only, and not as-if default-cted, it synchronously and non-blockingly attempts to connect to an opposing Session_server; and synchronously reports failure or success, the latter showing *this has entered PEER state.
Failure means *this remains in NULL state.
If invoked outside of NULL state, or if it is as-if default-cted (i.e., default-cted or moved-from), this returns false and otherwise does nothing.
Note that *this (modulo moves) that has entered PEER state can never change state subsequently (even on transmission error); once a PEER, always a PEER.
How does it know "where" the Session_server is listening?
While details are internal, abstractly speaking this is determined by the Server_app passed to the ctor. Internal detail (for exposition/general knowledge):
- The server application maintains a CNS (Current Namespace Store, a/k/a PID) file. Only at most 1 server instance (a/k/a process) shall be active at a time. The CNS contents – which are simply the active server app process's PID – determine "where" this
Client_sessionwill connect, and all other internally used cross-process resources (sockets, MQs, SHM pools...) are similarly segregated among different instances of the Server_app-described application. - The location of this file is determined by Server_app contents. Namely, Server_app::m_name, at least, is unique per Server_app in the universe, and most of the PID file's name comprises it; and its location comprises Server_app::m_kernel_persistent_run_dir_override and/or /var/run (or equivalent).
- sync_connect() reads the CNS (PID) file at that location, unique among
Server_apps. Now it knows "where" to connect in order to open the session; so it won't accidentally connect to some old zombie instance of the Server_app (its PID wouldn't be in the CNS file any longer) or another application entirely (its PID file would be located elsewhere and never accessed by this sync_connect()).
What if the CNS (PID) file does not exist? What if server is inactive?
Then sync_connect() will quickly fail (file-not-found or connection-refused error). Shouldn't we supply some API to await its appearance and actively listening? Answer: Probably not. Why? Answer: Consider the situation where the PID file is there, but it belongs to a now-exited instance of the Server_app; let's say it is currently suspended or restarting. sync_connect() will fail then too: There is nothing listening (anymore) at the advertised PID. So it'll quickly fail (connection-refused error). So then we'd also need an API to await an active server's appearance whether or not the PID exists. That leads to the following to-do:
- Todo:
- Consider adding an optional mode/feature to allow to wait through the condition wherein CNS (PID) file does not exist, or it does but the initial session-open connect op would be refused; instead it detects these relatively common conditions (server not yet up and/or is restarting and/or is operationally suspended for now, etc.) as normal and waits until the condition is cleared. Without this mode, a typical user would probably do something like: oh, sync_connect() failed; let's sleep 1 sec and try again (rinse/repeat). It's not awful, but we might as well make it easier and more responsive out of the box (optionally). Upon resolving this to-do please update the Manual section Sessions: Setting Up an IPC Context accordingly.
- See also
- Class doc header, section "Why no async-connect method, only sync-connect?" for potentially interesting context.
- Returns
falseif and only if invoked outside of NULL state; or if*thisis as-if default-cted.
- Parameters
-
err_code See flow::Error_codedocs for error reporting semantics. Error_code generated: session::error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER (destructor called, canceling all pending ops; spiritually identical toboost::asio::error::operation_aborted), interprocess-mutex-related errors (probably from boost.interprocess) w/r/t reading the CNS (PID file), file-related system errors w/r/t reading the CNS (PID file) (see Session_server doc header for background), error::Code::S_CLIENT_NAMESPACE_STORE_BAD_FORMAT (bad CNS contents), those emitted by transport::Native_socket_stream::sync_connect(), 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_CLIENT_MASTER_LOG_IN_RESPONSE_BAD, error::Code::S_INVALID_ARGUMENT (other side expected other sync_connect() overload with non-nullinit_channels_by_srv_reqarg).
Definition at line 400 of file client_session.hpp.
Friends And Related Function Documentation
◆ operator<<()
|
related |
Prints string representation of the given Client_session_mv to the given ostream.
- Parameters
-
os Stream to which to write. val Object to serialize.
- Returns
os.
Definition at line 419 of file client_session.hpp.
The documentation for this class was generated from the following files:
- session/client_session.hpp
- session/session_fwd.hpp
