Bundles access to stats from the session master channel (SMC) – the internal struc::Channel each Session uses for protocol traffic (log-in, channel-opening, graceful close, liveness status). More...

#include <info_collector.hpp>

Collaboration diagram for ipc::session::Info_collector< Master_structured_channel_t >:

[legend]

Public Types
using	Master_structured_channel = Master_structured_channel_t
	The concrete `struc::Channel` type of the session master channel.

Public Member Functions
bool	master_channel_live () const
	Returns whether the session master channel still exists; `false` means the source `Session` has been destroyed (`*this` being a copy that outlived it; see class doc header, Lifetime section). More...

transport::struc::stat::Channel_stats	master_channel_stats () const
	struc::Channel::stats() of the session master channel of the Session that spawned `*this`. More...

void	master_channel_stats_reset ()
	struc::Channel::reset_stats() of the session master channel of the Session that spawned `*this`. More...

transport::stat::Blob_snd_stats	master_channel_transport_snd_stats () const
	Native_socket_stream::native_handle_snd_stats() of the transport channel powering the session master channel of the Session that spawned `*this`. More...

void	master_channel_transport_snd_stats_reset ()
	Native_socket_stream::native_handle_snd_stats_reset() of the transport channel powering the session master channel of the Session that spawned `*this`. More...

transport::stat::Blob_rcv_stats	master_channel_transport_rcv_stats () const
	Native_socket_stream::native_handle_rcv_stats() of the transport channel powering the session master channel of the Session that spawned `*this`. More...

void	master_channel_transport_rcv_stats_reset ()
	Native_socket_stream::native_handle_rcv_stats_reset() of the transport channel powering the session master channel of the Session that spawned `*this`. More...

Public Attributes
util::stat::Info_dump_format	m_fmt
	Formatting knobs for printing `*this` via `ostream <<`. More...

Related Functions
(Note that these are not member functions.)
template<typename Master_structured_channel_t >
std::ostream &	operator<< (std::ostream &os, const Info_collector< Master_structured_channel_t > &val)
	Prints the entire Info_collector stats bundle to the given `ostream`, formatted per `val.m_fmt` (see Info_collector doc header); or a note that the stats are unavailable, if `!val.master_channel_live()`. More...

Detailed Description

template<typename Master_structured_channel_t>
class ipc::session::Info_collector< Master_structured_channel_t >

Bundles access to stats from the session master channel (SMC) – the internal struc::Channel each Session uses for protocol traffic (log-in, channel-opening, graceful close, liveness status).

The user obtains an Info_collector* via Session::info_collector().

Two levels of stats are exposed as of this writing:

Structured-channel stats (transport::struc::stat::Channel_stats): master_channel_stats(), master_channel_stats_reset().
Transport-level stats from the underlying Native_socket_stream: master_channel_transport_snd_stats(), master_channel_transport_snd_stats_reset(), master_channel_transport_rcv_stats(), master_channel_transport_rcv_stats_reset().

One can work in standard flow::util::stat ways with each stat-set accessed via *_stats(). This includes regular struct member reads (of course), sum/aggregation with others (flow::util::stats_aggregate() et al), and printing via ostream << print(...).

W/r/t the latter operation – printing – it is also possible to print all the *_stats() in one shot: simply use os << *this. You may use the simple knobs in (public, mutable) m_fmt to affect the format of the print-op (e.g.: multi-line versus single-line).

