ipc::session::Info_collector< Master_structured_channel_t > Class Template Reference

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 >:

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

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...

Private Types
using	Master_structured_channel_ptr = boost::shared_ptr< Master_structured_channel >
	Short-hand for shared_ptr to Master_structured_channel. More...
using	Master_structured_channel_observer = boost::weak_ptr< Master_structured_channel >
	Short-hand for weak_ptr observer of Master_structured_channel_ptr. More...

Private Member Functions
	Info_collector (const Master_structured_channel_ptr &master_channel)
	Constructs the collector, capturing a weak_ptr to the session master channel. More...

Private Attributes
Master_structured_channel_observer	m_master_channel
	weak_ptr to the session master channel. More...

Friends
struct	Info_collector_dtl
	Attorney granting internal code access to at least the private ctor. 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.

Impl notes

It is quite straightforward, once the situation has gotten to *this existing. The only question that arises, we think, is thread safety: we guarantee above that they can call any of our methods anytime during the lifetime of the generating Session. There are two levels to that:

• Is the saved pointer m_master_channel pointing to the right thing, and is that thing alive? Answer: yes, as by the time either Client_session_impl or Server_session_impl creates a *this, and the user has access to the Session in the first place: each of those classes internally promises the pointee SMC data member stays around until the destruction of the ..._impl and its containing Session.
• Are the actual calls to which we forward safe to call, while the SMC (a struc::Channel) is doing concurrent work (receiving traffic and such)? Answer: yes:
  • struc::Channel::stats() (and stats_reset()) internally lock the SMC's own mutex – advertised as safe-anytime; we are just another user in that sense.
  • struc::Channel::owned_channel() and struc::Channel::owned_channel_mutable() return flow::util::Locked_proxys instead of raw ptrs/refs; as a result the async-I/O-pattern Channel's internal mutex is locked through the end of the expression (in our case ...->*_stats[_reset]()). We use those (as of this writing there is no alternative/not-locking way in fact).

Note the Lifetime section speaks only of Session destruction causing !master_channel_live(). Internally there is also a degenerate window: Server_session_impl's init-channel-opening failure path resets the SMC shared_ptr after having emplaced its Info_collector member. However that is not user-reachable: a failed Session_server::async_accept() leaves the user's target Server_session empty (as-if default-cted), so the user never sees the affected ..._impl. And even if some future refactor changed that: the graceful !master_channel_live() semantics make the window moot anyway.

Regarding stat-related *stats_configure_...()s, such as on struc::Channel at least: Naively it might make sense to expose/forward those too. However, as of this writing, that would make no sense: The relevant Channels are already Channel::start()ed by the time the user has access to the relevant Session.

Lastly regarding Master_structured_channel, which is a template parameter: The type of the SMC object in Client_session_impl and Server_session_impl is "almost" concrete but does depend on the typename Mdt_payload parameter, such as to Client_session and Server_session and equivalents, that must be supplied by the user (with a default of Void, in the likely case they do not wish to use that feature). As for what Mdt_payload is for: see Session concept. That topic is irrelevant to us here though.

Template Parameters

Master_structured_channel_t

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

Definition at line 139 of file info_collector.hpp.

Member Typedef Documentation

Master_structured_channel

template<typename Master_structured_channel_t >

using ipc::session::Info_collector< Master_structured_channel_t >::Master_structured_channel = Master_structured_channel_t

The concrete struc::Channel type of the session master channel.

Definition at line 145 of file info_collector.hpp.

Master_structured_channel_observer

template<typename Master_structured_channel_t >

using ipc::session::Info_collector< Master_structured_channel_t >::Master_structured_channel_observer = boost::weak_ptr<Master_structured_channel>

private

Short-hand for weak_ptr observer of Master_structured_channel_ptr.

Definition at line 228 of file info_collector.hpp.

Master_structured_channel_ptr

template<typename Master_structured_channel_t >

using ipc::session::Info_collector< Master_structured_channel_t >::Master_structured_channel_ptr = boost::shared_ptr<Master_structured_channel>

private

Short-hand for shared_ptr to Master_structured_channel.

Definition at line 225 of file info_collector.hpp.

Constructor & Destructor Documentation

Info_collector()

template<typename Master_structured_channel_t >

ipc::session::Info_collector< Master_structured_channel_t >::Info_collector ( const Master_structured_channel_ptr &  master_channel )

explicitprivate

Constructs the collector, capturing a weak_ptr to the session master channel.

Only callable by detail::Info_collector_dtl::ct_base().

Parameters

master_channel

The SMC; must be non-null. A weak_ptr observer is stored.

Definition at line 263 of file info_collector.hpp.

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.

Definition at line 270 of file info_collector.hpp.

Referenced by ipc::session::Info_collector< Master_structured_channel_t >::operator<<().

Here is the caller graph for this function:

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().

Definition at line 276 of file info_collector.hpp.

Referenced by ipc::session::Info_collector< Master_structured_channel_t >::operator<<().

Here is the caller graph for this function:

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().

Definition at line 285 of file info_collector.hpp.

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().

Definition at line 315 of file info_collector.hpp.

Referenced by ipc::session::Info_collector< Master_structured_channel_t >::operator<<().

Here is the caller graph for this function:

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().

Definition at line 325 of file info_collector.hpp.

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().

Definition at line 295 of file info_collector.hpp.

Referenced by ipc::session::Info_collector< Master_structured_channel_t >::operator<<().

Here is the caller graph for this function:

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().

Definition at line 305 of file info_collector.hpp.

Friends And Related Function Documentation

Info_collector_dtl

template<typename Master_structured_channel_t >

friend struct Info_collector_dtl

friend

Attorney granting internal code access to at least the private ctor.

Definition at line 220 of file info_collector.hpp.

operator<<()

template<typename Master_structured_channel_t >

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

related

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.

Definition at line 335 of file info_collector.hpp.

References ipc::session::Info_collector< Master_structured_channel_t >::m_fmt, ipc::util::stat::Info_dump_format::m_multiline, ipc::session::Info_collector< Master_structured_channel_t >::master_channel_live(), ipc::session::Info_collector< Master_structured_channel_t >::master_channel_stats(), ipc::session::Info_collector< Master_structured_channel_t >::master_channel_transport_rcv_stats(), and ipc::session::Info_collector< Master_structured_channel_t >::master_channel_transport_snd_stats().

Here is the call graph for this function:

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).

Definition at line 154 of file info_collector.hpp.

Referenced by ipc::session::Info_collector< Master_structured_channel_t >::operator<<().

m_master_channel

template<typename Master_structured_channel_t >

Master_structured_channel_observer ipc::session::Info_collector< Master_structured_channel_t >::m_master_channel

private

weak_ptr to the session master channel.

Semantics/rationale (why weak_ptr?)

Internally to Client_session_impl and Server_session_impl, the SMC shared_ptr is immutable from PEER state through dtor – even on session hosing the channel object remains alive in both Client_session_impl and Server_session_impl (and their public-facing subclasses). So lock() succeeds while the source Session lives (modulo the degenerate never-reached-working-order cases; see class doc header, Lifetime section) and fails once it is destroyed – which is possible to observe from *this being a copy that outlived it. That distinction is exactly master_channel_live(); the accessors and ostream << use it to behave gracefully (zeroes/no-op/note) rather than access a dead SMC.

Definition at line 255 of file info_collector.hpp.

---

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

• session/info_collector.hpp
• session/session_fwd.hpp