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 () SO_5_NOEXCEPT=default
virtual mbox_id_t	id () const =0
	Unique ID of this mbox. More...
template<class Message >
void	deliver_message (std::type_index subscription_type, const intrusive_ptr_t< Message > &msg_ref) const
	Deliver message. More...
template<class Message >
void	deliver_message (const intrusive_ptr_t< Message > &msg_ref) const
	Deliver message. More...
template<class Message >
void	deliver_message (std::type_index subscription_type, std::unique_ptr< Message > msg_unique_ptr, message_mutability_t mutability) const
	Deliver message. More...
template<class Message >
void	deliver_message (std::unique_ptr< Message > msg_unique_ptr) const
	Deliver message. More...
template<class Message >
void	deliver_message (Message *msg_raw_ptr) const
	Deliver message. More...
template<class Message >
void	deliver_signal () const
	Deliver signal. More...
template<class Result >
service_invoke_proxy_t< Result >	get_one ()
	Create a special proxy for service request invocation. More...
service_invoke_proxy_t< void >	run_one ()
	Create a special proxy for service request invocation where return type is void. More...
void	deliver_message (const std::type_index &msg_type, const message_ref_t &message) const
	Deliver message for all subscribers. More...
void	deliver_service_request (const std::type_index &msg_type, const message_ref_t &message) const
	Deliver service request. 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) const =0
	Deliver message for all subscribers with respect to message limits. More...
virtual void	do_deliver_service_request (const std::type_index &msg_type, const message_ref_t &message, unsigned int overlimit_reaction_deep) const =0
	Deliver service request. More...
virtual void	do_deliver_enveloped_msg (const std::type_index &msg_type, const message_ref_t &message, unsigned int overlimit_reaction_deep)
	Deliver enveloped message. More...
Comparision.
bool	operator== (const abstract_message_box_t &o) const SO_5_NOEXCEPT
bool	operator< (const abstract_message_box_t &o) const SO_5_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) SO_5_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 () SO_5_NOEXCEPT
	Default constructor. More...
	~atomic_refcounted_t () SO_5_NOEXCEPT=default
	Destructor. More...
void	inc_ref_count () SO_5_NOEXCEPT
	Increments reference count. More...
unsigned long	dec_ref_count () SO_5_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::rt::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.

abstract_message_box_t has two versions of the deliver_message() method. The first one requires pointer to the actual message data and is intended for delivering messages to agents. The second one doesn't use a pointer to the actual message data and is intended for delivering signals to agents.

abstract_message_box_t also is used for the delivery of delayed and periodic messages. The SObjectizer Environment stores mbox for which messages must be delivered and the timer thread pushes message instances to the mbox at the appropriate time.

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

virtualdefault

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.

deliver_message() [1/6]

template<class Message >

void so_5::abstract_message_box_t::deliver_message ( std::type_index  subscription_type, const intrusive_ptr_t< Message > &  msg_ref  ) const

inline

Deliver message.

Mbox takes care about destroying a message object.

Since

v.5.5.19

Parameters

subscription_type	Subscription type for that message.
msg_ref	Message data.

Examples:

so_5/collector_many_performers/main.cpp, and so_5/simple_message_deadline/main.cpp.

deliver_message() [2/6]

template<class Message >

void so_5::abstract_message_box_t::deliver_message ( const intrusive_ptr_t< Message > &  msg_ref ) const

inline

Deliver message.

Since

v.5.2.2

Mbox takes care about destroying a message object.

Parameters

msg_ref

Message data.

deliver_message() [3/6]

template<class Message >

void so_5::abstract_message_box_t::deliver_message ( std::type_index  subscription_type, std::unique_ptr< Message >  msg_unique_ptr, message_mutability_t  mutability  ) const

inline

Deliver message.

Mbox takes care about destroying a message object.

Since

v.5.5.19

Parameters

subscription_type	Subscription type for that message.
msg_unique_ptr	Message data.
mutability	Actual mutability for this message instance.

deliver_message() [4/6]

template<class Message >

void so_5::abstract_message_box_t::deliver_message ( std::unique_ptr< Message >  msg_unique_ptr ) const

inline

Deliver message.

Mbox takes care about destroying a message object.

Parameters

msg_unique_ptr

Message data.

deliver_message() [5/6]

template<class Message >

void so_5::abstract_message_box_t::deliver_message ( Message *  msg_raw_ptr ) const

inline

Deliver message.

Mbox takes care about destroying a message object.

Parameters

