运行时 API 参考¶

ExecuTorch C++ API 提供了一个用于导出 PyTorch 模型的设备端执行框架。

有关运行时 API 的教程式介绍，请参阅运行时教程及其简化版。

有关 API 如何演变和弃用过程的详细信息，请参阅 ExecuTorch API 生命周期和弃用策略。

模型加载和执行¶

警告

doxygenclass: 在项目“ExecuTorch”的 doxygen xml 输出中找不到类“executorch::runtime::Program”，来自目录：../build/xml/

警告

doxygenclass: 在项目“ExecuTorch”的 doxygen xml 输出中找不到类“executorch::runtime::Method”，来自目录：../build/xml/

警告

doxygenclass: 在项目“ExecuTorch”的 doxygen xml 输出中找不到类“executorch::runtime::MethodMeta”，来自目录：../build/xml/

class DataLoader¶

从数据源加载。

请参阅 //executorch/extension/data_loader 以获取常见实现。

公共函数

virtual ET_NODISCARD Result< FreeableBuffer > load (size_t offset, size_t size, const SegmentInfo &segment_info) const =0

从底层数据源加载数据。

注意：这必须是线程安全的。如果此调用修改了公共状态，则实现必须自行进行锁定。

参数

offset – 数据源中开始加载的字节偏移量。
size – 要加载的字节数。
segment_info – 有关正在加载的段的信息。

返回

一个拥有加载数据的 FreeableBuffer。

inline virtual ET_NODISCARD Error load_into (size_t offset, size_t size, const SegmentInfo &segment_info, void *buffer) const

将数据从底层数据源加载到提供的缓冲区中。

注意：这必须是线程安全的。如果此调用修改了公共状态，则实现必须自行进行锁定。

参数

offset – 数据源中开始加载的字节偏移量。
size – 要加载的字节数。
segment_info – 有关正在加载的段的信息。
buffer – 要加载数据到的缓冲区。必须指向至少 size 字节的内存。

返回

一个指示加载是否成功的 Error。

virtual ET_NODISCARD Result< size_t > size () const =0: 返回底层数据源的长度，通常是文件大小。

struct SegmentInfo¶

描述段的内容。

公共类型

enum class Type¶

表示段的用途。

值

enumerator Program¶: 实际程序的数据。

enumerator Constant¶: 包含常量张量数据。

enumerator Backend¶: 用于初始化后端的 Adata。

enumerator Mutable¶: 用于初始化可变张量的数据。

enumerator External¶: 用于初始化外部张量的数据。

公共成员

Type segment_type¶: 段的类型。

size_t segment_index¶: 段在段列表中的索引。对于程序段，此值未定义。

const char *descriptor¶: 描述该段的可选的、以 null 结尾的字符串。对于 Backend 段，这是后端 ID。对于其他段类型，此值为 null。

class MemoryAllocator¶

一个根据大小进行简单分配并返回内存地址指针的类。它为具有特定大小的缓冲区设置书签。分配只是检查空间并在每次请求分配时递增 cur_ 指针。

简单示例

// 用户在堆上分配一个 100 字节的内存。 uint8_t* memory_pool = malloc(100 * sizeof(uint8_t)); MemoryAllocator allocator(100, memory_pool) // 在 Executor 中传递 allocator 对象

在底层，ExecuTorch 将调用 allocator.allocate() 来不断递增 cur_ 指针

公共函数

inline MemoryAllocator(uint32_t size, uint8_t *base_address)¶

使用给定 size 和 base_address 提供的缓冲区创建一个新的内存分配器。

参数

size – [in] base_address 处缓冲区的字节大小。
base_address – [in] 用于分配的缓冲区。不拥有此缓冲区的拥有权，因此它必须在 MemoryAllocator 的生命周期内有效。

inline virtual void *allocate(size_t size, size_t alignment = kDefaultAlignment)¶

分配 size 字节的内存。

参数

size – [in] 要分配的字节数。
alignment – [in] 返回指针的最小对齐要求。必须是 2 的幂。

返回值

nullptr – 内存不足，或 alignment 不是 2 的幂。

返回

成功时，返回分配内存的对齐指针。

template<typename T> inline T *allocateInstance(size_t alignment = alignof(T))¶

