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

env	An environment to be used for timer.
to	Mbox for the message to be sent to.
pause	Pause for message delaying.
args	Message 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

Message	type of message or signal to be sent.
Target	can be so_5::agent_t, so_5::adhoc_agent_definition_proxy_t or so_5::mchain_t.
Args	list of arguments for Message's constructor.

Since

v.1.2.0

Parameters

target	A destination for the periodic message.
pause	Pause for message delaying.
args	Message 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

Message

type of message or signal to be sent.

Since

v.1.2.0

Parameters

env	An environment to be used for timer.
to	Mbox for the message to be sent to.
pause	Pause for message delaying.
cmd	Message 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

Message

type of message or signal to be sent.

Since

v.1.2.0

Parameters

target	A destination for the periodic message.
pause	Pause for message delaying.
cmd	Message 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

env	An environment to be used for timer.
to	Mbox for the message to be sent to.
pause	Pause for message delaying.
period	Period of message repetitions.
args	Message 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

Message	type of message or signal to be sent.
Target	can be so_5::agent_t, so_5::adhoc_agent_definition_proxy_t or so_5::mchain_t.
Args	list of arguments for Message's constructor.

Since

v.1.2.0

Parameters

target	A destination for the periodic message.
pause	Pause for message delaying.
period	Period of message repetitions.
args	Message 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

Message

a 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

env	An environment to be used for timer.
to	Mbox for the message to be sent to.
pause	Pause for message delaying.
period	Period of message repetitions.
mhood	Existing 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

Message

a 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) {
       timer_id = so_5::extra::revocable_timer::send_periodic(
               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

env	An environment to be used for timer.
to	Mbox for the message to be sent to.
pause	Pause for message delaying.
period	Period 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:

periodic_id = so_5::extra::revocable_timer::send_periodic(
        target_agent.so_environment(),
        target_agent.so_direct_mbox(),
        pause,
        period,
        std::move(msg));

it is possible to write:

periodic_id = so_5::extra::revocable_timer::send_periodic(
        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

target	A target for periodic message/signal. It can be a reference to a target agent or a mchain_t.
pause	Pause for the first occurence of the message/signal.
period	Period of message repetitions.
mhood	Existing message hood for message/signal to be sent.

Definition at line 627 of file pub.hpp.