SObjectizer-5 Extra
Namespaces | Classes | Functions
so_5::extra::revocable_timer Namespace Reference

Namespaces

 details
 
 impl
 

Classes

class  timer_id_t
 The ID of revocable timer message/signal. More...
 

Functions

template<typename Message , typename... Args>
SO_5_NODISCARD timer_id_t send_periodic (so_5::environment_t &env, const so_5::mbox_t &to, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, Args &&... args)
 A utility function for creating and delivering a periodic message. More...
 
template<typename Message , typename Target , typename... Args>
SO_5_NODISCARD timer_id_t send_periodic (Target &&target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, Args &&... args)
 A utility function for creating and delivering a periodic message to the specified destination. More...
 
template<typename Message >
SO_5_NODISCARD std::enable_if< !::so_5::is_signal< Message >::value, timer_id_t >::type send_periodic (::so_5::environment_t &env, const ::so_5::mbox_t &to, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, ::so_5::mhood_t< Message > mhood)
 A utility function for delivering a periodic from an existing message hood. More...
 
template<typename Message >
SO_5_NODISCARD std::enable_if< ::so_5::is_signal< Message >::value, timer_id_t >::type send_periodic (::so_5::environment_t &env, const ::so_5::mbox_t &to, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, ::so_5::mhood_t< Message >)
 A utility function for periodic redirection of a signal from existing message hood. More...
 
template<typename Message , typename Target >
SO_5_NODISCARD timer_id_t send_periodic (Target &&target, std::chrono::steady_clock::duration pause, std::chrono::steady_clock::duration period, ::so_5::mhood_t< Message > mhood)
 A helper function for redirection of a message/signal as a periodic message/signal. More...
 
template<typename Message , typename... Args>
SO_5_NODISCARD timer_id_t send_delayed (so_5::environment_t &env, const so_5::mbox_t &to, std::chrono::steady_clock::duration pause, Args &&... args)
 A utility function for creating and delivering a delayed message. More...
 
template<typename Message , typename Target , typename... Args>
SO_5_NODISCARD timer_id_t send_delayed (Target &&target, std::chrono::steady_clock::duration pause, Args &&... args)
 A utility function for creating and delivering a delayed message to the specified destination. More...
 
template<typename Message >
SO_5_NODISCARD timer_id_t send_delayed (so_5::environment_t &env, const so_5::mbox_t &to, std::chrono::steady_clock::duration pause, ::so_5::mhood_t< Message > cmd)
 A helper function for redirection of existing message/signal as delayed message. More...
 
template<typename Message , typename Target >
SO_5_NODISCARD timer_id_t send_delayed (Target &&target, std::chrono::steady_clock::duration pause, ::so_5::mhood_t< Message > cmd)
 A helper function for redirection of existing message/signal as delayed message. More...
 

Function Documentation

◆ send_delayed() [1/4]

template<typename Message , typename... Args>
SO_5_NODISCARD timer_id_t so_5::extra::revocable_timer::send_delayed ( so_5::environment_t &  env,
const so_5::mbox_t &  to,
std::chrono::steady_clock::duration  pause,
Args &&...  args 
)

A utility function for creating and delivering a delayed message.

This function requires passing a reference to SObjectizer Environment and target mbox. Because of that it usually used outside SObjectizer's agent (where it is possible to use another variant of send_delayed). For example:

so_5::wrapped_env_t sobj; // SObjectizer is started here.
so_5::mbox_t worker_mbox; // Will get a value later.
// Create a worker and get its mbox.
sobj.environment().introduce_coop( [&](so_5::coop_t & coop) {
auto worker = coop.make_agent<worker_agent>(...);
worker_mbox = worker->so_direct_mbox();
});
// Send revocable delayed message to the worker.
auto timer_id = so_5::extra::revocable_timer::send_periodic<kill_yourself>(
sobj.environment(),
worker_mbox(),
60s,
... );
... // Do some work.
// Revoke the kill_yourself message.
timer_id.release();
Note
The return value of that function must be stored somewhere. Otherwise the delayed timer will be cancelled automatically just right after send_delayed returns.
Attention
Value of pause should be non-negative.
Since
v.1.2.0
Parameters
envAn environment to be used for timer.
toMbox for the message to be sent to.
pausePause for message delaying.
argsMessage constructor parameters.

