Rust API

​

模块

1. monad-event-ring - 此包提供核心 event ring 功能。回忆一下，event ring 是基于共享内存通信的通用广播工具，与其包含的事件数据类型无关。因此，此包_不_包含执行事件类型（或任何其他事件类型）的定义
2. monad-exec-events - 执行事件数据类型在此库中定义，还有一些用于编写实时数据应用的实用工具

struct EventRing<D: EventDecoder>

​

核心概念

​

事件枚举类型

const void *payload = monad_event_ring_payload_peek(&exec_ring, &event);

switch (event.event_type) {
case BLOCK_START:
    handle_block_start((const struct monad_exec_block_start *)payload);
    break;

case BLOCK_END:
    handle_block_end((const struct monad_exec_block_end *)payload);
    break;

// ... more event types handled here
}

#[derive(Clone, Debug)]
pub enum ExecEvent {
    BlockStart(monad_exec_block_start),
    BlockReject(monad_exec_block_reject),
    BlockEnd(monad_exec_block_end),
    // more variants follow

​

event ring 和 'ring 引用生命周期

​

零拷贝 API 和”事件引用”枚举类型

#[derive(Clone, Debug)]
pub enum ExecEvent {
    BlockStart(monad_exec_block_start),
    BlockReject(monad_exec_block_reject),
    BlockEnd(monad_exec_block_end),
    // more variants follow

#[derive(Clone, Debug)]
pub enum ExecEventRef<'ring> {
    BlockStart(&'ring monad_exec_block_start),
    BlockReject(&'ring monad_exec_block_reject),
    BlockEnd(&'ring monad_exec_block_end),
    // more variants follow

1. 因为它有引用生命周期作为泛型参数，可能更难使用（即更多地违反借用检查器）
2. 直接存在于负载缓冲区中的数据可能随时被覆盖，因此您不应依赖它在您首次查看后长时间仍然存在

​

拷贝与零拷贝负载 API

1. 拷贝风格 EventDescriptor::try_read - 这将返回 EventPayloadResult 枚举类型，它包含”成功”变体（EventPayloadResult::Ready）或”失败”变体（EventPayloadResult::Expired）；前者包含 ExecEvent 负载值，后者表明负载已丢失
2. 零拷贝风格 EventDescriptor::try_filter_map - 您向此方法传递一个非捕获闭包，它以指向共享内存中事件负载的 ExecEventRef<'ring> 引用被回调；由于您的闭包不能捕获任何东西，您对事件负载做出反应的唯一方式是返回类型 T 的某个值 v；EventDescriptor::try_filter_map 本身返回 Option<T>，按以下方式使用：
   • 如果在调用您的闭包之前负载已过期，则从不调用您的闭包，try_filter_map 返回 Option::None
   • 否则运行您的闭包，其返回值 v: T 被移动到 try_filter_map 函数中
   • 如果您的闭包运行后负载仍有效，则通过返回 Option::Some(v) 将值传递给调用者，否则返回 Option::None

​

为什么使用非捕获闭包？

• 创建对 event ring 负载缓冲区中数据的引用（e: &'ring E）并检查是否过期；如果未过期…
• … 基于事件负载值计算一些东西，即计算 let v = f(&e)
• 一旦 f 完成，再次检查负载是否过期；如果_现在_已过期，那么它_可能_在计算 v = f(&e) 期间的某个时刻过期；我们唯一能做的安全事情是丢弃计算的值 v，因为我们无法知道过期究竟何时发生

​

Rust API 中的重要类型

1. event ring EventRing<D: EventDecoder> - 给定 event ring 文件的路径，您创建其中一个以获取对该文件中 event ring 共享内存段的访问；您通常使用类型别名 ExecEventRing，它是 EventRing<ExecEventDecoder> 的语法糖
2. 事件读取器 EventReader<'ring, D: EventDecoder> - 这是类似迭代器的类型，用于读取事件；它称为”读取器”而非”迭代器”是因为 Iterator 在 Rust 中已有特定含义；事件读取器有比 Rust 迭代器更复杂的返回类型，因为它具有”轮询”风格：其 next() 的等价物 —— 称为 next_descriptor() —— 可以返回事件描述符、报告 gap 或指示尚无新事件就绪
3. 事件描述符 EventDescriptor<'ring, D: EventDecoder> - 如果下一个事件成功读取，事件读取器产生其中一个；回忆一下，事件描述符包含事件的通用字段，并存储读取事件负载和检查是否过期所需的数据；在 Rust API 中，读取负载是通过在事件描述符上定义的方法完成的
4. 事件解码器 trait EventDecoder - 您不会直接使用它，但实现此特征的类型 —— 在执行 event ring 情况下为 ExecEventDecoder —— 包含如何解码事件负载的所有逻辑
5. 事件枚举类型（关联类型 EventDecoder::Event 和 EventDecoder::EventRef）- 这些提供事件的”拷贝”和”零拷贝”解码形式；在 ExecEventDecoder 情况下，ExecEvent 是”拷贝”类型，ExecEventRef<'ring> 是零拷贝（共享内存引用）类型
6. 执行事件负载类型（monad_exec_block_start 等）- 这些是 bindgen 生成的 #[repr(C)] 事件负载类型，与其 C API 对应物匹配

​

区块级实用工具

​

ExecutedBlockBuilder

​

CommitStateBlockBuilder