choice 类
choice 消息块是多源、单目标的块，表示与一组源进行的控制流交互。 choice 块将等待多个源中的任何一个源以生成消息，并将传播生成该消息的源的索引。
语法
template<
class T
>
class choice: public ISource<size_t>;
参数
T
一种基于 tuple 的类型，表示输入源的有效负载。
成员
公共 Typedef
| 名称 | 描述 |
|---|---|
type |
T 的类型别名。 |
公共构造函数
| 名称 | 描述 |
|---|---|
| choice | 已重载。 构造 choice 消息块。 |
| ~choice 析构函数 | 销毁 choice 消息块。 |
公共方法
| 名称 | 描述 |
|---|---|
| accept | 接受此 choice 块提供的消息，将所有权转移给调用方。 |
| acquire_ref | 获取此 choice 消息块的引用计数，以防止删除。 |
| 使用 | 使用此 choice 消息块之前提供且由目标成功保留的消息，并将所有权转让给调用方。 |
| has_value | 检查是否已使用值初始化此 choice 消息块。 |
| 索引 | 返回表示 choice 消息块所选元素的 tuple 的索引。 |
| link_target | 将目标块链接到此 choice 消息块。 |
| release | 释放之前成功保留的消息。 |
| release_ref | 释放此 choice 消息块的引用计数。 |
| reserve | 保留此 choice 消息块之前提供的消息。 |
| unlink_target | 取消此 choice 消息块与目标块的链接。 |
| unlink_targets | 取消此 choice 消息块与所有目标的链接。 （重写 ISource::unlink_targets。） |
| value | 获取 choice 消息块选择其索引的消息。 |
备注
choice 块可确保只使用其中一条传入消息。
有关详细信息，请参阅异步消息块。
继承层次结构
choice
要求
标头： agents.h
命名空间： 并发
接受
接受此 choice 块提供的消息，将所有权转移给调用方。
virtual message<size_t>* accept(
runtime_object_identity _MsgId,
_Inout_ ITarget<size_t>* _PTarget);
参数
_MsgId
提供的 message 对象的 runtime_object_identity。
_PTarget
指向正在调用 accept 方法的目标块的指针。
返回值
指向调用方现在对其拥有所有权的消息的指针。
acquire_ref
获取此 choice 消息块的引用计数，以防止删除。
virtual void acquire_ref(_Inout_ ITarget<size_t>* _PTarget);
参数
_PTarget
指向正在调用此方法的目标块的指针。
注解
此方法由 ITarget 对象调用，该对象在使用 link_target 方法期间链接到此源。
选项
构造 choice 消息块。
explicit choice(
T _Tuple);
choice(
Scheduler& _PScheduler,
T _Tuple);
choice(
ScheduleGroup& _PScheduleGroup,
T _Tuple);
choice(
choice&& _Choice);
参数
_Tuple
choice 的源的 tuple 。
_PScheduler
在其中计划了 Scheduler 消息块的传播任务的 choice 对象。
_PScheduleGroup
在其中计划了 ScheduleGroup 消息块的传播任务的 choice 对象。 所用 Scheduler 对象由该计划组提示。
_Choice
要从中进行复制的 choice 消息块。 请注意原始对象是孤立的，使之成为一个移动构造函数。
备注
如果未指定 _PScheduler 或 _PScheduleGroup 函数，运行时将使用默认的计划程序。
在锁定状态下不执行移动构造，这意味着应由用户确保在移动期间没有轻量任务处于飞行状态。 否则可能会发生大量争用，从而导致异常或不一致的状态。
~choice
销毁 choice 消息块。
~choice();
使用
使用此 choice 消息块之前提供且由目标成功保留的消息，并将所有权转让给调用方。
virtual message<size_t>* consume(
runtime_object_identity _MsgId,
_Inout_ ITarget<size_t>* _PTarget);
参数
_MsgId
保留的 message 对象的 runtime_object_identity。
_PTarget
指向正在调用 consume 方法的目标块的指针。
返回值
指向调用方现在对其拥有所有权的 message 对象的指针。
备注
consume 方法类似于 accept，但必须始终在对 reserve 进行调用（返回 true）之前使用。
has_value
检查是否已使用值初始化此 choice 消息块。
bool has_value() const;
返回值
如果此块已接收一个值，则为 true；否则为 false。
索引
返回表示 choice 消息块所选元素的 tuple 的索引。
size_t index();
返回值
消息索引。
备注
可以使用 get 方法提取消息有效负载。
link_target
将目标块链接到此 choice 消息块。
virtual void link_target(_Inout_ ITarget<size_t>* _PTarget);
参数
_PTarget
指向要链接到此 choice 消息块的 ITarget 块的指针。
发布
释放之前成功保留的消息。
virtual void release(
runtime_object_identity _MsgId,
_Inout_ ITarget<size_t>* _PTarget);
参数
_MsgId
正在释放的 message 对象的 runtime_object_identity。
_PTarget
指向正在调用 release 方法的目标块的指针。
release_ref
释放此 choice 消息块的引用计数。
virtual void release_ref(_Inout_ ITarget<size_t>* _PTarget);
参数
_PTarget
指向正在调用此方法的目标块的指针。
备注
此方法由 ITarget 对象调用，正在取消该对象与此源的链接。 源块可以释放为目标块保留的任何资源。
reserve
保留此 choice 消息块之前提供的消息。
virtual bool reserve(
runtime_object_identity _MsgId,
_Inout_ ITarget<size_t>* _PTarget);
参数
_MsgId
正在保留的 message 对象的 runtime_object_identity。
_PTarget
指向正在调用 reserve 方法的目标块的指针。
返回值
如果已成功保留该消息，则为 true；否则，为 false。 预留可能因为众多原因失败，包括：消息已预留或已由另一目标接受，源可能拒绝预留等。
注解
调用 reserve 后，如果成功，则必须调用 consume 或 release，以便获取或放弃消息所有权。
unlink_target
取消此 choice 消息块与目标块的链接。
virtual void unlink_target(_Inout_ ITarget<size_t>* _PTarget);
参数
_PTarget
指向要取消与此 choice 消息块的链接的 ITarget 块的指针。
unlink_targets
取消此 choice 消息块与所有目标的链接。
virtual void unlink_targets();
备注
不需要从析构函数调用此方法，因为内部 single_assignment 块的析构函数将正确取消链接。
value
获取 choice 消息块选择其索引的消息。
template <
typename _Payload_type
>
_Payload_type const& value();
参数
_Payload_type
消息有效负载的类型。
返回值
消息的有效负载。
备注
因为 choice 消息块可以采用不同负载类型的输入，您必须指定检索时的负载类型。 可以根据 index 方法的结果确定类型。