Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType > Class Template Reference

The propagator_block class is an abstract base class for message blocks that are both a source and target. It combines the functionality of both the source_block and target_block classes. More...

#include <agents.h>

Inheritance diagram for Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >:

Public Types
typedef _SourceLinkRegistry::type::source_type	_Source_type
	The type of the payload for the incoming message to this propagator_block. More...
typedef source_link_manager< _SourceLinkRegistry >	_SourceLinkManager
	The type of the source_link_manager this propagator_block. More...
typedef _SourceLinkManager::iterator	source_iterator
	The type of the iterator for the source_link_manager for this propagator_block. More...
Public Types inherited from Concurrency::source_block< _TargetLinkRegistry, _MessageProcessorType >
typedef _TargetLinkRegistry::type::type	_Target_type
	The payload type of messages handled by this source_block. More...
typedef _TargetLinkRegistry::iterator	target_iterator
	The iterator to walk the connected targets. More...
Public Types inherited from Concurrency::ISource< _TargetLinkRegistry::type::type >
typedef _TargetLinkRegistry::type::type	source_type
	A type alias for _Type . More...
Public Types inherited from Concurrency::ITarget< _SourceLinkRegistry::type::source_type >
typedef _SourceLinkRegistry::type::source_type	type
	A type alias for _Type . More...
typedef std::function< bool(_SourceLinkRegistry::type::source_typeconst &)>	filter_method
	The signature of any method used by the block that returns a bool value to determine whether an offered message should be accepted. More...

Public Member Functions
	propagator_block ()
	Constructs a propagator_block object. More...
virtual	~propagator_block ()
	Destroys a propagator_block object. More...
virtual message_status	propagate (_Inout_opt_ message< _Source_type > *_PMessage, _Inout_opt_ ISource< _Source_type > *_PSource)
	Asynchronously passes a message from a source block to this target block. More...
virtual message_status	send (_Inout_ message< _Source_type > *_PMessage, _Inout_ ISource< _Source_type > *_PSource)
	Synchronously initiates a message to this block. Called by an ISource block. When this function completes, the message will already have propagated into the block. More...
Public Member Functions inherited from Concurrency::source_block< _TargetLinkRegistry, _MessageProcessorType >
	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< _TargetLinkRegistry::type::type >
virtual	~ISource ()
	Destroys the ISource object. More...
Public Member Functions inherited from Concurrency::ITarget< _SourceLinkRegistry::type::source_type >
virtual	~ITarget ()
	Destroys the ITarget object. More...
virtual bool	supports_anonymous_source ()
	When overridden in a derived class, returns true or false depending on whether the message block accepts messages offered by a source that is not linked to it. If the overridden method returns true, the target cannot postpone an offered message, as consumption of a postponed message at a later time requires the source to be identified in its source link registry. More...

Protected Member Functions
virtual message_status	propagate_message (_Inout_ message< _Source_type > *_PMessage, _Inout_ ISource< _Source_type > *_PSource)=0
	When overridden in a derived class, this method asynchronously passes a message from an ISource block to this propagator_block object. It is invoked by the propagate method, when called by a source block. More...
virtual message_status	send_message (_Inout_ message< _Source_type > *, _Inout_ ISource< _Source_type > *)
	When overridden in a derived class, this method synchronously passes a message from an ISource block to this propagator_block object. It is invoked by the send method, when called by a source block. More...
virtual void	link_source (_Inout_ ISource< _Source_type > *_PSource)
	Links a specified source block to this propagator_block object. More...
virtual void	unlink_source (_Inout_ ISource< _Source_type > *_PSource)
	Unlinks a specified source block from this propagator_block object. More...
virtual void	unlink_sources ()
	Unlinks all source blocks from this propagator_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...
void	initialize_source_and_target (_Inout_opt_ Scheduler *_PScheduler=NULL, _Inout_opt_ ScheduleGroup *_PScheduleGroup=NULL)
	Initializes the base object. Specifically, the message_processor object needs to be initialized. More...
void	register_filter (filter_method const &_Filter)
	Registers a filter method that will be invoked on every received message. More...
void	decline_incoming_messages ()
	Indicates to the block that new messages should be declined. More...
void	remove_network_links ()
	Removes all the source and target network links from this propagator_block object. More...
Protected Member Functions inherited from Concurrency::source_block< _TargetLinkRegistry, _MessageProcessorType >
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 message< _Target_type > *	accept_message (runtime_object_identity _MsgId)=0
	When overridden in a derived class, accepts an offered message by the source. Message blocks should override this method to validate the _MsgId and return a message. More...
virtual bool	reserve_message (runtime_object_identity _MsgId)=0
	When overridden in a derived class, reserves a message previously offered by this source_block object. More...
virtual message< _Target_type > *	consume_message (runtime_object_identity _MsgId)=0
	When overridden in a derived class, consumes a message that was previously reserved. More...
virtual void	release_message (runtime_object_identity _MsgId)=0
	When overridden in a derived class, releases a previous message reservation. More...
