> ## Documentation Index > Fetch the complete documentation index at: https://docs.monad.xyz/llms.txt > Use this file to discover all available pages before exploring further. # C API ## 核心概念 event ring C API 中有两个核心对象： 1. **struct `monad_event_ring`** - 表示一个已将其共享内存段映射到当前进程地址空间的 event ring；客户端对该对象最主要的用途是使用它初始化指向 event ring 的迭代器，使用 `monad_event_ring_init_iterator` 函数 2. **struct `monad_event_iterator`** - 主角：该迭代器对象用于顺序读取事件。迭代器的 `try_next` 操作会拷贝当前事件描述符（如果可用），如果成功则推进迭代器。概念上其行为类似表达式 `descriptor = *i++`，前提是有事件描述符立即就绪（否则什么也不做） 理解该 API 最简单的方式是编译并运行随附的 `eventwatch` 示例程序。该程序将执行事件的 ASCII 表示形式转储到 `stdout`，这些事件由运行在同一主机上的执行层守护进程写入。 在 `eventwatch` 中，事件描述符被完全解码，但事件负载仅以十六进制转储形式显示，因为这个简单程序不包含所有事件负载类型的美化打印逻辑。该程序仅 250 行代码，通读它应能解释各个 API 调用如何协同工作。 SDK 还包括 C++20 [`std::formatter`](https://en.cppreference.com/w/cpp/utility/format/formatter.html) 特化，可将事件负载完全解码为人类可读形式。这些被 `monad-event-cli` 实用程序使用。 ## 在您的项目中使用 API `libmonad_event` 面向第三方集成设计，因此除了较新版本的 glibc 外没有其他库依赖。这也意味着它不依赖 monad 仓库的其他部分或其构建系统：唯一要求是支持 C23 的 C 编译器。 构建 C 示例程序的"开始使用"指南[讨论了多种方法](/zh/execution-events/getting-started/c#how-can-my-code-use-libmonad_event-a)将 SDK 库作为第三方依赖用于您的代码。或者，可以将组成库目标的源文件复制到您自己的代码库中。也提供了 [Rust 客户端库](/zh/execution-events/rust-api)。 ## API 概览 ### event ring API | API | 用途 | | --------------------------------- | --------------------------------------------------------------------------- | | `monad_event_ring_mmap` | 给定一个已打开的 event ring 文件的文件描述符，将其共享内存段映射到当前进程，初始化一个 `struct monad_event_ring` | | `monad_event_ring_init_iterator` | 给定指向 `struct monad_event_ring` 的指针，初始化一个可以从 event ring 读取的迭代器 | | `monad_event_ring_try_copy` | 给定特定的序列号，尝试拷贝对应的事件描述符（如果尚未被覆盖） | | `monad_event_ring_payload_peek` | 获取指向事件负载的零拷贝指针 | | `monad_event_ring_payload_check` | 检查零拷贝指针所指向的事件负载是否已被覆盖 | | `monad_event_ring_memcpy` | `memcpy` 事件负载到缓冲区，仅当负载未过期时成功 | | `monad_event_ring_get_last_error` | 返回一个人类可读字符串，描述此线程上发生的最近一次错误 | 所有可能失败的函数都会返回 `errno(3)` 域错误码，说明失败原因。可调用 `monad_event_ring_get_last_error` 函数以提供失败原因的人类可读字符串说明。 ### 事件迭代器 API | API | 用途 | | ------------------------------------------ | ----------------------------------------------------------------------------- | | `monad_event_iterator_try_next` | 如果有事件描述符可用，则拷贝并推进迭代器；行为类似于 `*i++`，但仅当 `*i` 就绪时 | | `monad_event_iterator_try_copy` | 拷贝当前迭代点的事件描述符，不推进迭代器 | | `monad_event_iterator_reset` | 重置迭代器指向最近产生的事件描述符；用于 gap 恢复 | | `monad_exec_iter_consensus_prev` | 将迭代器倒回到上一个共识事件（`BLOCK_START`、`BLOCK_QC`、`BLOCK_FINALIZED` 或 `BLOCK_VERIFIED`） | | `monad_exec_iter_block_number_prev` | 将迭代器倒回到给定区块编号的上一个共识事件 | | `monad_exec_iter_block_id_prev` | 将迭代器倒回到给定区块 ID 的上一个共识事件 | | `monad_exec_iter_rewind_for_simple_replay` | 根据您看到的最后一个已确认区块，将迭代器倒回以重放您可能错过的事件 | ### event ring 实用 API | API | 用途 | | --------------------------------------- | -------------------------------------------------------- | | `monad_event_ring_check_content_type` | 检查库使用的事件定义二进制布局是否与已映射的 event ring 中记录的一致 | | `monad_event_ring_find_writer_pids` | 查找为写入而打开 event ring 文件描述符的进程；用于检测发布方退出 | | `monad_check_path_supports_map_hugetlb` | 检查路径是否位于允许其文件以 `MAP_HUGETLB` 进行 mmap 的文件系统上 | | `monad_event_open_hugetlbfs_dir_fd` | 打开创建 event ring 文件的默认 hugetlbfs 目录[^1] | | `monad_event_resolve_ring_file` | 如果路径不包含 `/` 字符（即它是"纯"文件名），则相对于某个默认 event ring 目录进行解析[^2] | | `monad_event_is_snapshot_file` | 检查路径是否指向 event ring 快照文件 | | `monad_event_decompress_snapshot_fd` | 解压给定文件描述符中包含的 event ring 快照 | | `monad_event_decompress_snapshot_mem` | 解压给定内存缓冲区中包含的 event ring 快照 | [^1]: 默认情况下，这会返回 hugetlbfs 挂载上的路径，由 libhugetlbfs 计算得出 [^2]: 如果使用 `MONAD_EVENT_USE_LIBHUGETLBFS=OFF` 编译，则必须指定默认 event ring 目录；详情见[此处](/zh/execution-events/advanced#location-of-event-ring-files) ## 库组织 `libmonad_event` 中的 event ring 文件： | 文件 | 内容 | | ------------------------- | ----------------------------------------------------- | | `event_ring.{h,c}` | event ring 核心共享内存结构的定义，以及初始化和 mmap event ring 文件的 API | | `event_iterator.h` | 定义基本事件迭代器对象及其 API | | `event_iterator_inline.h` | `event_iterator.h` 中函数的定义，出于性能原因全部为内联 | | `event_metadata.h` | 描述事件元数据的结构（事件的字符串名称、事件描述等） | | `exec_iter_help.h` | 用于将迭代器倒回到区块执行或共识事件的 API | `libmonad_event` 中的执行事件文件： | 文件 | 内容 | | ------------------------------ | ------------------------------------------------- | | `base_ctypes.h` | 以太坊数据中常见基础词汇类型的定义（例如 256 位整数类型等） | | `eth_ctypes.h` | 以太坊虚拟机中使用的结构定义 | | `exec_event_ctypes.h` | 执行事件负载结构的定义，以及事件类型枚举 `enum monad_exec_event_type` | | `exec_event_ctypes_metadata.c` | 定义执行事件的静态元数据，以及 schema 哈希值数组 | | `monad_ctypes.h` | Monad 区块链对以太坊扩展的定义 | `libmonad_event` 中的支持文件： | 文件 | 内容 | | ----------------------- | -------------------------------------------------------- | | `event_ring_util.{h,c}` | 在大多数 event ring 程序中有用的便利函数，但不属于核心 API | | `format_err.{h,c}` | 来自执行代码库的辅助工具，用于实现 `monad_event_ring_get_last_error()` 函数 | | `srcloc.h` | 与 `format_err.h` API 一起使用的辅助工具，用于在 C 中捕获源代码位置 | SDK 中的其他文件： | 文件 | 内容 | | -------------- | ---------------------------------------------------------------------- | | `eventwatch.c` | 展示如何使用 API 的示例程序 | | `*_fmt.hpp` 文件 | 以 `_fmt.hpp` 结尾的文件与 C++ `` 一起使用，包含 SDK 类型的 `std::formatter` 特化 | | `hex.hpp` | `_fmt.hpp` 文件使用的 `` 十六进制转储实用工具，用于转储 `uint8_t[]` 值 |