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
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();