virtual void	resume_propagation ()=0
	When overridden in a derived class, resumes propagation after a reservation has been released. 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< _TargetLinkRegistry::type::type >
void	_Invoke_link_source (ITarget< _TargetLinkRegistry::type::type > *_PLinkFrom)
	Links this source to a target. More...
void	_Invoke_unlink_source (ITarget< _TargetLinkRegistry::type::type > *_PUnlinkFrom)
	Unlinks this source from a target. More...

Protected Attributes
_SourceLinkManager	_M_connectedSources
	The container for all the sources connected to this block. More...
filter_method *	_M_pFilter
	The filter function which determines whether offered messages should be accepted. More...
volatile bool	_M_fDeclineMessages
	A bool that is set to indicate that all messages should be declined in preparation for deleting the block More...
Protected Attributes inherited from Concurrency::source_block< _TargetLinkRegistry, _MessageProcessorType >
ITarget< _Target_type > *	_M_pReservedFor
	Connected target that is holding a reservation More...
runtime_object_identity	_M_reservedId
	Reserved message ID More...
_TargetLinkRegistry	_M_connectedTargets
	Connected targets More...
_MessageProcessorType	_M_messageProcessor
	Processor used for asynchronous message handling More...

Detailed Description

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>
class Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >

The propagator_block class is an abstract base class for message blocks that are both a source and target. It combines the functionality of both the source_block and target_block classes.

Template Parameters

_TargetLinkRegistry	The link registry to be used for holding the target links.
_SourceLinkRegistry	The link registry to be used for holding the source links.
_MessageProcessorType	The processor type for message processing.

To avoid multiple inheritance, the propagator_block class inherits from the source_block class and ITarget abstract class. Most of the functionality in the target_block class is replicated here.

See also

source_block Class, ITarget Class

Member Typedef Documentation

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

typedef _SourceLinkRegistry::type::source_type Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::_Source_type

The type of the payload for the incoming message to this propagator_block.

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

typedef source_link_manager<_SourceLinkRegistry> Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::_SourceLinkManager

The type of the source_link_manager this propagator_block.

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

typedef _SourceLinkManager::iterator Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::source_iterator

The type of the iterator for the source_link_manager for this propagator_block.

Constructor & Destructor Documentation

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::propagator_block ( )

inline

