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

Message	type of message or signal to be sent.
Target	can be so_5::agent_t, so_5::mbox_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 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.
        timer_ = timer_ns::send_delayed(
                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

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

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 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

Message	type of message or signal to be sent.
Target	can be so_5::agent_t, so_5::mbox_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 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

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(
               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(
               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

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 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

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(
               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

to	Mbox for the message to be sent to.
pause	Pause for message delaying.
period	Period 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

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