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 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 (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 (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 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 (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/3]

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

Usage example 1:

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, ...);
...
}
...
};

Usage example 2:

so_5::wrapped_env_t sobj; // SObjectizer is started here.
// Create a worker and get its mbox.
so_5::mbox_t worker_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>(
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.
Template Parameters
Messagetype of message or signal to be sent.
Targetcan be so_5::agent_t, so_5::mbox_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 637 of file pub.hpp.

◆ send_delayed() [2/3]

template<typename Message >
SO_5_NODISCARD timer_id_t so_5::extra::revocable_timer::send_delayed ( 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.
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
toMbox for the message to be sent to.
pausePause for message delaying.
cmdMessage to redirect.

Definition at line 689 of file pub.hpp.

◆ send_delayed() [3/3]

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 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 742 of file pub.hpp.

◆ send_periodic() [1/4]

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

Usage example 1:

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, ...);
...
}
...
};

Usage example 2:

so_5::wrapped_env_t sobj; // SObjectizer is started here.
// Create a worker and get its mbox.
so_5::mbox_t worker_mbox = sobj.environment().introduce_coop(
[&](so_5::coop_t & coop) {
auto worker = coop.make_agent<worker_agent>(...);
return worker->so_direct_mbox();
});
// Send revocable periodic message to the worker.
auto timer_id = so_5::extra::revocable_timer::send_periodic<tell_status>(
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.
Template Parameters
Messagetype of message or signal to be sent.
Targetcan be so_5::agent_t, so_5::mbox_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 378 of file pub.hpp.

◆ send_periodic() [2/4]

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 ( 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) {
another_mbox,
std::chrono::seconds(1),
std::chrono::seconds(15),
cmd);
...
}
void on_some_mutable_message(mhood_t<mutable_msg<second_msg>> cmd) {
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
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 447 of file pub.hpp.

◆ send_periodic() [3/4]

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 ( 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) {
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
toMbox for the message to be sent to.
pausePause for message delaying.
periodPeriod of message repetitions.

Definition at line 503 of file pub.hpp.

◆ send_periodic() [4/4]

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

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 556 of file pub.hpp.