Definition at line 685 of file pub.hpp.

◆ send_delayed() [2/4]

template<typename Message , typename Target , typename... Args>
SO_5_NODISCARD timer_id_t so_5::extra::revocable_timer::send_delayed ( Target &&  target,
std::chrono::steady_clock::duration  pause,
Args &&...  args 
)

A utility function for creating and delivering a delayed message to the specified destination.

Agent, ad-hoc agent or mchain can be used as target.

Note
Message chains with overload control must be used for periodic messages with additional care because exceptions can't be thrown during dispatching messages from timer.

This function is intended to be used inside SObjectizer's agents where we have this pointer and can extract reference to SObjectizer Environment and the direct mbox of agent from that pointer:

namespace timer_ns = so_5::extra::revocable_timer;
class my_agent : public so_5::agent_t {
timer_ns::timer_id_t timer_;
...
void so_evt_start() override {
...
// Initiate a delayed message to self.
timer_ = timer_ns::send_periodic<kill_youself>(*this, 60s, ...);
...
}
...
};
Note
The return value of that function must be stored somewhere. Otherwise the delayed timer will be cancelled automatically just right after send_delayed returns.
Attention
Value of pause should be non-negative.
Template Parameters
Messagetype of message or signal to be sent.
Targetcan be so_5::agent_t, so_5::adhoc_agent_definition_proxy_t or so_5::mchain_t.
Argslist of arguments for Message's constructor.
Since
v.1.2.0
Parameters
targetA destination for the periodic message.
pausePause for message delaying.
argsMessage constructor parameters.

Definition at line 750 of file pub.hpp.

◆ send_delayed() [3/4]

template<typename Message >
SO_5_NODISCARD timer_id_t so_5::extra::revocable_timer::send_delayed ( so_5::environment_t &  env,
const so_5::mbox_t &  to,
std::chrono::steady_clock::duration  pause,
::so_5::mhood_t< Message >  cmd 
)

A helper function for redirection of existing message/signal as delayed message.

Usage example:

namespace timer_ns = so_5::extra::revocable_timer;
class my_agent : public so_5::agent_t {
const so_5::mbox_t another_worker_;
timer_ns::timer_id_t timer_;
...
void on_some_msg(mhood_t<some_message> cmd) {
// Redirect this message to another worker with delay in 250ms.
timer_ = timer_ns::send_delayed(so_environment(),
another_worker_,
std::chrono::milliseconds(250),
std::move(cmd));
...
}
};
Note
The return value of that function must be stored somewhere. Otherwise the delayed timer will be cancelled automatically just right after send_delayed returns.
Attention
Value of pause should be non-negative.
Template Parameters
Messagetype of message or signal to be sent.
Since
v.1.2.0
Parameters
envAn environment to be used for timer.
toMbox for the message to be sent to.
pausePause for message delaying.
cmdMessage to redirect.

Definition at line 802 of file pub.hpp.

◆ send_delayed() [4/4]

template<typename Message , typename Target >
SO_5_NODISCARD timer_id_t so_5::extra::revocable_timer::send_delayed ( Target &&  target,
std::chrono::steady_clock::duration  pause,
::so_5::mhood_t< Message >  cmd 
)

A helper function for redirection of existing message/signal as delayed message.

Agent, ad-hoc agent or mchain can be used as target.

Usage example:

namespace timer_ns = so_5::extra::revocable_timer;
class my_agent : public so_5::agent_t {
const so_5::mchain_t work_queue_;
timer_ns::timer_id_t timer_;
...
void on_some_msg(mhood_t<some_message> cmd) {
// Redirect this message to another worker with delay in 250ms.
timer_ = timer_ns::send_delayed(work_queue_,
std::chrono::milliseconds(250),
std::move(cmd));
...
}
};
Note
The return value of that function must be stored somewhere. Otherwise the delayed timer will be cancelled automatically just right after send_delayed returns.
Attention
Value of pause should be non-negative.
Template Parameters
Messagetype of message or signal to be sent.
Since
v.1.2.0
Parameters
targetA destination for the periodic message.
pausePause for message delaying.
cmdMessage to redirect.

