Concurrency::timer< _Type > Class Template Reference

A timer messaging block is a single-target source_block capable of sending a message to its target after a specified time period has elapsed or at specific intervals. More...

#include <agents.h>

Inheritance diagram for Concurrency::timer< _Type >:

Public Member Functions
	timer (unsigned int _Ms, _Type const &_Value, ITarget< _Type > *_PTarget=NULL, bool _Repeating=false)
	Constructs a timer messaging block that will fire a given message after a specified interval. More...
	~timer ()
	Destroys a timer messaging block. More...
void	start ()
	Starts the timer messaging block. The specified number of milliseconds after this is called, the specified value will be propagated downstream as a message. More...
void	stop ()
	Stops the timer messaging block. More...
void	pause ()
	Stops the timer messaging block. If it is a repeating timer messaging block, it can be restarted with a subsequent start() call. For non-repeating timers, this has the same effect as a stop call. More...
Public Member Functions inherited from Concurrency::source_block< single_link_registry< ITarget< _Type > > >
	source_block ()
	Constructs a source_block object. More...
virtual	~source_block ()
	Destroys the source_block object. More...
virtual void	link_target (_Inout_ ITarget< _Target_type > *_PTarget)
	Links a target block to this source_block object. More...
virtual void	unlink_target (_Inout_ ITarget< _Target_type > *_PTarget)
	Unlinks a target block from this source_block object. More...
virtual void	unlink_targets ()
	Unlinks all target blocks from this source_block object. More...
virtual message< _Target_type > *	accept (runtime_object_identity _MsgId, _Inout_ ITarget< _Target_type > *_PTarget)
	Accepts a message that was offered by this source_block object, transferring ownership to the caller. More...
virtual bool	reserve (runtime_object_identity _MsgId, _Inout_ ITarget< _Target_type > *_PTarget)
	Reserves a message previously offered by this source_block object. More...
virtual message< _Target_type > *	consume (runtime_object_identity _MsgId, _Inout_ ITarget< _Target_type > *_PTarget)
	Consumes a message previously offered by this source_block object and successfully reserved by the target, transferring ownership to the caller. More...
virtual void	release (runtime_object_identity _MsgId, _Inout_ ITarget< _Target_type > *_PTarget)
	Releases a previous successful message reservation. More...
virtual void	acquire_ref (_Inout_ ITarget< _Target_type > *)
	Acquires a reference count on this source_block object, to prevent deletion. More...
virtual void	release_ref (_Inout_ ITarget< _Target_type > *_PTarget)
	Releases a reference count on this source_block object. More...
Public Member Functions inherited from Concurrency::ISource< single_link_registry< ITarget< _Type > >::type::type >
virtual	~ISource ()
	Destroys the ISource object. More...
virtual void	link_target (_Inout_ ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PTarget)=0
	When overridden in a derived class, links a target block to this ISource block. More...
virtual void	unlink_target (_Inout_ ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PTarget)=0
	When overridden in a derived class, unlinks a target block from this ISource block, if found to be previously linked. More...
virtual message< single_link_registry< ITarget< _Type > >::type::type > *	accept (runtime_object_identity _MsgId, _Inout_ ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PTarget)=0
	When overridden in a derived class, accepts a message that was offered by this ISource block, transferring ownership to the caller. More...
virtual bool	reserve (runtime_object_identity _MsgId, _Inout_ ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PTarget)=0
	When overridden in a derived class, reserves a message previously offered by this ISource block. More...
virtual message< single_link_registry< ITarget< _Type > >::type::type > *	consume (runtime_object_identity _MsgId, _Inout_ ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PTarget)=0
	When overridden in a derived class, consumes a message previously offered by this ISource block and successfully reserved by the target, transferring ownership to the caller. More...
virtual void	release (runtime_object_identity _MsgId, _Inout_ ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PTarget)=0
	When overridden in a derived class, releases a previous successful message reservation. More...
virtual void	acquire_ref (_Inout_ ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PTarget)=0
	When overridden in a derived class, acquires a reference count on this ISource block, to prevent deletion. More...
