pub.hpp

Go to the documentation of this file.

/*!
 * \file
 * \brief Implementation of revocable timers
 *
 * \since
 * v.1.2.0
 */

#pragma once

#include <so_5/version.hpp>

#include <so_5_extra/revocable_msg/pub.hpp>

#include <so_5_extra/error_ranges.hpp>

#include <so_5/timers.hpp>
#include <so_5/enveloped_msg.hpp>
#include <so_5/send_functions.hpp>

#include <atomic>

namespace so_5 {

namespace extra {

namespace revocable_timer {

namespace details {

//
// envelope_t
//
/*!
 * \brief A special envelope to be used for revocable timer messages.
 *
 * Just a synonim for so_5::extra::revocable_msg::details::envelope_t.
 *
 * \since
 * v.1.2.0
 */
using envelope_t = so_5::extra::revocable_msg::details::envelope_t;

} /* namespace details */

namespace impl {

// Just forward declaration. Definition will be below definition of timer_id_t.
struct timer_id_maker_t;

} /* namespace impl */

//
// timer_id_t
//
/*!
 * \brief The ID of revocable timer message/signal.
 *
 * This type plays the same role as so_5::timer_id_t. But provide
 * guaranteed revocation of delayed/periodic message/signal.
 *
 * There are several implementations of send_delayed() and send_periodic()
 * functions in so_5::extra::revocable_timer namespace. They all return
 * instances of timer_id_t.
 *
 * An instance of timer_id_t returned from send_delayed/send_periodic need
 * to be store somewhere. Otherwise the timer message will be revoked
 * just after completion of send_delayed/send_periodic function. It is
 * because the destructor of timer_id_t will be called and that destructor
 * revokes the timer message.
 *
 * An instance of timer_id_t can be used for revocation of a timer message.
 * Revocation can be performed by two ways:
 *
 * 1. Destructor of timer_id_t automatically revokes the timer message.
 * 2. Method timer_id_t::release() or timer_id_t::revoke() is called
 *    by an user.
 *
 * For example:
 * \code
 * namespace timer_ns = so_5::extra::revocable_timer;
 * void demo(so_5::mchain_t work_queue) {
 *  // Send a delayed demand to work queue and store the ID returned.
 *  auto id = timer_ns::send_delayed<flush_data>(work_queue, 10s, ...);
 *  ... // Do some work.
 *  if(some_condition)
 *      // Our previous message should be revoked if it is not delivered yet.
 *      id.release();
 *  ...
 *  // Message will be automatically revoked here because ID is destroyed
 *  // on leaving the scope.
 * }
 * \endcode
 *
 * \note
 * The timer_id_t is Movable, not Copyable.
 *
 * \attention
 * This is not a thread-safe class. It means that it is dangerous to
 * call methods of that class (like revoke() or is_active()) from
 * different threads at the same time.
 *
 * \since
 * v.1.2.0
 */
class timer_id_t final
    {
        friend struct ::so_5::extra::revocable_timer::impl::timer_id_maker_t;

    private :
        //! The envelope that was sent.
        /*!
         * \note Can be nullptr if default constructor was used.
         */
        ::so_5::intrusive_ptr_t< details::envelope_t > m_envelope;

        //! Timer ID for the envelope.
        ::so_5::timer_id_t m_actual_id;

        timer_id_t(
            ::so_5::intrusive_ptr_t< details::envelope_t > envelope,
            ::so_5::timer_id_t actual_id )
            :   m_envelope{ std::move(envelope) }
            ,   m_actual_id{ std::move(actual_id) }
            {}

    public :
        timer_id_t() = default;
        /*!
         * \note The destructor automatically revokes the message if it is
         * not delivered yet.
         */
        ~timer_id_t() noexcept
            {
                release();
            }

        // This class is not copyable.
        timer_id_t( const timer_id_t & ) = delete;
        timer_id_t & operator=( const timer_id_t & ) = delete;

        // But this class is moveable.
        timer_id_t( timer_id_t && ) noexcept = default;
        timer_id_t & operator=( timer_id_t && ) noexcept = default;