Constructs a propagator_block object.

                       : _M_pFilter(NULL), _M_fDeclineMessages(false)
    {
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::~propagator_block ( )

inlinevirtual

Destroys a propagator_block object.

    {
        remove_network_links();

        delete _M_pFilter;
    }

Member Function Documentation

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

void Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::decline_incoming_messages ( )

inlineprotected

Indicates to the block that new messages should be declined.

This method is called by the destructor to ensure that new messages are declined while destruction is in progress.

    {
        _M_fDeclineMessages = true;
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

void Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::initialize_source_and_target ( _Inout_opt_ Scheduler *  _PScheduler = NULL, _Inout_opt_ ScheduleGroup *  _PScheduleGroup = NULL  )

inlineprotected

Initializes the base object. Specifically, the message_processor object needs to be initialized.

Parameters

_PScheduler	The scheduler to be used for scheduling tasks.
_PScheduleGroup	The schedule group to be used for scheduling tasks.

See also

Scheduler Class, ScheduleGroup Class

    {
        this->initialize_source(_PScheduler, _PScheduleGroup);

        // Register this propagator block as the owner of the connected sources
        _M_connectedSources.register_target_block(this);
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual void Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::link_source ( _Inout_ ISource< _Source_type > *  _PSource )

inlineprotectedvirtual

Links a specified source block to this propagator_block object.

Parameters

_PSource

A pointer to the ISource block that is to be linked.

Implements Concurrency::ITarget< _SourceLinkRegistry::type::source_type >.

    {
        _M_connectedSources.add(_PSource);
        _Trace_agents(AGENTS_EVENT_LINK,
            ::Concurrency::details::_Trace_agents_get_id(_PSource),
            ::Concurrency::details::_Trace_agents_get_id(this));
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual void Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::process_input_messages ( _Inout_ message< _Target_type > *  _PMessage )

inlineprotectedvirtual

Process input messages. This is only useful for propagator blocks, which derive from source_block

Reimplemented from Concurrency::source_block< _TargetLinkRegistry, _MessageProcessorType >.

    {
        throw invalid_operation("To use batched processing, you must override process_input_messages in the message block.");
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual message_status Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::propagate ( _Inout_opt_ message< _Source_type > *  _PMessage, _Inout_opt_ ISource< _Source_type > *  _PSource  )

inlinevirtual

Asynchronously passes a message from a source block to this target block.

Parameters

_PMessage	A pointer to the message object.
_PSource	A pointer to the source block offering the message.

Returns

A message_status indication of what the target decided to do with the message.

The propagate method is invoked on a target block by a linked source block. It queues up an asynchronous task to handle the message, if one is not already queued or executing.

The method throws an invalid_argument exception if either the _PMessage or _PSource parameter is NULL.

Implements Concurrency::ITarget< _SourceLinkRegistry::type::source_type >.

    {
        // It is important that calls to propagate do *not* take the same lock on the
        // internal structure that is used by <c>consume</c> and the LWT.  Doing so could
        // result in a deadlock.

        if (_PMessage == NULL)
        {
            throw std::invalid_argument("_PMessage");
        }

        if (_PSource == NULL)
        {
            throw std::invalid_argument("_PSource");
        }

        if (_M_fDeclineMessages)
        {
            return declined;
        }

        if (_M_pFilter != NULL && !(*_M_pFilter)(_PMessage->payload))
        {
            return declined;
        }

        return propagate_message(_PMessage, _PSource);
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual message_status Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::propagate_message ( _Inout_ message< _Source_type > *  _PMessage, _Inout_ ISource< _Source_type > *  _PSource  )

protectedpure virtual

When overridden in a derived class, this method asynchronously passes a message from an ISource block to this propagator_block object. It is invoked by the propagate method, when called by a source block.

Parameters

_PMessage	A pointer to the message object.
_PSource	A pointer to the source block offering the message.

Returns

A message_status indication of what the target decided to do with the message.

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

void Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::register_filter ( filter_method const &  _Filter )

inlineprotected

Registers a filter method that will be invoked on every received message.

Parameters

_Filter

The filter method.

    {
        if (_Filter != NULL)
        {
            _M_pFilter = new filter_method(_Filter);
        }
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

void Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::remove_network_links ( )

inlineprotected

Removes all the source and target network links from this propagator_block object.

    {
        // Decline messages while the links are being removed
        decline_incoming_messages();

        // Remove all the target links. This waits for
        // all outstanding async propagation operations.
        this->remove_targets();

        // unlink all sources. The above steps guarantee that
        // they can be removed safely.
        unlink_sources();
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual message_status Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::send ( _Inout_ message< _Source_type > *  _PMessage, _Inout_ ISource< _Source_type > *  _PSource  )

inlinevirtual

Synchronously initiates a message to this block. Called by an ISource block. When this function completes, the message will already have propagated into the block.

Parameters

_PMessage	A pointer to the message object.
_PSource	A pointer to the source block offering the message.

Returns

A message_status indication of what the target decided to do with the message.

This method throws an invalid_argument exception if either the _PMessage or _PSource parameter is NULL.

Implements Concurrency::ITarget< _SourceLinkRegistry::type::source_type >.

    {
        if (_PMessage == NULL)
        {
            throw std::invalid_argument("_PMessage");
        }

        if (_PSource == NULL)
        {
            throw std::invalid_argument("_PSource");
        }

        if (_M_fDeclineMessages)
        {
            return declined;
        }

        if (_M_pFilter != NULL && !(*_M_pFilter)(_PMessage->payload))
        {
            return declined;
        }

        return send_message(_PMessage, _PSource);
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual message_status Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::send_message ( _Inout_ message< _Source_type > *  , _Inout_ ISource< _Source_type > *    )

inlineprotectedvirtual

When overridden in a derived class, this method synchronously passes a message from an ISource block to this propagator_block object. It is invoked by the send method, when called by a source block.

Parameters

_PMessage	A pointer to the message object.
_PSource	A pointer to the source block offering the message.

Returns

A message_status indication of what the target decided to do with the message.

By default, this block returns declined unless overridden by a derived class.

    {
        // By default we do not allow send()
        return declined;
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual void Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::unlink_source ( _Inout_ ISource< _Source_type > *  _PSource )

inlineprotectedvirtual

Unlinks a specified source block from this propagator_block object.

Parameters

_PSource

A pointer to the ISource block that is to be unlinked.

Implements Concurrency::ITarget< _SourceLinkRegistry::type::source_type >.

    {
        _Trace_agents(AGENTS_EVENT_UNLINK,
            ::Concurrency::details::_Trace_agents_get_id(_PSource),
            ::Concurrency::details::_Trace_agents_get_id(this));

        _M_connectedSources.remove(_PSource);
    }

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

virtual void Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::unlink_sources ( )

inlineprotectedvirtual

Unlinks all source blocks from this propagator_block object.

Implements Concurrency::ITarget< _SourceLinkRegistry::type::source_type >.

    {
        for (source_iterator _Iter = _M_connectedSources.begin(); *_Iter != NULL; ++_Iter)
        {
             ISource<_Source_type> * _PSource = *_Iter;
             _PSource->unlink_target(this);
        }
    }

Member Data Documentation

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

_SourceLinkManager Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::_M_connectedSources

protected

The container for all the sources connected to this block.

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

volatile bool Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::_M_fDeclineMessages

protected

A bool that is set to indicate that all messages should be declined in preparation for deleting the block

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>

filter_method* Concurrency::propagator_block< _TargetLinkRegistry, _SourceLinkRegistry, _MessageProcessorType >::_M_pFilter

protected

The filter function which determines whether offered messages should be accepted.

---

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

• VS2015/inc/agents.h