msg_raw_ptr

Message data.

deliver_message() [6/6]

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

inline

Deliver message for all subscribers.

Note

This method is public since v.5.4.0.

This is a just a wrapper for do_deliver_message since v.5.5.4.

deliver_service_request()

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

inline

Deliver service request.

Since

v.5.3.0.

Note

This is a just a wrapper for do_deliver_service_request since v.5.5.4.

Parameters

msg_type	This is type_index for service Param type.
message	This is reference to msg_service_request_t<Result,Param> instance.

deliver_signal()

template<class Message >

void so_5::abstract_message_box_t::deliver_signal ( ) const

inline

Deliver signal.

do_deliver_enveloped_msg()

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

virtual

Deliver enveloped message.

Note

To keep source-code compatibility with previous versions this method is not pure virtual. It has an implementation that throws an exception with rc_not_implemented error code. This method will be marked as pure virtual in v.5.6.0

Since

v.5.5.23

Parameters

msg_type	This is type_index for service Param type.
message	This is reference to instance of an envelope. This pointer can't be null.
overlimit_reaction_deep	Current deep of overlimit reaction recursion.

Reimplemented in so_5::impl::local_mbox_template< Tracing_Base >, so_5::impl::limitful_mpsc_mbox_template< Tracing_Base >, so_5::mchain_props::mchain_template< Queue, Tracing_Base >, and so_5::impl::limitless_mpsc_mbox_template< Tracing_Base >.

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

pure virtual

Deliver message for all subscribers with respect to message limits.

Since

v.5.5.4

Note

It is obvious that do_deliver_message() must be non-const method. The constness is here now to keep compatibility in 5.5.* versions. The constness will be removed in v.5.6.0.

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

do_deliver_service_request()

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

pure virtual

Deliver service request.

Since

v.5.5.4

Note

It is obvious that do_deliver_message() must be non-const method. The constness is here now to keep compatibility in 5.5.* versions. The constness will be removed in v.5.6.0.

Parameters

msg_type	This is type_index for service Param type.
message	This is reference to msg_service_request_t<Result,Param> instance.
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.

drop_delivery_filter()

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

pure virtual

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::impl::limitless_mpsc_mbox_template< Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, and so_5::impl::named_local_mbox_t.

get_one()

template<class Result >

service_invoke_proxy_t< Result > so_5::abstract_message_box_t::get_one ( )

inline

Create a special proxy for service request invocation.

Since

v.5.3.0

Template Parameters

Result

type of result to be received as result of service request.

Note

That method starts methods call chain for synchonous agents interaction. Next method should be either wait_forever()/wait_for() or async()/make_async().

Usage examples

// Make synchronous call and acquire result as a future object.
const so_5::mbox_t & dest = ...;
std::future< std::string > result =
    dest.get_one< std::string >().make_async< request >(...);

// Or if request object is already created:
std::unique_ptr< request > req = std::make_unique< request >(...);
...
std::future< std::string > result =
    dest.get_one< std::string >().async( std::move( request ) );

// Make synchronous call, wait for result indefinitely.
std::string result =
    dest.get_one< std::string >().wait_forever().make_sync_get< request >(...);
// Or...
std::unique_ptr< request > req = std::make_unique< request >(...);
std::string result =
    dest.get_one< std::string >().wait_forever().sync_get( std::move( request ) );

// Make synchronous call, wait no more than 50ms.
std::string result =
    dest.get_one< std::string >().wait_for( std::chrono::milliseconds(50) ).make_sync_get< request >(...);
// Or...
std::unique_ptr< request > req = std::make_unique< request >(...);
std::string result =
    dest.get_one< std::string >().wait_for( std::chrono::milliseconds(50) ).sync_get( std::move( request ) );

Examples:

so_5/collector_many_performers/main.cpp, so_5/collector_performer_pair/main.cpp, and so_5/work_generation/main.cpp.

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

inline

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

inline

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.

run_one()

service_invoke_proxy_t< void > so_5::abstract_message_box_t::run_one ( )

inline

Create a special proxy for service request invocation where return type is void.

Since

v.5.3.0

Template Parameters

Result

type of result to be received as result of service request.

Note

This method could useful for waiting a completion of some message processing by destination agent.

See also

get_one().

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::impl::limitless_mpsc_mbox_template< Tracing_Base >, so_5::stats::impl::st_env_stuff::next_turn_mbox_t, 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::rt::impl::mbox_iface_for_timers_t

friend class so_5::rt::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