choice Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
A choice messaging block is a multi-source, single-target block that represents a control-flow interaction with a set of sources. The choice block will wait for any one of multiple sources to produce a message and will propagate the index of the source that produced the message.
Syntax
template<
class T
>
class choice: public ISource<size_t>;
Parameters
T
A tuple-based type representing the payloads of the input sources.
Members
Public Typedefs
| Name | Description |
|---|---|
type |
A type alias for T. |
Public Constructors
| Name | Description |
|---|---|
| choice::choice Constructor | Overloaded. Constructs a choice messaging block. |
| choice::~choice Destructor | Destroys the choice messaging block. |
Public Methods
| Name | Description |
|---|---|
| choice::accept Method | Accepts a message that was offered by this choice block, transferring ownership to the caller. |
| choice::acquire_ref Method | Acquires a reference count on this choice messaging block, to prevent deletion. |
| choice::consume Method | Consumes a message previously offered by this choice messaging block and successfully reserved by the target, transferring ownership to the caller. |
| choice::has_value Method | Checks whether this choice messaging block has been initialized with a value yet. |
| choice::index Method | Returns an index into the tuple representing the element selected by the choice messaging block. |
| choice::link_target Method | Links a target block to this choice messaging block. |
| choice::release Method | Releases a previous successful message reservation. |
| choice::release_ref Method | Releases a reference count on this choice messaging block. |
| choice::reserve Method | Reserves a message previously offered by this choice messaging block. |
| choice::unlink_target Method | Unlinks a target block from this choice messaging block. |
| choice::unlink_targets Method | Unlinks all targets from this choice messaging block. (Overrides ISource::unlink_targets.) |
| choice::value Method | Gets the message whose index was selected by the choice messaging block. |
Remarks
The choice block ensures that only one of the incoming messages is consumed.
For more information, see Asynchronous Message Blocks.
Inheritance Hierarchy
choice
Requirements
Header: agents.h
Namespace: concurrency
choice::accept Method
Accepts a message that was offered by this choice block, transferring ownership to the caller.
virtual message<size_t>* accept(
runtime_object_identity _MsgId,
_Inout_ ITarget<size_t>* _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 that the caller now has ownership of.
choice::acquire_ref Method
Acquires a reference count on this choice messaging block, to prevent deletion.
virtual void acquire_ref(_Inout_ ITarget<size_t>* _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 linked to this source during the link_target method.
choice::choice Constructor
Constructs a choice messaging block.
explicit choice(
T _Tuple);
choice(
Scheduler& _PScheduler,
T _Tuple);
choice(
ScheduleGroup& _PScheduleGroup,
T _Tuple);
choice(
choice&& _Choice);
Parameters
_Tuple
A tuple of sources for the choice.
_PScheduler
The Scheduler object within which the propagation task for the choice messaging block is scheduled.
_PScheduleGroup
The ScheduleGroup object within which the propagation task for the choice messaging block is scheduled. The Scheduler object used is implied by the schedule group.
_Choice
A choice messaging block to copy from. Note that the original object is orphaned, making this a move constructor.
Remarks
The runtime uses the default scheduler if you do not specify the _PScheduler or _PScheduleGroup parameters.
Move construction is not performed under a lock, which means that it is up to the user to make sure that there are no light-weight tasks in flight at the time of moving. Otherwise, numerous races can occur, leading to exceptions or inconsistent state.
choice::~choice Destructor
Destroys the choice messaging block.
~choice();
choice::consume Method
Consumes a message previously offered by this choice messaging block and successfully reserved by the target, transferring ownership to the caller.
virtual message<size_t>* consume(
runtime_object_identity _MsgId,
_Inout_ ITarget<size_t>* _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 consume method is similar to accept, but must always be preceded by a call to reserve that returned true.
choice::has_value Method
Checks whether this choice messaging block has been initialized with a value yet.
bool has_value() const;
Return Value
true if the block has received a value, false otherwise.
choice::index Method
Returns an index into the tuple representing the element selected by the choice messaging block.
size_t index();
Return Value
The message index.
Remarks
The message payload can be extracted using the get method.
choice::link_target Method
Links a target block to this choice messaging block.
virtual void link_target(_Inout_ ITarget<size_t>* _PTarget);
Parameters
_PTarget
A pointer to an ITarget block to link to this choice messaging block.
choice::release Method
Releases a previous successful message reservation.
virtual void release(
runtime_object_identity _MsgId,
_Inout_ ITarget<size_t>* _PTarget);
Parameters
_MsgId
The runtime_object_identity of the message object being released.
_PTarget
A pointer to the target block that is calling the release method.
choice::release_ref Method
Releases a reference count on this choice messaging block.
virtual void release_ref(_Inout_ ITarget<size_t>* _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.
choice::reserve Method
Reserves a message previously offered by this choice messaging block.
virtual bool reserve(
runtime_object_identity _MsgId,
_Inout_ ITarget<size_t>* _PTarget);
Parameters
_MsgId
The runtime_object_identity of the message object being reserved.
_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.
choice::unlink_target Method
Unlinks a target block from this choice messaging block.
virtual void unlink_target(_Inout_ ITarget<size_t>* _PTarget);
Parameters
_PTarget
A pointer to an ITarget block to unlink from this choice messaging block.
choice::unlink_targets Method
Unlinks all targets from this choice messaging block.
virtual void unlink_targets();
Remarks
This method does not need to be called from the destructor because destructor for the internal single_assignment block will unlink properly.
choice::value Method
Gets the message whose index was selected by the choice messaging block.
template <
typename _Payload_type
>
_Payload_type const& value();
Parameters
_Payload_type
The type of the message payload.
Return Value
The payload of the message.
Remarks
Because a choice messaging block can take inputs with different payload types, you must specify the type of the payload at the point of retrieval. You can determine the type based on the result of the index method.