propagator_block Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

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.

Syntax

template<class _TargetLinkRegistry, class _SourceLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>
class propagator_block : public source_block<_TargetLinkRegistry,
    _MessageProcessorType>,
 public ITarget<typename _SourceLinkRegistry::type::source_type>;

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.

Members

Public Typedefs

Name	Description
source_iterator	The type of the iterator for the source_link_manager for this propagator_block.

Public Constructors

Name	Description
propagator_block::propagator_block Constructor	Constructs a propagator_block object.
propagator_block::~propagator_block Destructor	Destroys a propagator_block object.

Public Methods

Name	Description
propagator_block::propagate Method	Asynchronously passes a message from a source block to this target block.
propagator_block::send Method	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.

Protected Methods

Name	Description
propagator_block::decline_incoming_messages Method	Indicates to the block that new messages should be declined.
propagator_block::initialize_source_and_target Method	Initializes the base object. Specifically, the message_processor object needs to be initialized.
propagator_block::link_source Method	Links a specified source block to this propagator_block object.
propagator_block::process_input_messages Method	Process input messages. This is only useful for propagator blocks, which derive from source_block (Overrides source_block::process_input_messages.)
propagator_block::propagate_message Method	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.
propagator_block::register_filter Method	Registers a filter method that will be invoked on every received message.
propagator_block::remove_network_links Method	Removes all the source and target network links from this propagator_block object.
propagator_block::send_message Method	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.
propagator_block::unlink_source Method	Unlinks a specified source block from this propagator_block object.
propagator_block::unlink_sources Method	Unlinks all source blocks from this propagator_block object. (Overrides ITarget::unlink_sources.)

Remarks

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.

Inheritance Hierarchy

ISource

ITarget

source_block

propagator_block

Requirements

Header: agents.h

Namespace: concurrency

propagator_block::decline_incoming_messages Method

Indicates to the block that new messages should be declined.

void decline_incoming_messages();

Remarks

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

propagator_block::initialize_source_and_target Method

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

void initialize_source_and_target(
    _Inout_opt_ Scheduler* _PScheduler = NULL,
    _Inout_opt_ ScheduleGroup* _PScheduleGroup = NULL);

Parameters

_PScheduler
The scheduler to be used for scheduling tasks.

_PScheduleGroup
The schedule group to be used for scheduling tasks.

propagator_block::link_source Method

Links a specified source block to this propagator_block object.

virtual void link_source(_Inout_ ISource<_Source_type>* _PSource);

Parameters

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

propagator_block::process_input_messages Method

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

virtual void process_input_messages(_Inout_ message<_Target_type>* _PMessage);

Parameters

_PMessage

propagator_block::propagate Method

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

virtual message_status propagate(
    _Inout_opt_ message<_Source_type>* _PMessage,
    _Inout_opt_ ISource<_Source_type>* _PSource);

Parameters

_PMessage
A pointer to the message object.

_PSource
A pointer to the source block offering the message.

Return Value

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

Remarks

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.

propagator_block::propagate_message Method

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.

virtual message_status propagate_message(
    _Inout_ message<_Source_type>* _PMessage,
    _Inout_ ISource<_Source_type>* _PSource) = 0;

Parameters

_PMessage
A pointer to the message object.

_PSource
A pointer to the source block offering the message.

Return Value

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

propagator_block::propagator_block Constructor

Constructs a propagator_block object.

propagator_block();

propagator_block::~propagator_block Destructor

Destroys a propagator_block object.

virtual ~propagator_block();

propagator_block::register_filter Method

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

void register_filter(filter_method const& _Filter);

Parameters

_Filter
The filter method.

propagator_block::remove_network_links Method

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

void remove_network_links();

propagator_block::send Method

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.

virtual message_status send(
    _Inout_ message<_Source_type>* _PMessage,
    _Inout_ ISource<_Source_type>* _PSource);

Parameters

_PMessage
A pointer to the message object.

_PSource
A pointer to the source block offering the message.

Return Value

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

Remarks

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

propagator_block::send_message Method

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.

virtual message_status send_message(
    _Inout_ message<_Source_type> *,
    _Inout_ ISource<_Source_type> *);

Return Value

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

Remarks

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

propagator_block::unlink_source Method

Unlinks a specified source block from this propagator_block object.

virtual void unlink_source(_Inout_ ISource<_Source_type>* _PSource);

Parameters

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

propagator_block::unlink_sources Method

Unlinks all source blocks from this propagator_block object.

virtual void unlink_sources();

See Also

concurrency Namespace
source_block Class
ITarget Class