source_block Class

The source_block class is an abstract base class for source-only blocks. The class provides basic link management functionality as well as common error checks.

Syntax

template<class _TargetLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>
class source_block : public ISource<typename _TargetLinkRegistry::type::type>;

Parameters

_TargetLinkRegistry
Link registry to be used for holding the target links.

_MessageProcessorType
Processor type for message processing.

Members

Public Typedefs

Name	Description
target_iterator	The iterator to walk the connected targets.

Public Constructors

Name	Description
source_block	Constructs a source_block object.
~source_block Destructor	Destroys the source_block object.

Public Methods

Name	Description
accept	Accepts a message that was offered by this source_block object, transferring ownership to the caller.
acquire_ref	Acquires a reference count on this source_block object, to prevent deletion.
consume	Consumes a message previously offered by this source_block object and successfully reserved by the target, transferring ownership to the caller.
link_target	Links a target block to this source_block object.
release	Releases a previous successful message reservation.
release_ref	Releases a reference count on this source_block object.
reserve	Reserves a message previously offered by this source_block object.
unlink_target	Unlinks a target block from this source_block object.
unlink_targets	Unlinks all target blocks from this source_block object. (Overrides ISource::unlink_targets.)

Protected Methods

Name	Description
accept_message	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.
async_send	Asynchronously queues up messages and starts a propagation task, if this has not been done already
consume_message	When overridden in a derived class, consumes a message that was previously reserved.
enable_batched_processing	Enables batched processing for this block.
initialize_source	Initializes the message_propagator within this source_block.
link_target_notification	A callback that notifies that a new target has been linked to this source_block object.
process_input_messages	Process input messages. This is only useful for propagator blocks, which derive from source_block
propagate_output_messages	Propagate messages to targets.
propagate_to_any_targets	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.
release_message	When overridden in a derived class, releases a previous message reservation.
remove_targets	Removes all target links for this source block. This should be called from the destructor.
reserve_message	When overridden in a derived class, reserves a message previously offered by this source_block object.
resume_propagation	When overridden in a derived class, resumes propagation after a reservation has been released.
sync_send	Synchronously queues up messages and starts a propagation task, if this has not been done already.
unlink_target_notification	A callback that notifies that a target has been unlinked from this source_block object.
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.

Remarks

Message blocks should derive from this block to take advantage of link management and synchronization provided by this class.

Inheritance Hierarchy

ISource

source_block

Requirements

Header: agents.h

Namespace: concurrency

accept

Accepts a message that was offered by this source_block object, transferring ownership to the caller.

virtual message<_Target_type>* accept(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<_Target_type>* _PTarget);

Parameters

_MsgId
The runtime_object_identity of the offered message object.

_PTarget
A pointer to the target block that is calling the accept method.

Return Value

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

Remarks

The method throws an invalid_argument exception if the parameter _PTarget is NULL.

The accept method is called by a target while a message is being offered by this ISource block. The message pointer returned may be different from the one passed into the propagate method of the ITarget block, if this source decides to make a copy of the message.

accept_message

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.

virtual message<_Target_type>* accept_message(runtime_object_identity _MsgId) = 0;

Parameters

_MsgId
The runtime object identity of the message object.

Return Value

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

Remarks

To transfer ownership, the original message pointer should be returned. To maintain ownership, a copy of message payload needs to be made and returned.

acquire_ref

Acquires a reference count on this source_block object, to prevent deletion.

virtual void acquire_ref(_Inout_ ITarget<_Target_type> *);

Remarks

This method is called by an ITarget object that is being linked to this source during the link_target method.

async_send

Asynchronously queues up messages and starts a propagation task, if this has not been done already

virtual void async_send(_Inout_opt_ message<_Target_type>* _Msg);

Parameters

_Msg
A pointer to a message object to asynchronously send.

consume

Consumes a message previously offered by this source_block object and successfully reserved by the target, transferring ownership to the caller.

virtual message<_Target_type>* consume(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<_Target_type>* _PTarget);

Parameters

_MsgId
The runtime_object_identity of the reserved message object.

_PTarget
A pointer to the target block that is calling the consume method.

Return Value

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

Remarks

The method throws an invalid_argument exception if the parameter _PTarget is NULL.

The method throws a bad_target exception if the parameter _PTarget does not represent the target that called reserve.

The consume method is similar to accept, but must always be preceded by a call to reserve that returned true.