virtual void	release_ref (_Inout_ ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PTarget)=0
	When overridden in a derived class, releases a reference count on this ISource block. More...

Protected Member Functions
virtual message< _Type > *	accept_message (runtime_object_identity _MsgId)
	Accepts a message that was offered by this timer messaging block, transferring ownership to the caller. More...
virtual bool	reserve_message (runtime_object_identity _MsgId)
	Reserves a message previously offered by this timer messaging block. More...
virtual message< _Type > *	consume_message (runtime_object_identity _MsgId)
	Consumes a message previously offered by the timer and reserved by the target, transferring ownership to the caller. More...
virtual void	release_message (runtime_object_identity _MsgId)
	Releases a previous message reservation. More...
virtual void	resume_propagation ()
	Resumes propagation after a reservation has been released. More...
virtual void	link_target_notification (_Inout_ ITarget< _Type > *_PTarget)
	A callback that notifies that a new target has been linked to this timer messaging block. More...
virtual void	propagate_to_any_targets (_Inout_opt_ message< _Type > *)
	Tries to offer the message produced by the timer block to all of the linked targets. More...
Protected Member Functions inherited from Concurrency::details::_Timer
_CRTIMP	_Timer (unsigned int _Ms, bool _FRepeating)
virtual _CRTIMP	~_Timer ()
_CRTIMP void	_Start ()
_CRTIMP void	_Stop ()
Protected Member Functions inherited from Concurrency::source_block< single_link_registry< ITarget< _Type > > >
virtual void	link_target_notification (_Inout_ ITarget< _Target_type > *)
	A callback that notifies that a new target has been linked to this source_block object. More...
virtual void	unlink_target_notification (_Inout_ ITarget< _Target_type > *_PTarget)
	A callback that notifies that a target has been unlinked from this source_block object. More...
virtual void	process_input_messages (_Inout_ message< _Target_type > *_PMessage)
	Process input messages. This is only useful for propagator blocks, which derive from source_block More...
virtual void	propagate_output_messages ()
	Propagate messages to targets. More...
virtual void	propagate_to_any_targets (_Inout_opt_ message< _Target_type > *_PMessage)
	When overridden in a derived class, propagates the given message to any or all of the linked targets. This is the main propagation routine for message blocks. More...
void	initialize_source (_Inout_opt_ Scheduler *_PScheduler=NULL, _Inout_opt_ ScheduleGroup *_PScheduleGroup=NULL)
	Initializes the message_propagator within this source_block. More...
void	enable_batched_processing ()
	Enables batched processing for this block. More...
virtual void	sync_send (_Inout_opt_ message< _Target_type > *_Msg)
	Synchronously queues up messages and starts a propagation task, if this has not been done already. More...
virtual void	async_send (_Inout_opt_ message< _Target_type > *_Msg)
	Asynchronously queues up messages and starts a propagation task, if this has not been done already More...
void	wait_for_outstanding_async_sends ()
	Waits for all asynchronous propagations to complete. This propagator-specific spin wait is used in destructors of message blocks to make sure that all asynchronous propagations have time to finish before destroying the block. More...
void	remove_targets ()
	Removes all target links for this source block. This should be called from the destructor. More...
Protected Member Functions inherited from Concurrency::ISource< single_link_registry< ITarget< _Type > >::type::type >
void	_Invoke_link_source (ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PLinkFrom)
	Links this source to a target. More...
void	_Invoke_unlink_source (ITarget< single_link_registry< ITarget< _Type > >::type::type > *_PUnlinkFrom)
	Unlinks this source from a target. More...

Private Types
enum	State { Initialized, Started, Paused, Stopped }
	Tracks the state machine of the timer. More...

Private Member Functions
message< _Type > *	_NewMessage () const
	Allocates a new message. More...
virtual void	_Fire ()
	Called when the timer fires. More...
void	_Initialize (const _Type &_Value, _Inout_ ITarget< _Type > *_PTarget, bool _Repeating, _Inout_opt_ Scheduler *_PScheduler=NULL, _Inout_opt_ ScheduleGroup *_PScheduleGroup=NULL)
	Common initialization. More...
