propagator_block Class

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	Constructs a propagator_block object.
~propagator_block Destructor	Destroys a propagator_block object.

Public Methods

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

decline_incoming_messages

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.

initialize_source_and_target

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.

link_source

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.

process_input_messages

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
A pointer to the message that is to be processed.

propagate

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.

propagate_message

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

Constructs a propagator_block object.

propagator_block();

~propagator_block

Destroys a propagator_block object.

virtual ~propagator_block();

register_filter

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

void register_filter(filter_method const& _Filter);

Parameters

_Filter
The filter method.

remove_network_links

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

void remove_network_links();

send

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.

send_message

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.

unlink_source

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.

unlink_sources

Unlinks all source blocks from this propagator_block object.

virtual void unlink_sources();

See also

concurrency Namespace
source_block Class
ITarget Class