ISource Class

 

The ISource class is the interface for all source blocks. Source blocks propagate messages to ITarget blocks.

template<class T>
class ISource;

Parameters

T
The data type of the payload within the messages produced by the source block.

Public Typedefs

NameDescription
source_typeA type alias for T.

Public Constructors

NameDescription
ISource::~ISource DestructorDestroys the ISource object.

Public Methods

NameDescription
ISource::accept MethodWhen overridden in a derived class, accepts a message that was offered by this ISource block, transferring ownership to the caller.
ISource::acquire_ref MethodWhen overridden in a derived class, acquires a reference count on this ISource block, to prevent deletion.
ISource::consume MethodWhen 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.
ISource::link_target MethodWhen overridden in a derived class, links a target block to this ISource block.
ISource::release MethodWhen overridden in a derived class, releases a previous successful message reservation.
ISource::release_ref MethodWhen overridden in a derived class, releases a reference count on this ISource block.
ISource::reserve MethodWhen overridden in a derived class, reserves a message previously offered by this ISource block.
ISource::unlink_target MethodWhen overridden in a derived class, unlinks a target block from this ISource block, if found to be previously linked.
ISource::unlink_targets MethodWhen overridden in a derived class, unlinks all target blocks from this ISource block.

For more information, see Asynchronous Message Blocks.

ISource

Header: agents.h

Namespace: concurrency

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.

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.

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.

Destroys the ISource object.

virtual ~ISource();

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.

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.

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.

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.

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.

When overridden in a derived class, unlinks all target blocks from this ISource block.

virtual void unlink_targets() = 0;

concurrency Namespace
ITarget Class

Show: