Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType > Class Template Reference

The target_block class is an abstract base class that provides basic link management functionality and error checking for target only blocks. More...

#include <agents.h>

Inheritance diagram for Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >:

Public Types
typedef _SourceLinkRegistry::type::source_type	_Source_type
	The type of the payload for the incoming messages to this target_block object. More...
typedef source_link_manager< _SourceLinkRegistry >	_SourceLinkManager
	The type of the source_link_manager this target_block object. More...
typedef _SourceLinkManager::iterator	source_iterator
	The type of the iterator for the source_link_manager for this target_block object. 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
	target_block ()
	Constructs a target_block object. More...
virtual	~target_block ()
	Destroys the target_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 passes a message from a source block to this target block. 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 target_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 target_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 target_block object. More...
virtual void	unlink_source (_Inout_ ISource< _Source_type > *_PSource)
	Unlinks a specified source block from this target_block object. More...
virtual void	unlink_sources ()
	Unlinks all source blocks from this target_block object. More...
virtual void	process_message (message< _Source_type > *)
	When overridden in a derived class, processes a message that was accepted by this target_block object. More...
void	register_filter (filter_method const &_Filter)
	Registers a filter method that will be invoked on every message received. More...
void	decline_incoming_messages ()
	Indicates to the block that new messages should be declined. More...
void	initialize_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	enable_batched_processing ()
	Enables batched processing for this block. More...
void	async_send (_Inout_opt_ message< _Source_type > *_PMessage)
	Asynchronously sends a message for processing. More...
void	sync_send (_Inout_opt_ message< _Source_type > *_PMessage)
	Synchronously send a message for processing. More...
void	wait_for_async_sends ()
	Waits for all asynchronous propagations to complete. More...
void	remove_sources ()
	Unlinks all sources after waiting for outstanding asynchronous send operations to complete. More...
virtual void	process_input_messages (_Inout_ message< _Source_type > *)
	Processes messages that are received as inputs. 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...
bool	_M_fDeclineMessages
	A bool that is set to indicate that all messages should be declined in preparation for deleting the block More...
_MessageProcessorType	_M_messageProcessor
	The message_processor for this target_block. More...

Detailed Description

template<class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>
class Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >

The target_block class is an abstract base class that provides basic link management functionality and error checking for target only blocks.

Template Parameters

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

See also

ITarget Class

Member Typedef Documentation

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

typedef _SourceLinkRegistry::type::source_type Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::_Source_type

The type of the payload for the incoming messages to this target_block object.

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

typedef source_link_manager<_SourceLinkRegistry> Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::_SourceLinkManager

The type of the source_link_manager this target_block object.

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

typedef _SourceLinkManager::iterator Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::source_iterator

The type of the iterator for the source_link_manager for this target_block object.

Constructor & Destructor Documentation

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

Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::target_block ( )

inline

Constructs a target_block object.

                   : _M_pFilter(NULL), _M_fDeclineMessages(false)
    {
        _Trace_agents(AGENTS_EVENT_CREATE,
            ::Concurrency::details::_Trace_agents_get_id(this),
            ::Concurrency::details::_Trace_agents_get_id(&_M_messageProcessor));
    }

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

virtual Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::~target_block ( )

inlinevirtual

Destroys the target_block object.

    {
        // All sources should have been unlinked
        _CONCRT_ASSERT(_M_connectedSources.count() == 0);
        delete _M_pFilter;

        _Trace_agents(AGENTS_EVENT_DESTROY, ::Concurrency::details::_Trace_agents_get_id(this));
    }

Member Function Documentation

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

void Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::async_send ( _Inout_opt_ message< _Source_type > *  _PMessage )

inlineprotected

Asynchronously sends a message for processing.

Parameters

_PMessage

A pointer to the message being sent.

    {
        _M_messageProcessor.async_send(_PMessage);
    }

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

void Concurrency::target_block< _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 _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>

void Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::enable_batched_processing ( )

inlineprotected

Enables batched processing for this block.

    {
        _M_messageProcessor.initialize_batched_processing(
            // Processing function used by CRT110
            [this](message<_Source_type> * _PMessage)
            {
                // Handle message through new process_input_message to use CRT110 batch processing
                this->process_input_messages(_PMessage);
            }, nullptr);
    }

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

void Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::initialize_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

    {
        // Register a callback with the processor
        _M_messageProcessor.initialize(_PScheduler, _PScheduleGroup,
            // Processing and Propagating function used by ordered_message_processors
            [this](message<_Source_type> * _PMessage)
            {
                // Handle message by calling process_message to maintain CRT100 compatibility
                this->process_message(_PMessage);
            });

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

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

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

inlineprotectedvirtual

Links a specified source block to this target_block object.

Parameters

_PSource

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

This function should not be called directly on a target_block object. Blocks should be connected together using the link_target method on ISource blocks, which will invoke the link_source method on the corresponding target.

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 _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>

virtual void Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::process_input_messages ( _Inout_ message< _Source_type > *  )

inlineprotectedvirtual

Processes messages that are received as inputs.

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

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

virtual void Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::process_message ( message< _Source_type > *  )

inlineprotectedvirtual

When overridden in a derived class, processes a message that was accepted by this target_block object.

Parameters

_PMessage

A pointer to the message that is to be handled.

    {
    }

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

virtual message_status Concurrency::target_block< _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 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 _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>

virtual message_status Concurrency::target_block< _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 target_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 _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>

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

inlineprotected

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

Parameters

_Filter

The filter method.

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

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

void Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::remove_sources ( )

inlineprotected

Unlinks all sources after waiting for outstanding asynchronous send operations to complete.

All target blocks should call this routine to remove the sources in their destructor.

    {
        wait_for_async_sends();

        unlink_sources();
    }

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

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

inlinevirtual

Synchronously 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 method throws an invalid_argument exception if either the _PMessage or _PSource parameter is NULL.

Using the send method outside of message initiation and to propagate messages within a network is dangerous and can lead to deadlock.

When send returns, the message has either already been accepted, and transferred into the target block, or it has been declined by the target.

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 _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>

virtual message_status Concurrency::target_block< _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 target_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 _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>

void Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::sync_send ( _Inout_opt_ message< _Source_type > *  _PMessage )

inlineprotected

Synchronously send a message for processing.

Parameters

_PMessage

A pointer to the message being sent.

    {
        _M_messageProcessor.sync_send(_PMessage);
    }

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

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

inlineprotectedvirtual

Unlinks a specified source block from this target_block object.

Parameters

_PSource

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

This function should not be called directly on n target_block object. Blocks should be disconnected using the unlink_target or unlink_targets methods on ISource blocks, which will invoke the unlink_source method on the corresponding target.

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 _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>

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

inlineprotectedvirtual

Unlinks all source blocks from this target_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);
        }
    }

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

void Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::wait_for_async_sends ( )

inlineprotected

Waits for all asynchronous propagations to complete.

This method is used by message block destructors to ensure all asynchronous operations have had time to finish before destroying the block.

    {
        // Decline new messages to ensure that messages are not dropped during the wait
        decline_incoming_messages();

        _M_messageProcessor.wait();
    }

Member Data Documentation

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

_SourceLinkManager Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::_M_connectedSources

protected

The container for all the sources connected to this block.

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

bool Concurrency::target_block< _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 _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _SourceLinkRegistry::type::source_type>>

_MessageProcessorType Concurrency::target_block< _SourceLinkRegistry, _MessageProcessorType >::_M_messageProcessor

protected

The message_processor for this target_block.

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

filter_method* Concurrency::target_block< _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:

• VS2017/inc/agents.h