SObjectizer-5 Extra
Public Types | Static Public Member Functions | Private Types | List of all members
so_5::extra::mboxes::collecting_mbox::mbox_template_t< Collecting_Msg, Traits, Lock_Type > Class Template Referencefinal

A template which defines properties for a collecting mbox. More...

#include <collecting_mbox.hpp>

Public Types

using messages_collected_t = typename details::messages_collected_t< config_type >
 Actual type of message_collected instance. More...
 

Static Public Member Functions

template<typename... Args>
static mbox_t make (environment_t &env, Args &&... args)
 Create an instance of collecting mbox. More...
 

Private Types

using config_type = details::config_type< Collecting_Msg, Traits, Lock_Type >
 A configuration to be used for that mbox type. More...
 

Detailed Description

template<typename Collecting_Msg, typename Traits = runtime_size_traits_t, typename Lock_Type = std::mutex>
class so_5::extra::mboxes::collecting_mbox::mbox_template_t< Collecting_Msg, Traits, Lock_Type >

A template which defines properties for a collecting mbox.

Usage examples:

  1. Collecting mbox for immutable messages of type my_msg. Count of messages to be collected is known only at runtime.
    my_msg >;
    auto my_mbox = my_mbox_type::make(
    // SObjectizer Environment to work in.
    so_environment(),
    // A target mbox for messages_collected_t.
    target_mbox,
    // Count of messages to be collected.
    messages_to_collect );
    // To receve messages_collected_t from my_mbox:
    void my_agent::on_messages_collected(mhood_t<my_mbox_type::messages_collected_t> cmd) {
    ...
    }
  2. Collecting mbox for immutable messages of type my_msg. Count of messages to be collected is known at the compile time.
    my_msg,
    // Note: there is no need to specify message count because it is already known.
    auto my_mbox = my_mbox_type::make(
    // SObjectizer Environment to work in.
    so_environment(),
    // A target mbox for messages_collected_t.
    target_mbox );
    // To receve messages_collected_t from my_mbox:
    void my_agent::on_messages_collected(mhood_t<my_mbox_type::messages_collected_t> cmd) {
    ...
    }
  3. Collecting mbox for mutable messages of type my_msg. Count of messages to be collected is known only at runtime. Please note that message_collected_t is also delivered as mutable message!
    so_5::mutable_msg<my_msg> >;
    auto my_mbox = my_mbox_type::make(
    // SObjectizer Environment to work in.
    so_environment(),
    // A target mbox for messages_collected_t.
    target_mbox,
    // Count of messages to be collected.
    messages_to_collect );
    // To receve messages_collected_t from my_mbox:
    void my_agent::on_messages_collected(mutable_mhood_t<my_mbox_type::messages_collected_t> cmd) {
    ...
    }
  4. Collecting mbox for mutable messages of type my_msg. Count of messages to be collected is known at the compile time. Please note that message_collected_t is also delivered as mutable message!
    so_5::mutable_msg<my_msg>,
    // Note: there is no need to specify message count because it is already known.
    auto my_mbox = my_mbox_type::make(
    // SObjectizer Environment to work in.
    so_environment(),
    // A target mbox for messages_collected_t.
    target_mbox );
    // To receve messages_collected_t from my_mbox:
    void my_agent::on_messages_collected(mutable_mhood_t<my_mbox_type::messages_collected_t> cmd) {
    ...
    }

A type of message with collected messages is specified by inner type mbox_template_t::messages_collected_t. Please note that actual message type for messages_collected_t will depend on Collecting_Msg template parameter. If Collecting_Msg is message type then messages_collected_t will be message which holds collected messages inside. Such message type will have the following interface:

// Interface of messages_collected_t for the case
// when Collecting_Msg is a message type.
class message_collected_t {
... // Some private stuff.
public :
// Count of collected messages.
std::size_t size() const;
// Perform some action on collected message with the specified index.
template<typename F>
decltype(auto) with_nth(std::size_t index, F && f) const;
// Perform some action on every collected message.
template<typename F>
void for_each(F && f) const;
// Perform some action on every collected message.
// Index of message is also passed to functor f.
template<typename F>
void for_each_with_index(F && f) const;
};

