source_block 类

  • 项目

source_block 是仅限于源的块的抽象基类。 该类提供基本链接管理功能和常见错误检查。

语法

template<class _TargetLinkRegistry, class _MessageProcessorType = ordered_message_processor<typename _TargetLinkRegistry::type::type>>
class source_block : public ISource<typename _TargetLinkRegistry::type::type>;

参数

_TargetLinkRegistry
用于保存目标链接的链接注册表。

_MessageProcessorType
用于消息处理的处理器类型。

成员

公共 Typedef

名称 描述
target_iterator 用于遍历连接目标的迭代器。

公共构造函数

名称 描述
source_block 构造 source_block 对象。
~source_block 析构函数 销毁 source_block 对象。

公共方法

名称 描述
accept 接受此 source_block 对象提供的消息，将所有权转让给调用方。
acquire_ref 获取此 source_block 对象的引用计数，以防止删除。
使用 使用此 source_block 对象之前提供且由目标成功保留的消息，并将所有权转让给调用方。
link_target 将目标块链接到此 source_block 对象。
release 释放之前成功保留的消息。
release_ref 释放此 source_block 对象上的引用计数。
reserve 保留 source_block 对象之前提供的消息。
unlink_target 取消链接此 source_block 对象的某个目标块。
unlink_targets 取消链接此 source_block 对象的所有目标块。 （重写 ISource::unlink_targets。）

受保护方法

名称 描述
accept_message 在派生类中重写时，接受源提供的消息。 消息块应重写此方法以验证 _MsgId 并返回消息。
async_send 异步排队消息并启动传播任务（如果尚未完成）
consume_message 在派生类中重写时，使用之前保留的消息。
enable_batched_processing 启用该块的批处理。
initialize_source 初始化此 source_block 中的 message_propagator。
link_target_notification 通知新目标已链接到此 source_block 对象的回调。
process_input_messages 处理输入消息。 这只适用于从源块派生的传播器块。
propagate_output_messages 将消息传播到目标。
propagate_to_any_targets 在派生类中重写时，将给定消息传播到任何或所有链接目标。 这是消息块的主要传播例程。
release_message 在派生类中重写时，释放之前保留的消息。
remove_targets 删除此源块的所有目标链接。 这应该从析构函数调用。
reserve_message 在派生类中重写时，保留此 source_block 对象先前提供的消息。
resume_propagation 在派生类中重写时，在释放保留的消息后恢复传播。
sync_send 同步排队消息并启动传播任务（如果尚未完成）。
unlink_target_notification 通知已从此 source_block 对象取消链接目标的回调。
wait_for_outstanding_async_sends 等待所有异步传播完成。 这个特定于传播器的自旋等待用于在消息块的析构函数中确保销毁块之前有时间完成所有异步传播。

备注

消息块应派生自此块，以利用这个类提供的链接管理和同步。

继承层次结构

ISource

source_block

要求

标头： agents.h

命名空间： 并发

接受

接受此 source_block 对象提供的消息，将所有权转让给调用方。

virtual message<_Target_type>* accept(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<_Target_type>* _PTarget);

参数

_MsgId
提供的 message 对象的 runtime_object_identity。

_PTarget
指向正在调用 accept 方法的目标块的指针。

返回值

指向调用方现在对其拥有所有权的 message 对象的指针。

注解

如果参数 _PTarget 为 NULL，则该方法将引发 invalid_argument 异常。

当消息由此 ISource 块提供时，目标调用 accept 方法。 如果此源决定复制消息，则返回的消息指针可能与传递给 ITarget 块的 propagate 方法的指针不同。

accept_message

在派生类中重写时，接受源提供的消息。 消息块应重写此方法以验证 _MsgId 并返回消息。

virtual message<_Target_type>* accept_message(runtime_object_identity _MsgId) = 0;

参数

_MsgId
message 对象的运行时对象标识。

返回值

指向调用方现在对其拥有所有权的消息的指针。

备注

若要转让所有权，应返回原始消息指针。 若要保持所有权，则需要创建并返回消息有效负载副本。

acquire_ref

获取此 source_block 对象的引用计数，以防止删除。

virtual void acquire_ref(_Inout_ ITarget<_Target_type> *);

注解

此方法由 ITarget 对象调用，该对象在使用 link_target 方法期间链接到此源。

async_send

异步排队消息并启动传播任务（如果尚未完成）

virtual void async_send(_Inout_opt_ message<_Target_type>* _Msg);

参数

_Msg
指向要异步发送的 message 对象的指针。

使用

使用此 source_block 对象之前提供且由目标成功保留的消息，并将所有权转让给调用方。

virtual message<_Target_type>* consume(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<_Target_type>* _PTarget);

参数

_MsgId
保留的 message 对象的 runtime_object_identity。

_PTarget
指向正在调用 consume 方法的目标块的指针。

返回值

指向调用方现在对其拥有所有权的 message 对象的指针。

注解

如果参数 _PTarget 为 NULL，则该方法将引发 invalid_argument 异常。

如果参数 _PTarget 不表示调用 reserve 的目标，该方法将引发 bad_target 异常。

consume 方法类似于 accept，但必须始终在对 reserve 进行调用（返回 true）之前使用。

consume_message

在派生类中重写时，使用之前保留的消息。