consume_message

When overridden in a derived class, consumes a message that was previously reserved.

virtual message<_Target_type>* consume_message(runtime_object_identity _MsgId) = 0;

Parameters

_MsgId
The runtime_object_identity of the message object being consumed.

Return Value

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

Remarks

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

enable_batched_processing

Enables batched processing for this block.

void enable_batched_processing();

initialize_source

Initializes the message_propagator within this source_block.

void initialize_source(
    _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_target

Links a target block to this source_block object.

virtual void link_target(_Inout_ ITarget<_Target_type>* _PTarget);

Parameters

_PTarget
A pointer to an ITarget block to link to this source_block object.

Remarks

The method throws an invalid_argument exception if the parameter _PTarget is NULL.

link_target_notification

A callback that notifies that a new target has been linked to this source_block object.

virtual void link_target_notification(_Inout_ ITarget<_Target_type> *);

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_output_messages

Propagate messages to targets.

virtual void propagate_output_messages();

propagate_to_any_targets

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.

virtual void propagate_to_any_targets(_Inout_opt_ message<_Target_type>* _PMessage);

Parameters

_PMessage
A pointer to the message that is to be propagated.

release

Releases a previous successful message reservation.

virtual void release(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<_Target_type>* _PTarget);

Parameters

_MsgId
The runtime_object_identity of the reserved message object.

_PTarget
A pointer to the target block that is calling the release method.

Remarks

The method throws an invalid_argument exception if the parameter _PTarget is NULL.

The method throws a bad_target exception if the parameter _PTarget does not represent the target that called reserve.

release_message

When overridden in a derived class, releases a previous message reservation.

virtual void release_message(runtime_object_identity _MsgId) = 0;

Parameters

_MsgId
The runtime_object_identity of the message object being released.

release_ref

Releases a reference count on this source_block object.

virtual void release_ref(_Inout_ ITarget<_Target_type>* _PTarget);

Parameters

_PTarget
A pointer to the target block that is calling this method.

Remarks

This method is called by an ITarget object that is being unlinked from this source. The source block is allowed to release any resources reserved for the target block.

remove_targets

Removes all target links for this source block. This should be called from the destructor.

void remove_targets();

reserve

Reserves a message previously offered by this source_block object.

virtual bool reserve(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<_Target_type>* _PTarget);

Parameters

_MsgId
The runtime_object_identity of the offered message object.

_PTarget
A pointer to the target block that is calling the reserve method.

Return Value

true if the message was successfully reserved, false otherwise. Reservations can fail for many reasons, including: the message was already reserved or accepted by another target, the source could deny reservations, and so forth.

Remarks

The method throws an invalid_argument exception if the parameter _PTarget is NULL.

After you call reserve, if it succeeds, you must call either consume or release in order to take or give up possession of the message, respectively.

reserve_message

When overridden in a derived class, reserves a message previously offered by this source_block object.

virtual bool reserve_message(runtime_object_identity _MsgId) = 0;

Parameters

_MsgId
The runtime_object_identity of the message object being reserved.

Return Value

true if the message was successfully reserved, false otherwise.

Remarks

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

resume_propagation

When overridden in a derived class, resumes propagation after a reservation has been released.

virtual void resume_propagation() = 0;

source_block

Constructs a source_block object.

source_block();

~source_block

Destroys the source_block object.

virtual ~source_block();

sync_send

Synchronously queues up messages and starts a propagation task, if this has not been done already.

virtual void sync_send(_Inout_opt_ message<_Target_type>* _Msg);

Parameters

_Msg
A pointer to a message object to synchronously send.

unlink_target

Unlinks a target block from this source_block object.

virtual void unlink_target(_Inout_ ITarget<_Target_type>* _PTarget);

Parameters

_PTarget
A pointer to an ITarget block to unlink from this source_block object.

Remarks

The method throws an invalid_argument exception if the parameter _PTarget is NULL.

unlink_target_notification

A callback that notifies that a target has been unlinked from this source_block object.

virtual void unlink_target_notification(_Inout_ ITarget<_Target_type>* _PTarget);

Parameters

_PTarget
The ITarget block that was unlinked.

unlink_targets

Unlinks all target blocks from this source_block object.

virtual void unlink_targets();

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.

void wait_for_outstanding_async_sends();

See also

concurrency Namespace
ISource Class