Definition at line 858 of file pub.hpp.

◆ send_periodic() [1/5]

template<typename Message , typename... Args>
SO_5_NODISCARD timer_id_t so_5::extra::revocable_timer::send_periodic ( so_5::environment_t &  env,
const so_5::mbox_t &  to,
std::chrono::steady_clock::duration  pause,
std::chrono::steady_clock::duration  period,
Args &&...  args 
)

A utility function for creating and delivering a periodic message.

This function requires passing a reference to SObjectizer Environment and target mbox. Because of that it usually used outside SObjectizer's agent (where it is possible to use another variant of send_periodic). For example:

so_5::wrapped_env_t sobj; // SObjectizer is started here.
so_5::mbox_t worker_mbox; // Will get a value later.
// Create a worker and get its mbox.
sobj.environment().introduce_coop( [&](so_5::coop_t & coop) {
auto worker = coop.make_agent<worker_agent>(...);
worker_mbox = worker->so_direct_mbox();
});
// Send revocable periodic message to the worker.
auto timer_id = so_5::extra::revocable_timer::send_periodic<tell_status>(
sobj.environment(),
worker_mbox(),
1s, 1s,
... );
... // Do some work.
// Revoke the tell_status message.
timer_id.release();
Note
The return value of that function must be stored somewhere. Otherwise the periodic timer will be cancelled automatically just right after send_periodic returns.
Attention
Values of pause and period should be non-negative.
Since
v.1.2.0
Parameters
envAn environment to be used for timer.
toMbox for the message to be sent to.
pausePause for message delaying.
periodPeriod of message repetitions.
argsMessage constructor parameters.

Definition at line 364 of file pub.hpp.

◆ send_periodic() [2/5]

template<typename Message , typename Target , typename... Args>
SO_5_NODISCARD timer_id_t so_5::extra::revocable_timer::send_periodic ( Target &&  target,
std::chrono::steady_clock::duration  pause,
std::chrono::steady_clock::duration  period,
Args &&...  args 
)

A utility function for creating and delivering a periodic message to the specified destination.

Agent, ad-hoc agent or mchain can be used as target.

Note
Message chains with overload control must be used for periodic messages with additional care because exceptions can't be thrown during dispatching messages from timer.

This function is intended to be used inside SObjectizer's agents where we have this pointer and can extract reference to SObjectizer Environment and the direct mbox of agent from that pointer:

namespace timer_ns = so_5::extra::revocable_timer;
class my_agent : public so_5::agent_t {
timer_ns::timer_id_t timer_;
...
void so_evt_start() override {
...
// Initiate a periodic message to self.
timer_ = timer_ns::send_periodic<do_some_task>(*this, 1s, 1s, ...);
...
}
...
};
Note
The return value of that function must be stored somewhere. Otherwise the periodic timer will be cancelled automatically just right after send_periodic returns.
Attention
Values of pause and period should be non-negative.
Template Parameters
Messagetype of message or signal to be sent.
Targetcan be so_5::agent_t, so_5::adhoc_agent_definition_proxy_t or so_5::mchain_t.
Argslist of arguments for Message's constructor.
Since
v.1.2.0
Parameters
targetA destination for the periodic message.
pausePause for message delaying.
periodPeriod of message repetitions.
argsMessage constructor parameters.

Definition at line 427 of file pub.hpp.

◆ send_periodic() [3/5]

template<typename Message >
SO_5_NODISCARD std::enable_if< !::so_5::is_signal< Message >::value, timer_id_t >::type so_5::extra::revocable_timer::send_periodic ( ::so_5::environment_t &  env,
const ::so_5::mbox_t &  to,
std::chrono::steady_clock::duration  pause,
std::chrono::steady_clock::duration  period,
::so_5::mhood_t< Message >  mhood 
)

A utility function for delivering a periodic from an existing message hood.

Attention
Message must not be a mutable message if period is not 0. Otherwise an exception will be thrown.
Template Parameters
Messagea type of message to be redirected (it can be in form of Msg, so_5::immutable_msg<Msg> or so_5::mutable_msg<Msg>).

Usage example:

namespace timer_ns = so_5::extra::revocable_timer;
class redirector : public so_5::agent_t {
...
void on_some_immutable_message(mhood_t<first_msg> cmd) {
timer_id = timer_ns::send_periodic(so_environment(), another_mbox,
std::chrono::seconds(1),
std::chrono::seconds(15),
cmd);
...
}
void on_some_mutable_message(mhood_t<mutable_msg<second_msg>> cmd) {
timer_id = timer_ns::send_periodic(so_environment(), another_mbox,
std::chrono::seconds(1),
std::chrono::seconds(20),
std::move(cmd));
// Note: cmd is nullptr now, it can't be used anymore.
...
}
};
Note
The return value of that function must be stored somewhere. Otherwise the periodic timer will be cancelled automatically just right after send_periodic returns.
Attention
Values of pause and period should be non-negative.
Since
v.1.2.0
Parameters
envAn environment to be used for timer.
toMbox for the message to be sent to.
pausePause for message delaying.
periodPeriod of message repetitions.
mhoodExisting message hood for message to be sent.

Definition at line 495 of file pub.hpp.

◆ send_periodic() [4/5]

template<typename Message >
SO_5_NODISCARD std::enable_if< ::so_5::is_signal< Message >::value, timer_id_t >::type so_5::extra::revocable_timer::send_periodic ( ::so_5::environment_t &  env,
const ::so_5::mbox_t &  to,
std::chrono::steady_clock::duration  pause,
std::chrono::steady_clock::duration  period,
::so_5::mhood_t< Message >   
)

A utility function for periodic redirection of a signal from existing message hood.

Template Parameters
Messagea type of signal to be redirected (it can be in form of Sig or so_5::immutable_msg<Sig>).

Usage example:

class redirector : public so_5::agent_t {
...
void on_some_immutable_signal(mhood_t<some_signal> cmd) {
so_environment(),
another_mbox,
std::chrono::seconds(1),
std::chrono::seconds(10),
cmd);
...
}
};
Note
The return value of that function must be stored somewhere. Otherwise the periodic timer will be cancelled automatically just right after send_periodic returns.
Attention
Values of pause and period should be non-negative.
Since
v.1.2.0
Parameters
envAn environment to be used for timer.
toMbox for the message to be sent to.
pausePause for message delaying.
periodPeriod of message repetitions.

Definition at line 555 of file pub.hpp.

◆ send_periodic() [5/5]

template<typename Message , typename Target >
SO_5_NODISCARD timer_id_t so_5::extra::revocable_timer::send_periodic ( Target &&  target,
std::chrono::steady_clock::duration  pause,
std::chrono::steady_clock::duration  period,
::so_5::mhood_t< Message >  mhood 
)

A helper function for redirection of a message/signal as a periodic message/signal.

This function can be used if target is a reference to agent or if target is a mchain. In such cases instead of writing:

target_agent.so_environment(),
target_agent.so_direct_mbox(),
pause,
period,
std::move(msg));

it is possible to write:

target_agent,
pause,
period,
std::move(msg));

Example usage:

namespace timer_ns = so_5::extra::revocable_timer;
class my_agent : public so_5::agent_t {
...
so_5::mchain_t target_mchain_;
timer_ns::timer_id_t periodic_msg_id_;
...
void on_some_msg(mhood_t<some_msg> cmd) {
if( ... )
// Message should be resend as a periodic message.
periodic_msg_id_ = timer_ns::send_periodic(target_mchain_, 10s, 20s, std::move(cmd));
}
Note
The return value of that function must be stored somewhere. Otherwise the periodic timer will be cancelled automatically just right after send_periodic returns.
Attention
Values of pause and period should be non-negative.
Since
v.1.2.0
Parameters
targetA target for periodic message/signal. It can be a reference to a target agent or a mchain_t.
pausePause for the first occurence of the message/signal.
periodPeriod of message repetitions.
mhoodExisting message hood for message/signal to be sent.

Definition at line 627 of file pub.hpp.