        friend void
        swap( timer_id_t & a, timer_id_t & b ) noexcept
            {
                a.m_envelope.swap( b.m_envelope );
                a.m_actual_id.swap( b.m_actual_id );
            }

        //! Is message delivery still in progress?
        /*!
         * \note Please take care when using this method.
         * Message delivery in SObjectizer is asynchronous operation.
         * It means that you can receve \a true from is_active() but
         * this value will already be obsolete because the message
         * can be delivered just before return from is_active().
         * The return value of is_active() can be useful in that context:
         * \code
         * namespace timer_ns = so_5::extra::revocable_timer;
         * void demo(so_5::mchain_t work_queue) {
         *  auto id = timer_ns::send_delayed(work_queue, 10s, ...);
         *  ... // Do some work.
         *  if(some_condition)
         *      id.revoke();
         *  ... // Do some more work.
         *  if(another_condition)
         *      id.revoke();
         *  ...
         *  if(id.is_active()) {
         *      // No previous calls to revoke().
         *      ...
         *  }
         * }
         * \endcode
         */
        bool
        is_active() const noexcept
            {
                return m_actual_id.is_active();
            }

        //! Revoke the message and release the timer.
        /*!
         * \note
         * It is safe to call release() for already revoked message.
         */
        void
        release() noexcept
            {
                if( m_envelope )
                    {
                        m_envelope->revoke();
                        m_actual_id.release();

                        m_envelope.reset();
                    }
            }

        //! Revoke the message and release the timer.
        /*!
         * Just a synonym for release() method.
         */
        void
        revoke() noexcept { release(); }
    };

namespace impl {

/*
 * This is helper for creation of initialized timer_id objects.
 */
struct timer_id_maker_t
    {
        template< typename... Args >
        [[nodiscard]] static auto
        make( Args && ...args )
            {
                return ::so_5::extra::revocable_timer::timer_id_t{
                        std::forward<Args>(args)... };
            }
    };

/*
 * Helper function for actual sending of periodic message.
 */
[[nodiscard]]
inline so_5::extra::revocable_timer::timer_id_t
make_envelope_and_initiate_timer(
    const so_5::mbox_t & to,
    const std::type_index & msg_type,
    message_ref_t payload,
    std::chrono::steady_clock::duration pause,
    std::chrono::steady_clock::duration period )
    {
        using envelope_t = ::so_5::extra::revocable_timer::details::envelope_t;

        ::so_5::intrusive_ptr_t< envelope_t > envelope{
                std::make_unique< envelope_t >( std::move(payload) ) };

        auto actual_id = ::so_5::low_level_api::schedule_timer(
                msg_type,
                envelope,
                to,
                pause,
                period );

        return timer_id_maker_t::make(
                std::move(envelope), std::move(actual_id) );
    }

/*
 * This is helpers for send_delayed and send_periodic implementation.
 */

template< class Message, bool Is_Signal >
struct instantiator_and_sender_base
    {
        template< typename... Args >
        [[nodiscard]] static ::so_5::extra::revocable_timer::timer_id_t
        send_periodic(
            const ::so_5::mbox_t & to,
            std::chrono::steady_clock::duration pause,
            std::chrono::steady_clock::duration period,
            Args &&... args )
            {
                message_ref_t payload{
                        so_5::details::make_message_instance< Message >(
                                std::forward< Args >( args )...)
                };

                so_5::details::mark_as_mutable_if_necessary< Message >( *payload );

                return make_envelope_and_initiate_timer(
                        to,
                        message_payload_type< Message >::subscription_type_index(),
                        std::move(payload),
                        pause,
                        period );
            }
    };

template< class Message >
struct instantiator_and_sender_base< Message, true >
    {
        //! Type of signal to be delivered.
        using actual_signal_type = typename message_payload_type< Message >::subscription_type;