void	_Delete_stored_messages ()
	Deletes all messages currently stored in this message block. Should be called by the destructor to ensure any messages propagated in are cleaned up. More...
timer const &	operator= (timer const &)
	timer (timer const &)

Private Attributes
message< _Type > *	_M_pMessage
State	_M_state
_Type	_M_value
bool	_M_fRepeating
bool	_M_fReferencedScheduler
Scheduler *	_M_pScheduler

Additional Inherited Members
Public Types inherited from Concurrency::source_block< single_link_registry< ITarget< _Type > > >
typedef single_link_registry< ITarget< _Type > >::type::type	_Target_type
	The payload type of messages handled by this source_block. More...
typedef single_link_registry< ITarget< _Type > >::iterator	target_iterator
	The iterator to walk the connected targets. More...
Public Types inherited from Concurrency::ISource< single_link_registry< ITarget< _Type > >::type::type >
typedef single_link_registry< ITarget< _Type > >::type::type	source_type
	A type alias for _Type . More...
Protected Attributes inherited from Concurrency::source_block< single_link_registry< ITarget< _Type > > >
ITarget< _Target_type > *	_M_pReservedFor
	Connected target that is holding a reservation More...
runtime_object_identity	_M_reservedId
	Reserved message ID More...
single_link_registry< ITarget< _Type > >	_M_connectedTargets
	Connected targets More...
_MessageProcessorType	_M_messageProcessor
	Processor used for asynchronous message handling More...

Detailed Description

template<class _Type>
class Concurrency::timer< _Type >

A timer messaging block is a single-target source_block capable of sending a message to its target after a specified time period has elapsed or at specific intervals.

Template Parameters

_Type

The payload type of the output messages of this block.

For more information, see Asynchronous Message Blocks.

Member Enumeration Documentation

template<class _Type >

enum Concurrency::timer::State

private

Tracks the state machine of the timer.

Enumerator
Initialized	The timer has been initialized, but not yet started.
Started	The timer has been started.
Paused	The timer has started and been paused.
Stopped	The timer has been stopped.

    {
        
        Initialized,
        
        Started,
        
        Paused,
        
        Stopped
    };

Constructor & Destructor Documentation

template<class _Type >

Concurrency::timer< _Type >::timer ( unsigned int  _Ms, _Type const &  _Value, ITarget< _Type > *  _PTarget = NULL, bool  _Repeating = false  )

inline

Constructs a timer messaging block that will fire a given message after a specified interval.

Parameters

_Ms	The number of milliseconds that must elapse after the call to start for the specified message to be propagated downstream.
_Value	The value which will be propagated downstream when the timer elapses.
_PTarget	The target to which the timer will propagate its message.
_Repeating	If true, indicates that the timer will fire periodically every _Ms milliseconds.

The runtime uses the default scheduler if you do not specify the _Scheduler or _ScheduleGroup parameters.

See also

Scheduler Class, ScheduleGroup Class

                                                                                                           :
        _Timer(_Ms, _Repeating)
    {
        _Initialize(_Value, _PTarget, _Repeating);
    }

template<class _Type >

Concurrency::timer< _Type >::~timer ( )

inline

Destroys a timer messaging block.

    {
        //
        // Make sure there are no more outstanding timer fires.  Note that this does not mean that the LWT that was queued is finished, it only
        // means that no more timers will fire after the return from _Stop.  We still *MUST* wait on any outstanding LWTs.
        //
        if (_M_state == Started)
            _Stop();

        // Remove all the targets. This will wait for any outstanding LWTs
        remove_targets();

        //
        // No more asynchronous operations can happen as of this point.
        //

        // Clean up any messages left in this message block
        _Delete_stored_messages();

        if (_M_fReferencedScheduler)
        {
            ::Concurrency::details::_Scheduler(_M_pScheduler)._Release();
        }
    }

template<class _Type >

Concurrency::timer< _Type >::timer ( timer< _Type > const &  )

private

Member Function Documentation

template<class _Type >

void Concurrency::timer< _Type >::_Delete_stored_messages ( )

inlineprivate

