so_5::abstract_message_box_t Class Reference

Mail box class. More...

#include <mbox.hpp>

Inheritance diagram for so_5::abstract_message_box_t:

Public Member Functions
	abstract_message_box_t ()=default
virtual	~abstract_message_box_t () noexcept=default
virtual mbox_id_t	id () const =0
	Unique ID of this mbox. More...
virtual void	subscribe_event_handler (const std::type_index &type_index, const message_limit::control_block_t *limit, agent_t &subscriber)=0
	Add the message handler. More...
virtual void	unsubscribe_event_handlers (const std::type_index &type_index, agent_t &subscriber)=0
	Remove all message handlers. More...
virtual std::string	query_name () const =0
	Get the mbox name. More...
virtual mbox_type_t	type () const =0
	Get the type of message box. More...
virtual void	do_deliver_message (const std::type_index &msg_type, const message_ref_t &message, unsigned int overlimit_reaction_deep)=0
	Deliver message for all subscribers with respect to message limits. More...
virtual so_5::environment_t &	environment () const noexcept=0
	SObjectizer Environment for which the mbox is created. More...
Comparision.
bool	operator== (const abstract_message_box_t &o) const noexcept
bool	operator< (const abstract_message_box_t &o) const noexcept
Methods for working with delivery filters.
virtual void	set_delivery_filter (const std::type_index &msg_type, const delivery_filter_t &filter, agent_t &subscriber)=0
	Set a delivery filter for message type and subscriber. More...
virtual void	drop_delivery_filter (const std::type_index &msg_type, agent_t &subscriber) noexcept=0
	Removes delivery filter for message type and subscriber. More...

Protected Member Functions
virtual void	do_deliver_message_from_timer (const std::type_index &msg_type, const message_ref_t &message)
	Special method for message delivery from a timer thread. More...
Protected Member Functions inherited from so_5::atomic_refcounted_t
	atomic_refcounted_t (const atomic_refcounted_t &)=delete
atomic_refcounted_t &	operator= (const atomic_refcounted_t &)=delete
	atomic_refcounted_t () noexcept
	Default constructor. More...
	~atomic_refcounted_t () noexcept=default
	Destructor. More...
void	inc_ref_count () noexcept
	Increments reference count. More...
unsigned long	dec_ref_count () noexcept
	Decrement reference count. More...

Static Protected Member Functions
static void	delegate_deliver_message_from_timer (abstract_message_box_t &mbox, const std::type_index &msg_type, const message_ref_t &message)
	Helper for calling do_deliver_message_from_timer in derived classes. More...

Private Member Functions
	abstract_message_box_t (const abstract_message_box_t &)=delete
	abstract_message_box_t (abstract_message_box_t &&)=delete
abstract_message_box_t &	operator= (const abstract_message_box_t &)=delete
abstract_message_box_t &	operator= (abstract_message_box_t &&)=delete

Friends
class	intrusive_ptr_t< abstract_message_box_t >
class	so_5::impl::mbox_iface_for_timers_t

Detailed Description

Mail box class.

The class serves as an interface for sending and receiving messages.

All mboxes can be created via the SObjectizer Environment. References to mboxes are stored and manipulated by so_5::mbox_t objects.

See also

environment_t::schedule_timer(), environment_t::single_timer().

Constructor & Destructor Documentation

abstract_message_box_t() [1/3]

so_5::abstract_message_box_t::abstract_message_box_t ( const abstract_message_box_t &  )

privatedelete

abstract_message_box_t() [2/3]

so_5::abstract_message_box_t::abstract_message_box_t ( abstract_message_box_t &&  )

privatedelete

abstract_message_box_t() [3/3]

so_5::abstract_message_box_t::abstract_message_box_t ( )

default

~abstract_message_box_t()

virtual so_5::abstract_message_box_t::~abstract_message_box_t ( )

virtualdefaultnoexcept

Member Function Documentation

delegate_deliver_message_from_timer()

static void so_5::abstract_message_box_t::delegate_deliver_message_from_timer ( abstract_message_box_t &  mbox, const std::type_index &  msg_type, const message_ref_t &  message  )

inlinestaticprotected

Helper for calling do_deliver_message_from_timer in derived classes.

Sometimes an user want to implement its own mbox on top of an existing mbox. Something like that:

class my_custom_mbox : public so_5::abstract_message_box_t
{
  // Actual mbox to perform all work.
  const so_5::mbox_t actual_mbox_;
  ...
  void do_deliver_message_from_timer(
    const std::type_index & msg_type,
    const so_5::message_ref_t & message )
  {
    ... // Do some specific stuff.
    // Work should be delegated to actual_mbox_ but we
    // can't simply call actual_mbox_->do_deliver_message_from_timer()
    // because it is a protected method.
    // But we can call delegate_deliver_message_from_timer():
    delegate_deliver_message_from_timer(
        actual_mbox_, msg_type, message );
  }
};

Since

v.5.5.23

Parameters

