so_5::msg_tracing Namespace Reference

Public part of message delivery tracing mechanism. More...

Namespaces
	impl
	Implementation details of message delivery tracing mechanism.

Classes
struct	compound_action_description_t
	An information about compound description of message-related action. More...
class	filter_t
	An interface of filter for trace messages. More...
class	holder_t
	Interface of holder of message tracer and message trace filter objects. More...
struct	message_instance_info_t
	An information about a message instance. More...
struct	msg_source_t
	An information about message source. More...
class	trace_data_t
	An interface of object for accessing trace details. More...
class	tracer_t
	Interface of tracer object. More...

Typedefs
using	tracer_unique_ptr_t = std::unique_ptr< tracer_t >
	A short alias for unique_ptr to tracer. More...
using	filter_shptr_t = intrusive_ptr_t< filter_t >
	An alias for smart pointer to filter. More...

Enumerations
enum	status_t { status_t::disabled, status_t::enabled }
	Status of message delivery tracing. More...
enum	message_or_signal_flag_t { message_or_signal_flag_t::message, message_or_signal_flag_t::signal }
	A flag for message/signal dichotomy. More...
enum	msg_source_type_t { msg_source_type_t::mbox, msg_source_type_t::mchain, msg_source_type_t::unknown }
	Type of message source. More...

Functions
SO_5_FUNC tracer_unique_ptr_t	std_cout_tracer ()
	Factory for tracer which uses std::cout stream. More...
SO_5_FUNC tracer_unique_ptr_t	std_cerr_tracer ()
	Factory for tracer which uses std::cerr stream. More...
SO_5_FUNC tracer_unique_ptr_t	std_clog_tracer ()
	Factory for tracer which uses std::clog stream. More...
template<typename L >
filter_shptr_t	make_filter (L &&lambda)
	A helper function for creation of new filter from lambda-function. More...
filter_shptr_t	make_enable_all_filter ()
	A helper function for creation of filter that enables all messages. More...
filter_shptr_t	make_disable_all_filter ()
	A helper function for creation of filter that disables all messages. More...
filter_shptr_t	no_filter ()
	A helper function to be used when it is necessary to remove msg_tracing's filter. More...

Detailed Description

Public part of message delivery tracing mechanism.

Since

v.5.5.9

Typedef Documentation

filter_shptr_t

using so_5::msg_tracing::filter_shptr_t = typedef intrusive_ptr_t< filter_t >

An alias for smart pointer to filter.

Since

v.5.5.22

tracer_unique_ptr_t

using so_5::msg_tracing::tracer_unique_ptr_t = typedef std::unique_ptr< tracer_t >

A short alias for unique_ptr to tracer.

Since

v.5.5.9

Enumeration Type Documentation

message_or_signal_flag_t

enum so_5::msg_tracing::message_or_signal_flag_t

strong

A flag for message/signal dichotomy.

Since

v.5.5.22

Enumerator
message
signal

msg_source_type_t

enum so_5::msg_tracing::msg_source_type_t

strong

Type of message source.

Message can be sent to a mbox or to a mchain. This mbox/mchain will be a message source for a subscriber. Sometimes it is necessary to know what is actual type of message source: mbox or mchain.

Since

v.5.5.22

Enumerator
mbox
mchain
unknown	There is no information about a type of actual message source. This information can be lost if message was redirected or transformed during delivery. Or there is no information about message source in the point where message is handled. For example, when message arrived to a subscriber it is unknown was message sent to mchain or to mbox.

status_t

enum so_5::msg_tracing::status_t

strong

Status of message delivery tracing.

Since

v.5.5.9

Enumerator
disabled	Message delivery tracing is disabled.
enabled	Message delivery tracing is enabled.

Function Documentation

make_disable_all_filter()

filter_shptr_t so_5::msg_tracing::make_disable_all_filter ( )

inline

A helper function for creation of filter that disables all messages.

Usage example:

so_5::launch([](so_5::environment_t & env) {...},
  [](so_5::environment_params_t & params) {
    // Turn message delivery tracing on.
    params.message_delivery_tracer(
      so_5::msg_tracing::std_cout_tracer());
    // Disable all trace messages.
    // It is expected that trace filter will be changed in the future.
    params.message_delivery_tracer_filter(
      so_5::msg_tracing::make_disable_all_filter());
    ...
  } );

Since

v.5.5.22

Examples:

so_5/selective_msg_tracing/main.cpp.

make_enable_all_filter()

filter_shptr_t so_5::msg_tracing::make_enable_all_filter ( )

inline

A helper function for creation of filter that enables all messages.

Usage example:

so_5::launch([](so_5::environment_t & env) {...},
  [](so_5::environment_params_t & params) {
    // Turn message delivery tracing on.
    params.message_delivery_tracer(
      so_5::msg_tracing::std_cout_tracer());
    // Enable all trace messages.
    params.message_delivery_tracer_filter(
      so_5::msg_tracing::make_enable_all_filter());
    ...
  } );

Since

v.5.5.22

make_filter()

template<typename L >

filter_shptr_t so_5::msg_tracing::make_filter

(

L &&

lambda

)

A helper function for creation of new filter from lambda-function.

In most cases usage of that function must easier than implementation of a new class derived from filter_t interface.

Usage example:

void some_agent_t::so_evt_start() {
  // Create a filter which will enable only messages from specific mboxes.
  std::set<so_5::mbox_id_t> selected_ids{...};
  so_environment().change_message_delivery_tracer_filter(
    so_5::msg_tracing::make_filter( 
      [ids = std::move(selected_ids)](so_5::msg_tracing::trace_data_t & td) {
        const auto ms = td.msg_source();
        return ms && 1 == ids.count(ms->m_id);
      } ) );
  ...
}

Since

v.5.5.22

Examples:

so_5/nohandler_msg_tracing/main.cpp, and so_5/selective_msg_tracing/main.cpp.

no_filter()

filter_shptr_t so_5::msg_tracing::no_filter ( )

inline

A helper function to be used when it is necessary to remove msg_tracing's filter.

Usage example:

so_5::launch([](so_5::environment_t & env) {...},
  [](so_5::environment_params_t & params) {
    // Turn message delivery tracing on.
    params.message_delivery_tracer(
      so_5::msg_tracing::std_cout_tracer());
    // Disable all trace messages.
    // It is expected that trace filter will be changed in the future.
    params.message_delivery_tracer_filter(
      so_5::msg_tracing::make_disable_all_filter());
    ...
  } );
...
void some_agent_t::turn_msg_tracing_on() {
  // Remove trace filter. As result all trace messages will be printed.
  so_environment().change_message_delivery_tracer_filter(
    so_5::msg_tracing::no_filter());
  ...
}

Since

v.5.5.22

std_cerr_tracer()

SO_5_FUNC tracer_unique_ptr_t so_5::msg_tracing::std_cerr_tracer

(

)

Factory for tracer which uses std::cerr stream.

Since

v.5.5.9

std_clog_tracer()

SO_5_FUNC tracer_unique_ptr_t so_5::msg_tracing::std_clog_tracer

(

)

Factory for tracer which uses std::clog stream.

Since

v.5.5.9

std_cout_tracer()

SO_5_FUNC tracer_unique_ptr_t so_5::msg_tracing::std_cout_tracer

(

)

Factory for tracer which uses std::cout stream.

Since

v.5.5.9

Examples:

so_5/chstate_msg_tracing/main.cpp, so_5/nohandler_msg_tracing/main.cpp, and so_5/selective_msg_tracing/main.cpp.