A functor for methods with_nth and for_each must have the following format:

return_type f(mhood_t<Collecting_Msg> m);

A functor for method for_each_with_index must have the following format:

return_type f(std::size_t index, mhood_t<Collecting_Msg> m);

For example, handling of collected immutable messages can looks like:

my_msg >;
...
void my_agent::on_my_messages(mhood_t<my_mbox_type::messages_collected_t> cmd) {
cmd->for_each( [](mhood_t<my_msg> m) { ... } );
}

And handling of collected mutable messages can looks like:

so_5::mutable_msg<my_msg> >;
...
void my_agent::on_my_messages(mutable_mhood_t<my_mbox_type::messages_collected_t> cmd) {
cmd->for_each( [](mutable_mhood_t<my_msg> m) { ... } );
}

If Collecting_Msg is a type of signal, then mbox_template_t::messages_collected_t will have the following format:

// Interface of messages_collected_t for the case
// when Collecting_Msg is a signal type.
class message_collected_t {
... // Some private stuff.
public :
// Count of collected messages.
std::size_t size() const;
};

It means that if Collecting_Msg is a signal type then there is no any collected signals instances.

Note
Collecting mbox can be used for collecting mutable messages. But there are some limitations:
  • mutable messages can be collected only if target_mbox is multi-producer/single-consumer mbox. It is because messages_collected_t will be sent also as a mutable message. And sending of mutable messages it allowed only to MPSC mboxes;
  • messages_collected_t will be sent as mutable message;
  • it is impossible to collect mutable signals (this is prohibited by SObjectizer);
  • it is impossible to collect mutable and immutable messages of the same type.
Template Parameters
Collecting_Msgtype of message to be collected. It can be simple type like my_msg (in this case only immutable messages of type my_msg will be collected). Or it can be so_5::mutable_msg<my_msg> (in this case only mutable messages of type my_msg will be collected).
Traitstype of size-specific traits. It is expected to be constexpr_size_traits_t or runtime_size_traits_t (or any other type like these two).
Lock_Typetype of lock to be used for thread safety. It can be std::mutex or so_5::null_mutex_t (or any other type which can be used with std::lock_quard).
Examples:
mboxes/collecting_mbox/advanced/main.cpp, and mboxes/collecting_mbox/simple/main.cpp.

Definition at line 1191 of file collecting_mbox.hpp.

Member Typedef Documentation

◆ config_type

template<typename Collecting_Msg , typename Traits = runtime_size_traits_t, typename Lock_Type = std::mutex>
using so_5::extra::mboxes::collecting_mbox::mbox_template_t< Collecting_Msg, Traits, Lock_Type >::config_type = details::config_type< Collecting_Msg, Traits, Lock_Type >
private

A configuration to be used for that mbox type.

Definition at line 1194 of file collecting_mbox.hpp.

◆ messages_collected_t

template<typename Collecting_Msg , typename Traits = runtime_size_traits_t, typename Lock_Type = std::mutex>
using so_5::extra::mboxes::collecting_mbox::mbox_template_t< Collecting_Msg, Traits, Lock_Type >::messages_collected_t = typename details::messages_collected_t<config_type>

Actual type of message_collected instance.

Definition at line 1198 of file collecting_mbox.hpp.

Member Function Documentation

◆ make()

template<typename Collecting_Msg , typename Traits = runtime_size_traits_t, typename Lock_Type = std::mutex>
template<typename... Args>
static mbox_t so_5::extra::mboxes::collecting_mbox::mbox_template_t< Collecting_Msg, Traits, Lock_Type >::make ( environment_t &  env,
Args &&...  args 
)
inlinestatic

Create an instance of collecting mbox.

Please note that actual list of parameters depends on Traits type. If Traits is constexpr_size_traits_t then make will have the following format:

mbox_t make(environment_t & env, const mbox_t & target);

If Traits is runtime_size_traits_t then make will have the following format:

mbox_t make(environment_t & env, const mbox_t & target, size_t messages_to_collect);

Definition at line 1218 of file collecting_mbox.hpp.


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