Note: Slight subtlety: A *this is a live-accessor of information, not a store (dump) of information. It has those *_reset() methods, for one thing; but more to the point: It is not a classic struct with public data members storing the stats/info (cf., say, the SHM-providers' Info_dump pattern – e.g., shm::classic::Pool_arena::Info_dump). Each *_stats() call will grab a snapshot of those data as of this moment; they may not equal what it returns a split-second later. Session::info_collector(), which returns us, returns a pointer (this) and does not itself capture any stats/info. (Cf., say, shm::classic::Pool_arena::info_dump() which returns a new stats/info-filled object.); Corollary: ostream << *this shall internally perform all of *_stats() info-grabbing ops. (Cf. ostream << of Pool_arena::Info_dump; it outputs serializations of already-stored stats/info.)

Subject matter

The aforementioned SMC (structured master channel) stats track the behavior of an internal facility. One does not normally concern themselves with these workings; but in short ipc::session relies on a struc::Channel over a transport::Native_socket_stream to establish and end any Session; as well as opening on-demand user Channels throughout, plus liveness detection (so that if the opposing side ends the session, this side will quickly know and report to the user, who should stop that IPC session/start a new one/etc.). Some potential ways in which stats about this are useful:

to ascertain that the background traffic exchanged uses negligible resources (versus the user's actual IPC work which ipc::session makes possible by establishing IPC conversations a/k/a sessions);
in long-lived processes to get an idea of how many channels are opened when;
to generally understand what's happening behind the scenes.

Thread safety

It is safe to call all methods (const or otherwise) at any time from any thread (even though the Session operates the SMC in the background).

ostream << *this is not formally safe w/r/t a concurrent modification of *this m_fmt.

Lifetime

The pointer returned by Session::info_collector() is stable from PEER state (for Client_session, after sync_connect() returns; for Server_session throughout its lifetime once the user obtains access to it via successful Session_server::async_accept() or equivalent). Before PEER state, Client_session::info_collector() returns null.

That pointer points to a member of the Session and hence must not be dereferenced beyond that Session's life. However Info_collector is copyable, and a copy may safely outlive the source Session: once the Session (and hence the SMC) is gone – master_channel_live() returns false – the stat-getters return all-zero values; the resetters no-op; and printing *this yields a note that the stats are unavailable.

Template Parameters

Master_structured_channel_t This is an implementation detail. The concrete type for the user is aliased as Session::Info_collector.

Member Function Documentation

◆ master_channel_live()

template<typename Master_structured_channel_t >

bool ipc::session::Info_collector< Master_structured_channel_t >::master_channel_live

Returns whether the session master channel still exists; false means the source Session has been destroyed (*this being a copy that outlived it; see class doc header, Lifetime section).

When false: the stat-getters return all-zero values; the resetters no-op; printing *this yields a note that the stats are unavailable.

Returns: See above.

◆ master_channel_stats()

template<typename Master_structured_channel_t >

transport::struc::stat::Channel_stats ipc::session::Info_collector< Master_structured_channel_t >::master_channel_stats

struc::Channel::stats() of the session master channel of the Session that spawned *this.

Returns: See above; or an all-zero value if !master_channel_live().

◆ master_channel_stats_reset()

template<typename Master_structured_channel_t >

void ipc::session::Info_collector< Master_structured_channel_t >::master_channel_stats_reset

struc::Channel::reset_stats() of the session master channel of the Session that spawned *this.

No-op if !master_channel_live().

◆ master_channel_transport_rcv_stats()

template<typename Master_structured_channel_t >

transport::stat::Blob_rcv_stats ipc::session::Info_collector< Master_structured_channel_t >::master_channel_transport_rcv_stats

Native_socket_stream::native_handle_rcv_stats() of the transport channel powering the session master channel of the Session that spawned *this.

Note: Same note as for master_channel_transport_snd_stats().

Returns: See above; or an all-zero value if !master_channel_live().

◆ master_channel_transport_rcv_stats_reset()

template<typename Master_structured_channel_t >

void ipc::session::Info_collector< Master_structured_channel_t >::master_channel_transport_rcv_stats_reset

Native_socket_stream::native_handle_rcv_stats_reset() of the transport channel powering the session master channel of the Session that spawned *this.

No-op if !master_channel_live().

◆ master_channel_transport_snd_stats()

template<typename Master_structured_channel_t >

transport::stat::Blob_snd_stats ipc::session::Info_collector< Master_structured_channel_t >::master_channel_transport_snd_stats

Native_socket_stream::native_handle_snd_stats() of the transport channel powering the session master channel of the Session that spawned *this.

Note: Despite the aforementioned reference to native_handle, the stats struct really covers both (arguably mainly) data being trafficked as well as native handles (which are indeed involved in various things, notably opening Native_socket_stream-containing channels through the Session). It's an artifact (not that we're saying it's a bad thing) of how concepts interact – Native_handle_sender versus Blob_sender and so on.

Returns: See above; or an all-zero value if !master_channel_live().

◆ master_channel_transport_snd_stats_reset()

template<typename Master_structured_channel_t >

void ipc::session::Info_collector< Master_structured_channel_t >::master_channel_transport_snd_stats_reset

Native_socket_stream::native_handle_snd_stats_reset() of the transport channel powering the session master channel of the Session that spawned *this.

No-op if !master_channel_live().

Friends And Related Function Documentation

◆ operator<<()

template<typename Master_structured_channel_t >

std::ostream & operator<<	(	std::ostream &	os,
		const Info_collector< Master_structured_channel_t > &	val
	)

Prints the entire Info_collector stats bundle to the given ostream, formatted per val.m_fmt (see Info_collector doc header); or a note that the stats are unavailable, if !val.master_channel_live().

Parameters

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

Returns: os.

Member Data Documentation

◆ m_fmt

template<typename Master_structured_channel_t >

util::stat::Info_dump_format ipc::session::Info_collector< Master_structured_channel_t >::m_fmt

Formatting knobs for printing *this via ostream <<.

util::stat::Info_dump_format is also used by other Flow-IPC code; here m_multiline is honored, while m_verbose has no effect (there is no verbose-only content to gate).

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

session/info_collector.hpp
session/session_fwd.hpp

Public Types

Public Member Functions

Public Attributes

Related Functions

Detailed Description

Subject matter

Thread safety

Lifetime

Member Function Documentation

◆ master_channel_live()

◆ master_channel_stats()

◆ master_channel_stats_reset()

◆ master_channel_transport_rcv_stats()

◆ master_channel_transport_rcv_stats_reset()

◆ master_channel_transport_snd_stats()

◆ master_channel_transport_snd_stats_reset()

Friends And Related Function Documentation

◆ operator<<()

Member Data Documentation

◆ m_fmt