virtual message<_Target_type>* consume_message(runtime_object_identity _MsgId) = 0;

参数

_MsgId
正在使用的 message 对象的 runtime_object_identity。

返回值

指向调用方现在对其拥有所有权的消息的指针。

备注

类似于 accept，但始终在对 reserve 的调用之前。

enable_batched_processing

启用该块的批处理。

void enable_batched_processing();

initialize_source

初始化此 source_block 中的 message_propagator。

void initialize_source(
    _Inout_opt_ Scheduler* _PScheduler = NULL,
    _Inout_opt_ ScheduleGroup* _PScheduleGroup = NULL);

参数

_PScheduler
用于计划任务的计划程序。

_PScheduleGroup
用于计划任务的计划组。

将目标块链接到此 source_block 对象。

virtual void link_target(_Inout_ ITarget<_Target_type>* _PTarget);

参数

_PTarget
指向要链接到此 source_block 对象的 ITarget 块的指针。

备注

如果参数 _PTarget 为 NULL，则该方法将引发 invalid_argument 异常。

通知新目标已链接到此 source_block 对象的回调。

virtual void link_target_notification(_Inout_ ITarget<_Target_type> *);

process_input_messages

处理输入消息。 这只适用于从源块派生的传播器块。

virtual void process_input_messages(_Inout_ message<_Target_type>* _PMessage);

参数

_PMessage
指向要处理的消息的指针。

propagate_output_messages

将消息传播到目标。

virtual void propagate_output_messages();

propagate_to_any_targets

在派生类中重写时，将给定消息传播到任何或所有链接目标。 这是消息块的主要传播例程。

virtual void propagate_to_any_targets(_Inout_opt_ message<_Target_type>* _PMessage);

参数

_PMessage
指向要传播的消息的指针。

发布

释放之前成功保留的消息。

virtual void release(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<_Target_type>* _PTarget);

参数

_MsgId
保留的 message 对象的 runtime_object_identity。

_PTarget
指向正在调用 release 方法的目标块的指针。

注解

如果参数 _PTarget 为 NULL，则该方法将引发 invalid_argument 异常。

如果参数 _PTarget 不表示调用 reserve 的目标，该方法将引发 bad_target 异常。

release_message

在派生类中重写时，释放之前保留的消息。

virtual void release_message(runtime_object_identity _MsgId) = 0;

参数

_MsgId
正在释放的 message 对象的 runtime_object_identity。

release_ref

释放此 source_block 对象上的引用计数。

virtual void release_ref(_Inout_ ITarget<_Target_type>* _PTarget);

参数

_PTarget
指向正在调用此方法的目标块的指针。

备注

此方法由 ITarget 对象调用，正在取消该对象与此源的链接。 源块可以释放为目标块保留的任何资源。

remove_targets

删除此源块的所有目标链接。 这应该从析构函数调用。

void remove_targets();

reserve

保留 source_block 对象之前提供的消息。

virtual bool reserve(
    runtime_object_identity _MsgId,
    _Inout_ ITarget<_Target_type>* _PTarget);

参数

_MsgId
提供的 message 对象的 runtime_object_identity。

_PTarget
指向正在调用 reserve 方法的目标块的指针。

返回值

如果已成功保留该消息，则为 true；否则，为 false。 预留可能因为众多原因失败，包括：消息已预留或已由另一目标接受，源可能拒绝预留等。

注解

如果参数 _PTarget 为 NULL，则该方法将引发 invalid_argument 异常。

调用 reserve 后，如果成功，则必须调用 consume 或 release，以便获取或放弃消息所有权。

reserve_message

在派生类中重写时，保留此 source_block 对象先前提供的消息。

virtual bool reserve_message(runtime_object_identity _MsgId) = 0;

参数

_MsgId
正在保留的 message 对象的 runtime_object_identity。

返回值

如果已成功保留该消息，则为 true；否则，为 false。

备注

调用 reserve 后，如果返回 true，则必须调用 consume 或 release 来获取或释放消息的所有权。

resume_propagation

在派生类中重写时，在释放保留的消息后恢复传播。

virtual void resume_propagation() = 0;

source_block

构造 source_block 对象。

source_block();

~source_block

销毁 source_block 对象。

virtual ~source_block();

sync_send

同步排队消息并启动传播任务（如果尚未完成）。

virtual void sync_send(_Inout_opt_ message<_Target_type>* _Msg);

参数

_Msg
指向要同步发送的 message 对象的指针。

取消链接此 source_block 对象的某个目标块。

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

参数

_PTarget
指向要取消与此 source_block 对象的链接的 ITarget 块的指针。

注解

如果参数 _PTarget 为 NULL，则该方法将引发 invalid_argument 异常。

通知已从此 source_block 对象取消链接目标的回调。

virtual void unlink_target_notification(_Inout_ ITarget<_Target_type>* _PTarget);

参数

_PTarget
已取消链接的 ITarget 块。

取消链接此 source_block 对象的所有目标块。

virtual void unlink_targets();

wait_for_outstanding_async_sends

等待所有异步传播完成。 这个特定于传播器的自旋等待用于在消息块的析构函数中确保销毁块之前有时间完成所有异步传播。

void wait_for_outstanding_async_sends();

另请参阅

并发命名空间
ISource 类