what's new in sobjectizer 5.5.5

What’s new in SObjectizer-5.5.5

SObjectizer Team, May 2015

A Short Overview

There are three new features in SObjectizer v.5.5.5:

● new introduce_coop() and introduce_child_coop() helpers,

● tuples as messages,● message delivery filters.

This presentation briefly describes them.


https://sourceforge.net/projects/sobjectizer/


New Helpers for Cooperation Registration




New helpers introduce_coop() and introduce_child_coop() are intended for simplification of cooperation creation and registration.




If a coop is created by create_coop() or create_child_coop() then three steps must be performed:

● new coop instance must be created;● the instance must be filled up with agents;● the instance must be registered by invoking

register_coop().

Sometimes the last step (e.g. call of register_coop()) is forgotten.




New introduce_coop() and introduce_child_coop() helpers take care about coop instance creation and calling of register_coop().

A programmer should only fill the coop up with agents.




Just for comparison. A registration of a new coop by create_coop() and register_coop():

auto coop = env.create_coop( so_5::autoname );coop->make_agent< first_agent >( some_params() );coop->make_agent< second_agent >( some_params() );env.register_coop( std::move( coop ) );

And by introduce_coop() in C++11:

env.introduce_coop( []( so_5::rt::agent_coop_t & coop ) { coop.make_agent< first_agent >( some_params() ); coop.make_agent< second_agent >( some_params() );} );




Or, if C++14 is available in your compiler:

env.introduce_coop( []( auto & coop ) { coop.make_agent< first_agent >( some_params() ); coop.make_agent< second_agent >( some_params() );} );




The same comparison for create_child_coop() and introduce_child_coop().

Old way:

void parent_coop::so_evt_start() override{ auto coop = so_5::rt::create_child_coop( *this, so_5::autoname ); coop->make_agent< first_agent >( some_params() ); coop->make_agent< second_agent >( some_params() ); env.register_coop( std::move( coop ) );}




New way in C++11:

void parent_coop::so_evt_start() override{ so_5::rt::introduce_child_coop( *this, [=](so_5::rt::agent_coop_t & coop) { coop.make_agent< first_agent >( some_params() ); coop.make_agent< second_agent >( some_params() ); } );}




Or, if C++14 is available in your compiler:

void parent_coop::so_evt_start() override{ so_5::rt::introduce_child_coop( *this, [=]( auto & coop ) { coop.make_agent< first_agent >( some_params() ); coop.make_agent< second_agent >( some_params() ); } );}




Tuples as Messages




A message with data inside must be an instance of dedicated struct or class derived from so_5::rt::message_t.

Because of that it was necessary to spend several lines to define even the simplest messages even in tiny programs like unit-tests. For example the code like this is widespread:

struct msg_line_loaded : public so_5::rt::message_t{ std::string m_line; msg_line_loaded( std::string line ) : m_line( std::move(line) ) {}};




Version 5.5.5 adds a possibility to use tuples instead of dedicated message struct/classes. A message like msg_line_loaded could be represented as:

struct line_loaded_tag {};using msg_line_loaded = so_5::rt::tuple_as_message_t< line_loaded_tag, std::string >;




But version 5.5.5 goes even further…

It is not necessary to define tag-types like line_loaded_tag. It is possible to use so_5::rt::mtag template with a unique number as type tag:

using so_5::rt;using msg_line_loaded = tuple_as_message_t< mtag<0>, std::string >;




Just for comparison. With dedicated message type:

using so_5::rt;

struct msg_line_loaded : public message_t{ std::string m_line; msg_line_loaded( std::string line ) : m_line( std::move(line) ) {}};

void data_producer::evt_io_event(){ so_5::send< msg_line_loaded >( receiver, load_input(...) ); }void data_consumer::evt_next_line( const msg_line_loaded & evt ){ std::cout << "line: " << evt.m_line << std::endl;}




And with tuple_as_message_t:

using so_5::rt;

using msg_line_loaded = tuple_as_message_t< mtag<0>, std::string >;

void data_producer::evt_io_event(){ so_5::send< msg_line_loaded >( receiver, load_input(...) ); }void data_consumer::evt_next_line( const msg_line_loaded & evt ){ std::cout << "line: " << std::get<0>(evt) << std::endl;}




More information about tuples_as_message_t and mtag (and also typed_mtag) can be found in the corresponding Wiki section:

https://sourceforge.net/p/sobjectizer/wiki/so-5.5.5%20tuple_as_message/

But note that this feature is recommended only for use in very small programs like unit-test and

write-and-forget proof-of-concept demos.






Message Delivery Filters




Message delivery filter is a solution for a situation where you have to deal with big amount of messages but need to handle only a few of them. Like in the example of handling run-time monitoring information from SObjectizer Environment:

void timer_thread_stats_listener::evt_timer_quantities( const so_5::rt::stats::messages::quantity< std::size_t > & evt ){ // Ignore messages unrelated to timer thread. if( so_5::rt::stats::prefixes::timer_thread() != evt.m_prefix ) return; … // Processing of related to timer thread messages.}




An approach where you receive all messages but handle only a few of them is not cost effective.

It is because all messages go through full message dispatching path: from message box to event queue and then to event handler.




More effective approach is to pass to event queue only those messages which will be handled by a receiver.

To do that some filter must be set for message box. This filter will check every message instance before pushing it to the receiver’s event queue. Only messages which passes filter will be stored in the receiver’s event queue. And then handled by the receiver.

Message delivery filters do exactly that. Nothing more. Nothing less.




With the help of message filters the example above could be rewritten this way:void timer_thread_stats_listener::so_define_agent() { // Set the delivery filter. so_set_delivery_filter( so_environment().stats_controller().mbox(), []( const so_5::rt::stats::messages::quantity< std::size_t > & msg ) { return so_5::rt::stats::prefixes::timer_thread() == msg.m_prefix; } ); …}…void timer_thread_stats_listener::evt_timer_quantities( const so_5::rt::stats::messages::quantity< std::size_t > & evt ) { … // Processing of related to timer thread messages.}




More information about message delivery filters can be found in the corresponding Wiki section:

https://sourceforge.net/p/sobjectizer/wiki/so-5.5.5%20Message%20delivery%20filters/






The SObjectizer v.5.5.5 could be obtained from Subversion repository on SourceForge:

http://svn.code.sf.net/p/sobjectizer/repo/tags/so_5/5.5.5

Or from GitHub:

https://github.com/masterspline/SObjectizer/releases/tag/v5.5.5

Or could be downloaded as archive from SourceForge:

https://sourceforge.net/projects/sobjectizer/files/sobjectizer/SObjectizer%20Core%20v.5.5/










Additional Information:

Project’s home: http://sourceforge.net/projects/sobjectizer

Documentation: http://sourceforge.net/p/sobjectizer/wiki/

Forum: http://sourceforge.net/p/sobjectizer/discussion/

Google-group: https://groups.google.com/forum/#!forum/sobjectizer

GitHub mirror: https://github.com/masterspline/SObjectizer

http://sourceforge.net/projects/sobjectizer

http://sourceforge.net/projects/sobjectizer

http://sourceforge.net/p/sobjectizer/wiki/

http://sourceforge.net/p/sobjectizer/wiki/

http://sourceforge.net/p/sobjectizer/discussion/

http://sourceforge.net/p/sobjectizer/discussion/

https://groups.google.com/forum/#!forum/sobjectizer

https://groups.google.com/forum/#!forum/sobjectizer

https://github.com/masterspline/SObjectizer

https://github.com/masterspline/SObjectizer

what's new in sobjectizer 5.5.5

Software

coop auto coop

params coop

coop std

coop helpers

t coop

autoname coop

new coop instance

coop instance creation