Deletes all messages currently stored in this message block. Should be called by the destructor to ensure any messages propagated in are cleaned up.

    {
        // Input messages for this message block are in the base-class input buffer
        // All messages in that buffer are guaranteed to have moved to the output
        // buffer because the destructor first waits for all async sends to finish
        // before reaching this point

        // Delete the message remaining in the output queue
        if (_M_pMessage != NULL)
        {
            delete _M_pMessage;
        }
    }

template<class _Type >

virtual void Concurrency::timer< _Type >::_Fire ( )

inlineprivatevirtual

Called when the timer fires.

Implements Concurrency::details::_Timer.

    {
        async_send(NULL);
    }

template<class _Type >

void Concurrency::timer< _Type >::_Initialize ( const _Type &  _Value, _Inout_ ITarget< _Type > *  _PTarget, bool  _Repeating, _Inout_opt_ Scheduler *  _PScheduler = NULL, _Inout_opt_ ScheduleGroup *  _PScheduleGroup = NULL  )

inlineprivate

Common initialization.

Parameters

_Value	The value which will be propagated downstream when the timer elapses.
_PTarget	The target to which the timer will propagate its message.
_Repeating	If true, indicates that the timer will fire periodically every _Ms milliseconds.

    {
        _M_pMessage = NULL;
        _M_value = _Value;
        _M_fRepeating = _Repeating;
        _M_state = Initialized;
        _M_fReferencedScheduler = false;

        //
        // If we are going to utilize the current scheduler for timer firing, we need to capture it now.  Otherwise,
        // the timer threads fired from Windows (what _Fire executes within) will wind up with a default scheduler
        // attached -- probably not the semantic we want.
        //
        if (_PScheduleGroup == NULL && _PScheduler == NULL)
        {
            ::Concurrency::details::_Scheduler _sched = ::Concurrency::details::_CurrentScheduler::_Get();
            _PScheduler = _sched._GetScheduler();
            _sched._Reference();
            _M_fReferencedScheduler = true;
        }

        _M_pScheduler = _PScheduler;
        initialize_source(_PScheduler, _PScheduleGroup);

        if (_PTarget != NULL)
        {
            link_target(_PTarget);
        }
    }

template<class _Type >

message<_Type>* Concurrency::timer< _Type >::_NewMessage ( ) const

inlineprivate

Allocates a new message.

    {
        return new message<_Type>(_M_value);
    }

template<class _Type >

virtual message<_Type>* Concurrency::timer< _Type >::accept_message ( runtime_object_identity  _MsgId )

inlineprotectedvirtual

Accepts a message that was offered by this timer messaging block, transferring ownership to the caller.

Parameters

_MsgId

The runtime_object_identity of the offered message object.

Returns

A pointer to the message object that the caller now has ownership of.

Implements Concurrency::source_block< single_link_registry< ITarget< _Type > > >.

    {
        if (_M_pMessage == NULL || _MsgId != _M_pMessage->msg_id())
        {
            return NULL;
        }

        message<_Type> *_PMessage = _M_pMessage;
        _M_pMessage = NULL;

        return _PMessage;
    }

template<class _Type >

virtual message<_Type>* Concurrency::timer< _Type >::consume_message ( runtime_object_identity  _MsgId )

inlineprotectedvirtual

Consumes a message previously offered by the timer and reserved by the target, transferring ownership to the caller.

Parameters

_MsgId

The runtime_object_identity of the message object being consumed.

Returns

A pointer to the message object that the caller now has ownership of.

Similar to accept, but is always preceded by a call to reserve.

Implements Concurrency::source_block< single_link_registry< ITarget< _Type > > >.

    {
        return accept_message(_MsgId);
    }

template<class _Type >

virtual void Concurrency::timer< _Type >::link_target_notification ( _Inout_ ITarget< _Type > *  _PTarget )

inlineprotectedvirtual

A callback that notifies that a new target has been linked to this timer messaging block.

Parameters

_PTarget

A pointer to the newly linked target.

    {
        // If there is a timer message sitting around, it must be propagated to the target now.

        if (_M_pMessage != NULL)
        {
            _PTarget->propagate(_M_pMessage, this);
        }
    }

template<class _Type >

