so_5::msg_tracing Namespace Reference

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

Namespaces
namespace	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.
using	filter_shptr_t = intrusive_ptr_t< filter_t >
	An alias for smart pointer to filter.

Enumerations
enum class	status_t { disabled , enabled }
	Status of message delivery tracing. More...
enum class	message_or_signal_flag_t { message , signal }
	A flag for message/signal dichotomy. More...
enum class	msg_source_type_t { mbox , mchain , 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.
SO_5_FUNC tracer_unique_ptr_t	std_cerr_tracer ()
	Factory for tracer which uses std::cerr stream.
SO_5_FUNC tracer_unique_ptr_t	std_clog_tracer ()
	Factory for tracer which uses std::clog stream.
template<typename L >
filter_shptr_t	make_filter (L &&lambda)
	A helper function for creation of new filter from lambda-function.
filter_shptr_t	make_enable_all_filter ()
	A helper function for creation of filter that enables all messages.
filter_shptr_t	make_disable_all_filter ()
	A helper function for creation of filter that disables all messages.
filter_shptr_t	no_filter ()
	A helper function to be used when it is necessary to remove msg_tracing's filter.
SO_5_FUNC filter_shptr_t	make_individual_trace_filter ()
	Factory for special message tracing filter for individual tracing.
template<typename Dest >
so_5::mbox_t	individual_trace (Dest &&dest)
	Indicator that tells that delivery of the message/signal should be traced.

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 = intrusive_ptr_t< filter_t >

An alias for smart pointer to filter.

Since

v.5.5.22

Definition at line 347 of file msg_tracing.hpp.

tracer_unique_ptr_t

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

A short alias for unique_ptr to tracer.

Since

v.5.5.9

Definition at line 79 of file msg_tracing.hpp.

Enumeration Type Documentation

message_or_signal_flag_t

enum class so_5::msg_tracing::message_or_signal_flag_t

strong

A flag for message/signal dichotomy.

Since

v.5.5.22

Enumerator
message
signal

Definition at line 114 of file msg_tracing.hpp.

msg_source_type_t

enum class 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	The source is a mbox.
mchain	The source is a 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.

Definition at line 129 of file msg_tracing.hpp.

status_t

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

Definition at line 36 of file msg_tracing.hpp.

Function Documentation

individual_trace()

template<typename Dest >

so_5::mbox_t so_5::msg_tracing::individual_trace ( Dest && dest )

nodiscard

Indicator that tells that delivery of the message/signal should be traced.

This indicator has to be used with send(), send_delayed() and send_periodic() functions. It allows to trace only actions related to a message/signal sent by using individual_trace().

Note

It's necessary to enable message delivery tracing and set a filter returned by make_individual_trace_filter().

Usage example:

// Ordinary message/signal.
so_5::send<my_msg>(so_5::msg_tracing::individual_trace(dest), ...);
 
// Delayed message/signal.
so_5::send_delayed<my_msg>(so_5::msg_tracing::individual_trace(dest), 10ms, ...);
 
// Periodic message/signal.
auto timer_id = so_5::send_periodic<my_msg>(so_5::msg_tracing::individual_trace(dest), 10ms, 10ms, ...);

Since

v.5.8.3

Parameters

dest	Actual destination for the message/signal. It can be a reference to the agent (direct mbox of that agent will be used), a mbox, a mchain.

Examples

so_5/individual_msg_tracing/main.cpp.

Definition at line 227 of file msg_tracing_individual.hpp.

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.

Definition at line 463 of file msg_tracing.hpp.

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

Definition at line 434 of file msg_tracing.hpp.

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.

Definition at line 404 of file msg_tracing.hpp.

make_individual_trace_filter()

SO_5_FUNC filter_shptr_t so_5::msg_tracing::make_individual_trace_filter ( )

nodiscard

Factory for special message tracing filter for individual tracing.

This filter allows to trace only actions related to messages/signal sent by using individual_trace().

Usage example:

so_5::launch(
  [](so_5::environment_t & env) {...},
  [](so_5::environment_params_t & params) {
    // Message delivery tracing has to be turned on.
    params.message_delivery_tracer(so_5::msg_tracing::std_cout_tracer());
    // Special filter has to be set to avoid flooding of trace information.
    params.message_delivery_tracer_filter(so_5::msg_tracing::make_individual_trace_filter());
    ...
  });

Since

v.5.8.3

Examples

so_5/individual_msg_tracing/main.cpp.

Definition at line 129 of file msg_tracing_individual.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

Definition at line 500 of file msg_tracing.hpp.

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

Examples

so_5/bind_transformer/main.cpp.

Definition at line 68 of file msg_tracing.cpp.

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

Definition at line 74 of file msg_tracing.cpp.

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/individual_msg_tracing/main.cpp, so_5/nohandler_msg_tracing/main.cpp, and so_5/selective_msg_tracing/main.cpp.

Definition at line 62 of file msg_tracing.cpp.