        [[nodiscard]] static so_5::extra::revocable_timer::timer_id_t
        send_periodic(
            const so_5::mbox_t & to,
            std::chrono::steady_clock::duration pause,
            std::chrono::steady_clock::duration period )
            {
                return make_envelope_and_initiate_timer(
                        to,
                        message_payload_type< Message >::subscription_type_index(),
                        message_ref_t{},
                        pause,
                        period );
            }
    };

template< class Message >
struct instantiator_and_sender
    :   public instantiator_and_sender_base<
            Message,
            is_signal< typename message_payload_type< Message >::payload_type >::value >
    {};

} /* namespace impl */

/*!
 * \brief A utility function for creating and delivering a periodic message
 * to the specified destination.
 *
 * Agent, mbox or mchain can be used as \a 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:
 * \code
 * 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, ...);
 *      ...
 *  }
 *  ...
 * };
 * \endcode
 *
 * Usage example 2:
 * \code
 * 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();
 * \endcode
 *
 * \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 \a pause and \a period should be non-negative.
 *
 * \tparam Message type of message or signal to be sent.
 * \tparam Target can be so_5::agent_t, so_5::mbox_t or so_5::mchain_t.
 * \tparam Args list of arguments for Message's constructor.
 *
 * \since
 * v.1.2.0
 */
template< typename Message, typename Target, typename... Args >
[[nodiscard]] timer_id_t
send_periodic(
    //! A destination for the periodic message.
    Target && target,
    //! Pause for message delaying.
    std::chrono::steady_clock::duration pause,
    //! Period of message repetitions.
    std::chrono::steady_clock::duration period,
    //! Message constructor parameters.
    Args&&... args )
    {
        return impl::instantiator_and_sender< Message >::send_periodic(
                ::so_5::send_functions_details::arg_to_mbox( target ),
                pause,
                period,
                std::forward< Args >( args )... );
    }

/*!
 * \brief A utility function for delivering a periodic
 * from an existing message hood.
 *
 * \attention Message must not be a mutable message if \a period is not 0.
 * Otherwise an exception will be thrown.
 *
 * \tparam 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:
 * \code
    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.
            ...
        }
    };
 * \endcode
 *
 * \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 \a pause and \a period should be non-negative.
 *
 * \since
 * v.1.2.0
 */
template< typename Message >
[[nodiscard]]
typename std::enable_if<
        !::so_5::is_signal< Message >::value,
        timer_id_t >::type
send_periodic(
    //! Mbox for the message to be sent to.
    const ::so_5::mbox_t & to,
    //! Pause for message delaying.
    std::chrono::steady_clock::duration pause,
    //! Period of message repetitions.
    std::chrono::steady_clock::duration period,
    //! Existing message hood for message to be sent.
    ::so_5::mhood_t< Message > mhood )
    {
        return impl::make_envelope_and_initiate_timer(
                to,
                message_payload_type< Message >::subscription_type_index(),
                mhood.make_reference(),
                pause,
                period );
    }

/*!
 * \brief A utility function for periodic redirection of a signal
 * from existing message hood.
 *
 * \tparam Message a type of signal to be redirected (it can be
 * in form of Sig or so_5::immutable_msg<Sig>).
 *
 * Usage example:
 * \code
    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);
            ...
        }
    };
 * \endcode
 *
 * \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 \a pause and \a period should be non-negative.
 *
 * \since
 * v.1.2.0
 */
template< typename Message >
[[nodiscard]]
typename std::enable_if<
        ::so_5::is_signal< Message >::value,
        timer_id_t >::type
send_periodic(
    //! Mbox for the message to be sent to.
    const ::so_5::mbox_t & to,
    //! Pause for message delaying.
    std::chrono::steady_clock::duration pause,
    //! Period of message repetitions.
    std::chrono::steady_clock::duration period,
    //! Existing message hood for message to be sent.
    ::so_5::mhood_t< Message > /*mhood*/ )
    {
        return impl::make_envelope_and_initiate_timer(
                to,
                message_payload_type< Message >::subscription_type_index(),
                message_ref_t{},
                pause,
                period );
    }

/*!
 * \brief A helper function for redirection of a message/signal as a periodic
 * message/signal.
 *
 * This function can be used if \a target is a reference to agent or if
 * \a target is a mchain
 *
 * Example usage:
 * \code
 * 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));
 *  }
 * \endcode
 *
 * \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 \a pause and \a period should be non-negative.
 *
 * \since
 * v.1.2.0
 */
template< typename Message, typename Target >
[[nodiscard]] timer_id_t
send_periodic(
    //! A target for periodic message/signal.
    //! It can be a reference to a target agent or a mchain_t.
    Target && target,
    //! Pause for the first occurence of the message/signal.
    std::chrono::steady_clock::duration pause,
    //! Period of message repetitions.
    std::chrono::steady_clock::duration period,
    //! Existing message hood for message/signal to be sent.
    ::so_5::mhood_t< Message > mhood )
    {
        return ::so_5::extra::revocable_timer::send_periodic< Message >(
                ::so_5::send_functions_details::arg_to_mbox( target ),
                pause,
                period,
                std::move(mhood) );
    }

/*!
 * \brief A utility function for creating and delivering a delayed message
 * to the specified destination.
 *
 * Agent, mbox or mchain can be used as \a 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:
 * \code
 * 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, ...);
 *      ...
 *  }
 *  ...
 * };
 * \endcode
 *
 * Usage example 2:
 * \code
 * 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();
 * \endcode
 *
 * \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 \a pause should be non-negative.
 *
 * \tparam Message type of message or signal to be sent.
 * \tparam Target can be so_5::agent_t, so_5::mbox_t or so_5::mchain_t.
 * \tparam Args list of arguments for Message's constructor.
 *
 * \since
 * v.1.2.0
 */
template< typename Message, typename Target, typename... Args >
[[nodiscard]] timer_id_t
send_delayed(
    //! A destination for the periodic message.
    Target && target,
    //! Pause for message delaying.
    std::chrono::steady_clock::duration pause,
    //! Message constructor parameters.
    Args&&... args )
    {
        return ::so_5::extra::revocable_timer::send_periodic< Message >(
                ::so_5::send_functions_details::arg_to_mbox( target ),
                pause,
                std::chrono::steady_clock::duration::zero(),
                std::forward<Args>(args)... );
    }

/*!
 * \brief A helper function for redirection of existing message/signal
 * as delayed message.
 *
 * Usage example:
 * \code
 * 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));
 *      ...
 *  }
 * };
 * \endcode
 *
 * \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 \a pause should be non-negative.
 *
 * \tparam Message type of message or signal to be sent.
 *
 * \since
 * v.1.2.0
 */
template< typename Message >
[[nodiscard]] timer_id_t
send_delayed(
    //! Mbox for the message to be sent to.
    const so_5::mbox_t & to,
    //! Pause for message delaying.
    std::chrono::steady_clock::duration pause,
    //! Message to redirect.
    ::so_5::mhood_t< Message > cmd )
    {
        return ::so_5::extra::revocable_timer::send_periodic< Message >(
                to,
                pause,
                std::chrono::steady_clock::duration::zero(),
                std::move(cmd) );
    }

/*!
 * \brief A helper function for redirection of existing message/signal
 * as delayed message.
 *
 * Agent or mchain can be used as \a target.
 *
 * Usage example:
 * \code
 * 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));
 *      ...
 *  }
 * };
 * \endcode
 *
 * \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 \a pause should be non-negative.
 *
 * \tparam Message type of message or signal to be sent.
 *
 * \since
 * v.1.2.0
 */
template< typename Message, typename Target >
[[nodiscard]] timer_id_t
send_delayed(
    //! A destination for the periodic message.
    Target && target,
    //! Pause for message delaying.
    std::chrono::steady_clock::duration pause,
    //! Message to redirect.
    ::so_5::mhood_t< Message > cmd )
    {
        return ::so_5::extra::revocable_timer::send_periodic(
                std::forward<Target>(target),
                pause,
                std::chrono::steady_clock::duration::zero(),
                std::move(cmd) );
    }

} /* namespace revocable_timer */

} /* namespace extra */

} /* namespace so_5 */