mbox	Mbox to be used for message delivery.
msg_type	Type of the message to deliver.
message	A message instance to be delivered.

do_deliver_message()

virtual void so_5::abstract_message_box_t::do_deliver_message ( const std::type_index &  msg_type, const message_ref_t &  message, unsigned int  overlimit_reaction_deep  )

pure virtual

Deliver message for all subscribers with respect to message limits.

Since

v.5.5.4

Note

Since v.5.6.0 this method is used for deliverance of ordinary messages/signals and for deliverance of enveloped messages.

Parameters

msg_type	Type of the message to deliver.
message	A message instance to be delivered.
overlimit_reaction_deep	Current deep of overlimit reaction recursion.

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::impl::limitful_mpsc_mbox_template< Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

do_deliver_message_from_timer()

void so_5::abstract_message_box_t::do_deliver_message_from_timer ( const std::type_index &  msg_type, const message_ref_t &  message  )

protectedvirtual

Special method for message delivery from a timer thread.

Since

v.5.5.18

A message delivery from timer thread is somewhat different from an ordinary message delivery. Especially in the case when target mbox is a message chain. If that message chain is full and some kind of overflow reaction is specified (like waiting for some time or throwing an exception) then it can lead to undesired behaviour of the whole application. To take care about these cases a new method is introduced.

Note that implementation of that method in abstract_message_box_t class is just a proxy for do_deliver_message() method. It is done to keep compatibility with previous versions of SObjectizer. The actual implementation of that method is present only in message chains.

Parameters

msg_type	Type of the message to deliver.
message	A message instance to be delivered.

Reimplemented in so_5::mchain_props::mchain_template< Queue, Tracing_Base >.

drop_delivery_filter()

virtual void so_5::abstract_message_box_t::drop_delivery_filter ( const std::type_index &  msg_type, agent_t &  subscriber  )

pure virtualnoexcept

Removes delivery filter for message type and subscriber.

Since

v.5.5.5

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

environment()

virtual so_5::environment_t& so_5::abstract_message_box_t::environment ( ) const

pure virtualnoexcept

SObjectizer Environment for which the mbox is created.

Since

v.5.6.0

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

id()

virtual mbox_id_t so_5::abstract_message_box_t::id ( ) const

pure virtual

Unique ID of this mbox.

Since

v.5.4.0

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

operator<()

bool so_5::abstract_message_box_t::operator< ( const abstract_message_box_t &  o ) const

inlinenoexcept

operator=() [1/2]

abstract_message_box_t& so_5::abstract_message_box_t::operator= ( const abstract_message_box_t &  )

privatedelete

operator=() [2/2]

abstract_message_box_t& so_5::abstract_message_box_t::operator= ( abstract_message_box_t &&  )

privatedelete

operator==()

bool so_5::abstract_message_box_t::operator== ( const abstract_message_box_t &  o ) const

inlinenoexcept

query_name()

virtual std::string so_5::abstract_message_box_t::query_name ( ) const

pure virtual

Get the mbox name.

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

set_delivery_filter()

virtual void so_5::abstract_message_box_t::set_delivery_filter ( const std::type_index &  msg_type, const delivery_filter_t &  filter, agent_t &  subscriber  )

pure virtual

Set a delivery filter for message type and subscriber.

Since

v.5.5.5

Note

If there already is a delivery filter for that (msg_type,subscriber) pair then old delivery filter will be replaced by new one.

Parameters

msg_type	Message type to be filtered.
filter	Filter to be set. A caller must guaranted the validity of this reference.
subscriber	A subscriber for the message.

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

subscribe_event_handler()

virtual void so_5::abstract_message_box_t::subscribe_event_handler ( const std::type_index &  type_index, const message_limit::control_block_t *  limit, agent_t &  subscriber  )

pure virtual

Add the message handler.

Parameters

type_index	Message type.
limit	Optional message limit for that message type.
subscriber	Agent-subcriber.

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

type()

virtual mbox_type_t so_5::abstract_message_box_t::type ( ) const

pure virtual

Get the type of message box.

Since

v.5.5.3

Note

This method is primarily intended for internal usage. It is useful sometimes in subscription-related operations because there is no need to do some actions for MPSC mboxes.

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

unsubscribe_event_handlers()

virtual void so_5::abstract_message_box_t::unsubscribe_event_handlers ( const std::type_index &  type_index, agent_t &  subscriber  )

pure virtual

Remove all message handlers.

Parameters

type_index	Message type.
subscriber	Agent-subcriber.

Implemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >, and so_5::impl::named_local_mbox_t.

Friends And Related Function Documentation

intrusive_ptr_t< abstract_message_box_t >

friend class intrusive_ptr_t< abstract_message_box_t >

friend

so_5::impl::mbox_iface_for_timers_t

friend class so_5::impl::mbox_iface_for_timers_t

friend

It is necessary for for access to do_deliver_message_from_timer().

Note

Added in v.5.5.18.

---

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

• mbox.hpp
• mbox.cpp