timer const& Concurrency::timer< _Type >::operator= ( timer< _Type > const &  )

private

template<class _Type >

void Concurrency::timer< _Type >::pause ( )

inline

Stops the timer messaging block. If it is a repeating timer messaging block, it can be restarted with a subsequent start() call. For non-repeating timers, this has the same effect as a stop call.

    {
        //
        // Non repeating timers cannot pause.  They go to a final stopped state on pause.
        //
        if (!_M_fRepeating)
        {
            stop();
        }
        else
        {
            // Pause only a started timer.

            if (_M_state == Started)
            {
                _Stop();
                _M_state = Paused;
            }
        }
    }

template<class _Type >

virtual void Concurrency::timer< _Type >::propagate_to_any_targets ( _Inout_opt_ message< _Type > *  )

inlineprotectedvirtual

Tries to offer the message produced by the timer block to all of the linked targets.

    {
        if (_M_pMessage == NULL)
        {
            _M_pMessage = _NewMessage();
            for (target_iterator _Iter = _M_connectedTargets.begin(); *_Iter != NULL; ++_Iter)
            {
                ITarget<_Type> * _PTarget = *_Iter;
                _PTarget->propagate(_M_pMessage, this);
            }
        }
    }

template<class _Type >

virtual void Concurrency::timer< _Type >::release_message ( runtime_object_identity  _MsgId )

inlineprotectedvirtual

Releases a previous message reservation.

Parameters

_MsgId

The runtime_object_identity of the message object being released.

Implements Concurrency::source_block< single_link_registry< ITarget< _Type > > >.

    {
        if (_M_pMessage == NULL || _M_pMessage->msg_id() != _MsgId)
        {
            throw message_not_found();
        }

        delete _M_pMessage;
        _M_pMessage = NULL;
    }

template<class _Type >

virtual bool Concurrency::timer< _Type >::reserve_message ( runtime_object_identity  _MsgId )

inlineprotectedvirtual

Reserves a message previously offered by this timer messaging block.

Parameters

_MsgId

The runtime_object_identity of the message object being reserved.

Returns

true if the message was successfully reserved, false otherwise.

After reserve is called, if it returns true, either consume or release must be called to either take or release ownership of the message.

Implements Concurrency::source_block< single_link_registry< ITarget< _Type > > >.

    {
        //
        // Semantically, every timer tick is the same value -- it doesn't matter the message ID.  Because we can only
        // have one target as well, we do not need to track anything here.
        //
        if (_M_pMessage == NULL || _M_pMessage->msg_id() != _MsgId)
        {
            return false;
        }

        return true;
    }

template<class _Type >

virtual void Concurrency::timer< _Type >::resume_propagation ( )

inlineprotectedvirtual

Resumes propagation after a reservation has been released.

Implements Concurrency::source_block< single_link_registry< ITarget< _Type > > >.

    {
        // Because reservation doesn't prevent propagation there is
        // no need to resume on consume/release.
    }

template<class _Type >

void Concurrency::timer< _Type >::start ( )

inline

Starts the timer messaging block. The specified number of milliseconds after this is called, the specified value will be propagated downstream as a message.

    {
        if (_M_state == Initialized || _M_state == Paused)
        {
            _M_state = Started;
            _Start();
        }
    }

template<class _Type >

void Concurrency::timer< _Type >::stop ( )

inline

Stops the timer messaging block.

    {
        if (_M_state == Started)
            _Stop();

        _M_state = Stopped;
    }

Member Data Documentation

template<class _Type >

bool Concurrency::timer< _Type >::_M_fReferencedScheduler

private

template<class _Type >

bool Concurrency::timer< _Type >::_M_fRepeating

private

template<class _Type >

message<_Type>* Concurrency::timer< _Type >::_M_pMessage

private

template<class _Type >

Scheduler* Concurrency::timer< _Type >::_M_pScheduler

private

template<class _Type >

State Concurrency::timer< _Type >::_M_state

private

template<class _Type >

_Type Concurrency::timer< _Type >::_M_value

private

---

The documentation for this class was generated from the following file:

• VS2013/inc/agents.h