ISource Class
The ISource class is the interface for all source blocks. Source blocks propagate messages to ITarget blocks.
Syntax
template<class T>
class ISource;
Parameters
T
The data type of the payload within the messages produced by the source block.
Members
Public Typedefs
| Name | Description |
|---|---|
source_type |
A type alias for T. |
Public Constructors
| Name | Description |
|---|---|
| ~ISource Destructor | Destroys the ISource object. |
Public Methods
| Name | Description |
|---|---|
| accept | When overridden in a derived class, accepts a message that was offered by this ISource block, transferring ownership to the caller. |
| acquire_ref | When overridden in a derived class, acquires a reference count on this ISource block, to prevent deletion. |
| consume | When overridden in a derived class, consumes a message previously offered by this ISource block and successfully reserved by the target, transferring ownership to the caller. |
| link_target | When overridden in a derived class, links a target block to this ISource block. |
| release | When overridden in a derived class, releases a previous successful message reservation. |
| release_ref | When overridden in a derived class, releases a reference count on this ISource block. |
| reserve | When overridden in a derived class, reserves a message previously offered by this ISource block. |
| unlink_target | When overridden in a derived class, unlinks a target block from this ISource block, if found to be previously linked. |
| unlink_targets | When overridden in a derived class, unlinks all target blocks from this ISource block. |
Remarks
For more information, see Asynchronous Message Blocks.
Inheritance Hierarchy
ISource
Requirements
Header: agents.h
Namespace: concurrency
accept
When overridden in a derived class, accepts a message that was offered by this ISource block, transferring ownership to the caller.
virtual message<T>* accept(
runtime_object_identity _MsgId,
_Inout_ ITarget<T>* _PTarget) = 0;
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 that the caller now has ownership of.
Remarks
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.
acquire_ref
When overridden in a derived class, acquires a reference count on this ISource block, to prevent deletion.
virtual void acquire_ref(_Inout_ ITarget<T>* _PTarget) = 0;
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 linked to this source during the link_target method.
consume
When overridden in a derived class, consumes a message previously offered by this ISource block and successfully reserved by the target, transferring ownership to the caller.
virtual message<T>* consume(
runtime_object_identity _MsgId,
_Inout_ ITarget<T>* _PTarget) = 0;
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 consume method is similar to accept, but must always be preceded by a call to reserve that returned true.
~ISource
Destroys the ISource object.
virtual ~ISource();
link_target
When overridden in a derived class, links a target block to this ISource block.
virtual void link_target(_Inout_ ITarget<T>* _PTarget) = 0;
Parameters
_PTarget
A pointer to the target block being linked to this ISource block.
release
When overridden in a derived class, releases a previous successful message reservation.
virtual void release(
runtime_object_identity _MsgId,
_Inout_ ITarget<T>* _PTarget) = 0;
Parameters
_MsgId
The runtime_object_identity of the reserved message object.
_PTarget
A pointer to the target block that is calling the release method.
release_ref
When overridden in a derived class, releases a reference count on this ISource block.
virtual void release_ref(_Inout_ ITarget<T>* _PTarget) = 0;
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.
reserve
When overridden in a derived class, reserves a message previously offered by this ISource block.
virtual bool reserve(
runtime_object_identity _MsgId,
_Inout_ ITarget<T>* _PTarget) = 0;
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
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.
unlink_target
When overridden in a derived class, unlinks a target block from this ISource block, if found to be previously linked.
virtual void unlink_target(_Inout_ ITarget<T>* _PTarget) = 0;
Parameters
_PTarget
A pointer to the target block being unlinked from this ISource block.
unlink_targets
When overridden in a derived class, unlinks all target blocks from this ISource block.
virtual void unlink_targets() = 0;