分配一个足够容纳 T 类型实例的缓冲区。注意，内存不会被初始化。

示例

auto p = memory_allocator->allocateInstance<MyType>();

参数: alignment – [in] 返回指针的最小对齐要求。必须是 2 的幂。默认为 T 的自然对齐。
返回值: nullptr – 内存不足，或 alignment 不是 2 的幂。
返回: 成功时，返回分配内存的对齐指针。

template<typename T> inline T *allocateList(size_t size, size_t alignment = alignof(T))¶

分配 size 个 T 类型的数据块，其中每个数据块的大小等于 sizeof(T) 字节。

参数

size – [in] 要分配的内存块数。
alignment – [in] 返回指针的最小对齐要求。必须是 2 的幂。默认为 T 的自然对齐。

返回值

nullptr – 内存不足，或 alignment 不是 2 的幂。

返回

成功时，返回分配内存的对齐指针。

公共静态属性

static constexpr size_t kDefaultAlignment = alignof(void*)¶: 此类返回的内存的默认对齐。确保结构中的指针字段对齐。但是，像 long double 这样更大的类型可能不会对齐，具体取决于工具链和架构。

class HierarchicalAllocator¶

一组缓冲区，可用于表示设备的内存层次结构。

公共函数

inline explicit HierarchicalAllocator(Span<Span<uint8_t>> buffers)¶

使用给定的缓冲区数组构造一个新的分层分配器。

内存 ID 基于 buffers 中的索引：buffers[N] 的内存 ID 为 N。
buffers.size() 必须大于等于 MethodMeta::num_non_const_buffers()。
buffers[N].size() 必须大于等于 MethodMeta::non_const_buffer_size(N)。

inline ET_DEPRECATED HierarchicalAllocator(uint32_t n_allocators, MemoryAllocator *allocators)¶: 已弃用：请改用 spans。

inline ET_NODISCARD Result< void * > get_offset_address (uint32_t memory_id, size_t offset_bytes, size_t size_bytes)

返回从给定缓冲区基地址开始的字节偏移量 offset_bytes 处的地址，该地址指向至少 size_bytes 的内存。

参数

memory_id – [in] 层次结构中缓冲区的 ID。
offset_bytes – [in] 指定缓冲区中以字节为单位的偏移量。
size_bytes – [in] 在偏移量处应可用的内存量。

返回

成功时，返回指定缓冲区中请求的字节偏移量的地址。失败时，返回非 Ok 的 Error。

class MemoryManager¶

用于 Method 加载和执行期间分配器的容器类。

此类整合了 Method 加载和执行的所有动态内存需求。这可以实现基于堆以及无堆的执行（与某些嵌入式场景相关），并总体上提供对内存使用的更多控制。

然而，此类无法确保所有分配都得到处理，因为内核和后端实现可以自由使用单独的内存分配方式（例如，用于临时空间等）。但我们建议后端和内核尽可能使用这些提供的分配器。

公共函数

inline explicit MemoryManager(MemoryAllocator *method_allocator, HierarchicalAllocator *planned_memory = nullptr, MemoryAllocator *temp_allocator = nullptr)¶

构造一个新的 MemoryManager。

参数

method_allocator – [in] 加载 Method 并分配其内部结构时使用的分配器。必须比使用它的 Method 的生命周期长。
planned_memory – [in] 用于执行 Method 时的可变张量数据的内存计划缓冲区。必须比使用它的 Method 的生命周期长。如果 Method 不使用任何内存计划的张量数据，则可以为 nullptr。此 HierarchicalAllocator 中的缓冲区大小必须与嵌入在 Program 中的相应 MethodMeta::num_memory_planned_buffers() 和 MethodMeta::memory_planned_buffer_size(N) 值匹配。
temp_allocator – [in] 在内核或委托执行期间分配临时数据时使用的分配器。必须比使用它的 Method 的生命周期长。如果 Method 不使用分配临时数据的内核或委托，则可以为 nullptr。此分配器将在每次内核或委托调用执行后重置。

inline ET_DEPRECATED MemoryManager(MemoryAllocator *constant_allocator, HierarchicalAllocator *non_constant_allocator, MemoryAllocator *runtime_allocator, MemoryAllocator *temporary_allocator)¶

