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 块可确保只使用其中一条传入消息。

有关详细信息，请参阅异步消息块。

继承层次结构

ISource

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 方法提取消息有效负载。

将目标块链接到此 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，以便获取或放弃消息所有权。

取消此 choice 消息块与目标块的链接。

virtual void unlink_target(_Inout_ ITarget<size_t>* _PTarget);

参数

_PTarget
指向要取消与此 choice 消息块的链接的 ITarget 块的指针。

取消此 choice 消息块与所有目标的链接。

virtual void unlink_targets();

备注

不需要从析构函数调用此方法，因为内部 single_assignment 块的析构函数将正确取消链接。

value

获取 choice 消息块选择其索引的消息。

template <
    typename _Payload_type
>
_Payload_type const& value();

参数

_Payload_type
消息有效负载的类型。

返回值

消息的有效负载。

备注

因为 choice 消息块可以采用不同负载类型的输入，您必须指定检索时的负载类型。 可以根据 index 方法的结果确定类型。

另请参阅

并发命名空间
join 类
single_assignment 类