已弃用：请改用不带 constant_allocator 的构造函数。

TODO(T162089316)：在所有用户迁移到新构造函数后移除此项。

inline MemoryAllocator *method_allocator() const¶: 返回运行时在加载 Method 时用于分配内部结构的分配器。在其关联的 Method 加载后不得使用。

inline HierarchicalAllocator *planned_memory() const¶: 返回用于可变张量数据的内存计划缓冲区。

inline MemoryAllocator *temp_allocator() const¶

返回在内核或委托执行期间分配临时数据所使用的分配器。

此分配器将在每次内核或委托调用执行后重置。

值¶

struct EValue¶

公共函数

inline EValue(executorch::aten::Scalar s)¶: 使用 Scalar 的隐式值构造一个 EValue。

template<typename T> inline std::optional<T> toOptional() const¶: 将 EValue 转换为一个可选对象，该对象可以同时表示 T 和未初始化状态。

union Payload¶

union TriviallyCopyablePayload¶

class Tensor¶

一个最小的 Tensor 类型，其 API 是 at::Tensor 的源兼容子集。

注意：此类的实例不拥有传递给它的 TensorImpl，这意味着调用者必须保证 TensorImpl 的生命周期比指向它的任何 Tensor 实例的生命周期更长。

有关此处使用的返回/参数类型以及它们与 at::Tensor 的关系，请参阅 TensorImpl 文档。

公共类型

using SizesType = TensorImpl::SizesType¶: 用于 sizes() 元素的类型。

using DimOrderType = TensorImpl::DimOrderType¶: 用于 dim_order() 元素的类型。

using StridesType = TensorImpl::StridesType¶: 用于 strides() 元素的类型。

公共函数

inline TensorImpl *unsafeGetTensorImpl() const¶

返回底层 TensorImpl 的指针。

注意：客户端应谨慎直接操作 TensorImpl 而不是 Tensor。很容易出错。

inline size_t nbytes() const¶

返回张量的大小（以字节为单位）。

注意：仅返回已使用的空间，而不是底层数据块的总容量。

inline ssize_t size(ssize_t dim) const¶

返回给定维度的张量大小。

注意：size() 故意不返回 SizeType，尽管它返回 SizeType 数组的一个元素。这是为了使此方法的调用与 at::Tensor 更兼容，并与该类和 ETensor 的其他方法更一致。

inline ssize_t dim() const¶: 返回张量的维数。

inline ssize_t numel() const¶: 返回张中的元素数量。

inline ScalarType scalar_type() const¶: 返回张量中元素的类型（int32、float、bool 等）。

inline ssize_t element_size() const¶: 返回张量中一个元素的大小（以字节为单位）。

inline const ArrayRef<SizesType> sizes() const¶: 返回张量在每个维度的尺寸。

inline const ArrayRef<DimOrderType> dim_order() const¶: 返回维度在内存中的布局顺序。

inline const ArrayRef<StridesType> strides() const¶: 返回张量在每个维度的步幅。

inline TensorShapeDynamism shape_dynamism() const¶: 返回张量形状的可变性。

template<typename T> inline const T *const_data_ptr() const¶: 返回指向常量底层数据块的 T 类型指针。

inline const void *const_data_ptr() const¶: 返回指向常量底层数据块的指针。

template<typename T> inline T *mutable_data_ptr() const¶: 返回指向可变底层数据块的 T 类型指针。

inline void *mutable_data_ptr() const¶: 返回指向可变底层数据块的指针。

template<typename T> inline ET_DEPRECATED T * data_ptr () const: 已弃用：请改用 const_data_ptr 或 mutable_data_ptr。

inline ET_DEPRECATED void * data_ptr () const: 已弃用：请改用 const_data_ptr 或 mutable_data_ptr。

inline ET_DEPRECATED void set_data (void *ptr) const: 已弃用：更改张量所指向的 data_ptr。不释放先前指向的数据，也不假定新指针的拥有权语义。此 API 在 at::Tensor 中不存在，因此内核开发人员应避免使用它。

运行时 API 参考¶

模型加载和执行¶

值¶

文档

教程

资源