---
title: UDF接口列表
description: "本文档主要描述UDF（User Defined Function）模块对外提供的接口，用户可以调用这些接口进行自定义处理函数的开发，然后通过DataFlow构图在CPU上执行该处理函数。"
url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/others/dataflowdevg/udfrefc_23_00001.html
sourcePath: /source/zh/canncommercial/900/others/dataflowdevg/udfrefc_23_00001.html
indexId: d916c0818ae92a4715f86caa3ffddf88f3e42866b706be9d24e97326e59af1cd71
---
# UDF接口列表

本文档主要描述UDF（User Defined Function）模块对外提供的接口，用户可以调用这些接口进行自定义处理函数的开发，然后通过DataFlow构图在CPU上执行该处理函数。

您可以在“${INSTALL_DIR}/include/flow_func”查看对应接口的头文件。

${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。

#### 接口分类及对应头文件


**表1 接口分类及对应头文件**

| 接口分类 | 头文件路径 | 简介 |
| --- | --- | --- |
| AttrValue类 | attr\_value.h | 用于获取用户设置的属性值。 |
| AscendString类 | ascend\_string.h | 对String类型的封装。 |
| MetaContext类 | meta\_context.h | 用于UDF上下文信息相关处理，如申请tensor和获取设置的属性等操作。 |
| FlowMsg类 | flow\_msg.h | 用于处理flow func输入输出的相关操作。 |
| Tensor类 | flow\_msg.h | 用于执行Tensor的相关操作。 |
| MetaFlowFunc类 | meta\_flow\_func.h | 该类在meta\_flow\_func.h中定义，用户继承该类进行自定义的单func处理函数的编写。 |
| MetaMultiFunc类 | meta\_multi\_func.h | 该类在meta\_multi\_func.h中定义，用户继承该类进行自定义的多func处理函数的编写。 |
| FlowFuncRegistrar类 | meta\_multi\_func.h | 该类在meta\_multi\_func.h中定义，是注册MetaMultiFunc的辅助模板类。 |
| MetaParams类 | meta\_params.h | 该类在meta\_params.h中定义，在FlowFunc的多func处理函数中使用该类获取共享的变量信息。 |
| MetaRunContext类 | meta\_run\_context.h | 用于执行FlowFunc的多func处理函数的上下文信息相关处理，如申请Tensor、设置输出、运行FlowModel等操作。 |
| OutOptions类 | out\_options.h | 业务发布数据时，为了携带相关的option，提供了输出options的类。 |
| BalanceConfig类 | balance\_config.h | 当需要均衡分发时，需要设置输出数据标识和权重矩阵相关配置信息，根据配置调度模块可以完成多实例之间的均衡分发。 |
| FlowBufferFactory类 | flow\_msg.h | \- |
| FlowMsgQueue类 | flow\_msg\_queue.h | 流式输入场景下（即flow func函数入参为队列时），用于flow func的输入队列，队列中的数据对象为FlowMsg类。 |
| 注册宏 | meta\_flow\_func.h meta\_multi\_func.h | \- |
| UDF日志接口 | flow\_func\_log.h | flow\_func\_log.h提供了日志接口，方便flowfunc开发中进行日志记录。 |
| 错误码 | flow\_func\_defines.h | \- |


#### AttrValue类


**表2 AttrValue类接口**

| 接口名称 | 简介 |
| --- | --- |
| AttrValue构造函数和析构函数 | AttrValue构造函数和析构函数。 |
| GetVal(AscendString &value) | 获取string类型的属性值。 |
| GetVal(std::vector<AscendString> &value) | 获取list string类型的属性值。 |
| GetVal(int64\_t &value) | 获取int类型的属性值。 |
| GetVal(std::vector<int64\_t> &value) | 获取list int类型的属性值。 |
| GetVal(std::vector<std::vector<int64\_t >> &value) | 获取list list int类型的属性值。 |
| GetVal(float &value) | 获取float类型的属性值。 |
| GetVal(std::vector<float> &value) | 获取list float类型的属性值。 |
| GetVal(bool &value) | 获取bool类型的属性值。 |
| GetVal(std::vector<bool> &value) | 获取list bool类型的属性值。 |
| GetVal(TensorDataType &value) | 获取TensorDataType类型的属性值。 |
| GetVal(std::vector<TensorDataType> &value) | 获取list TensorDataType类型的属性值。 |


#### AscendString类


**表3 AscendString类接口**

| 接口名称 | 简介 |
| --- | --- |
| AscendString构造函数和析构函数 | AscendString构造函数和析构函数。 |
| GetString | 获取字符串地址。 |
| 关系符重载 | 对于AscendString对象大小比较的使用场景（例如map数据结构的key进行排序），通过重载以下关系符实现。 |
| GetLength | 获取字符串的长度。 |


#### MetaContext类


**表4 MetaContext类接口**

| 接口名称 | 简介 |
| --- | --- |
| MetaContext构造函数和析构函数 | MetaContext构造函数和析构函数。 |
| AllocTensorMsg | 根据shape和data type申请Tensor类型的msg。该函数供Proc调用。 |
| AllocEmptyDataMsg | 申请空数据的MsgType类型的message。该函数供Proc调用。 |
| SetOutput | 设置指定index的output的tensor。该函数供Proc调用。 |
| GetAttr(const char \*attrName) | 根据属性名获取AttrValue类型的指针。该函数供Init调用。 |
| GetAttr(const char \*attrName, T &value) | 根据属性名获取对应的属性值。该函数供Init调用。 |
| RunFlowModel | 同步执行指定的模型。该函数供Proc调用。 |
| GetInputNum | 获取Flowfunc的输入个数。该函数供Init调用。 |
| GetOutputNum | 获取Flowfunc的输出个数。该函数供Init调用。 |
| GetWorkPath | 获取Flowfunc的工作路径。该函数供Init调用。 |
| GetRunningDeviceId | 获取正在运行的设备ID。该函数供Init调用。 |
| GetUserData | 获取用户数据。该函数供Proc调用。 |
| AllocTensorMsgWithAlign | 根据shape、data type和对齐大小申请Tensor类型的FlowMsg，与AllocTensorMsg函数区别是AllocTensorMsg默认申请以64字节对齐，此函数可以指定对齐大小，方便性能调优。 |
| RaiseException | UDF主动上报异常，该异常可以被同作用域内的其他UDF捕获。 |
| GetException | UDF获取异常，如果开启了异常捕获功能，需要在UDF中Proc函数开始位置尝试捕获异常。 |


#### FlowMsg类


**表5 FlowMsg类接口**

| 接口名称 | 简介 |
| --- | --- |
| FlowMsg构造函数和析构函数 | FlowMsg构造函数和析构函数。 |
| GetMsgType | 获取FlowMsg的消息类型。 |
| GetTensor | 获取FlowMsg中的Tensor指针。 |
| SetRetCode | 设置FlowMsg消息中的错误码。 |
| GetRetCode | 获取输入FlowMsg消息中的错误码。 |
| SetStartTime | 设置FlowMsg消息头中的开始时间戳。 |
| GetStartTime | 获取FlowMsg消息中的开始时间戳。 |
| SetEndTime | 设置FlowMsg消息头中的结束时间戳。 |
| GetEndTime | 获取FlowMsg消息中的结束时间戳。 |
| SetFlowFlags | 设置FlowMsg消息头中的flags。 |
| GetFlowFlags | 获取FlowMsg消息头中的flags。 |
| SetRouteLabel | 设置路由的标签。 |
| GetTransactionId | 获取FlowMsg消息中的事务ID，事务ID从1开始计数，每feed一批数据，事务ID会加一，可用于识别哪一批数据。 |
| GetTensorList | 返回FlowMsg中所有的Tensor指针列表。 |
| GetRawData | 获取RawData类型的数据对应的数据指针和数据大小。 |
| SetMsgType | 设置FlowMsg的消息类型。 |
| SetTransactionId | 设置FlowMsg消息中的事务ID。 |


#### Tensor类


**表6 Tensor类接口**

| 接口名称 | 简介 |
| --- | --- |
| Tensor构造函数和析构函数 | Tensor构造函数和析构函数。 |
| GetShape | 获取Tensor的Shape。 |
| GetDataType | 获取Tensor中的数据类型。 |
| GetData | 获取Tensor中的数据。 |
| GetDataSize | 获取Tensor中的数据大小。 |
| GetElementCnt | 获取Tensor中的元素的个数。 |
| GetDataBufferSize | 获取Tensor中的对齐后的数据大小。 |
| Reshape | 对Tensor进行Reshape操作，不改变Tensor的内容。 |


#### MetaFlowFunc类


**表7 MetaFlowFunc类接口**

| 接口名称 | 简介 |
| --- | --- |
| MetaFlowFunc构造函数和析构函数 | 用户继承该类进行自定义的单func处理函数的编写。在析构函数中，执行释放相关资源操作。 |
| SetContext | 设置flow func的上下文信息。 |
| Init | 用户自定义flow func的初始化函数。 |
| Proc | 用户自定义flow func的处理函数。 |
| RegisterFlowFunc | 注册flow func。 不建议直接使用该函数，建议使用MetaFlowFunc注册函数宏来注册flow func。 |
| ResetFlowFuncState | 在故障恢复场景下，快速重置FlowFunc为初始化状态。 |
| 其他 | REGISTER\_FLOW\_FUNC\_INNER(name, ctr, clazz)和REGISTER\_FLOW\_FUNC\_IMPL(name, ctr, clazz)是MetaFlowFunc注册函数宏的实现，不建议用户直接调用。 |


#### MetaMultiFunc类


**表8 MetaMultiFunc类接口**

| 接口名称 | 简介 |
| --- | --- |
| MetaMultiFunc构造函数和析构函数 | 用户继承该类进行自定义的多func处理函数的编写。在析构函数中，执行释放相关资源操作。 |
| Init | 用户自定义flow func的初始化函数。 |
| 多func处理函数 | 用户自定义多flow func的处理函数。 |
| RegisterMultiFunc | 注册多flow func。 不建议直接使用该函数，建议使用MetaMultiFunc注册函数宏来注册flow func。 |
| ResetFlowFuncState | 在故障恢复场景下，快速重置FlowFunc为初始化状态。 |


#### FlowFuncRegistrar类


**表9 FlowFuncRegistrar类接口**

| 接口名称 | 简介 |
| --- | --- |
| RegProcFunc | 注册多flow func处理函数，结合MetaMultiFunc注册函数宏来注册flow func。 |
| CreateMultiFunc | 创建多func处理对象和处理函数，框架内部使用，用户不直接使用。 |


#### MetaParams类


**表10 MetaParams类接口**

| 接口名称 | 简介 |
| --- | --- |
| MetaParams构造函数和析构函数 | MetaParams构造函数和析构函数。 |
| GetName | 获取Flowfunc的实例名。 |
| GetAttr(const char \*attrName) | 根据属性名获取AttrValue类型的指针。该函数供Init调用。 |
| GetAttr(const char \*attrName, T &value) | 根据属性名获取对应的属性值。该函数供Init调用。 |
| GetInputNum | 获取Flowfunc的输入个数。该函数供Init调用。 |
| GetOutputNum | 获取Flowfunc的输出个数。该函数供Init调用。 |
| GetWorkPath | 获取Flowfunc的工作路径。该函数供Init调用。 |
| GetRunningDeviceId | 获取正在运行的设备ID。 |


#### MetaRunContext类


**表11 MetaRunContext类接口**

| 接口名称 | 简介 |
| --- | --- |
| MetaRunContext构造函数和析构函数 | MetaRunContext构造函数和析构函数。 |
| AllocTensorMsg | 根据shape和data type申请Tensor类型的msg。该函数供Proc调用。 |
| SetOutput | 设置指定index的output的tensor。该函数供Proc调用。 |
| RunFlowModel | 同步执行指定的模型。该函数供Proc调用。 |
| AllocEmptyDataMsg | 申请空数据的MsgType类型的message。 |
| GetUserData | 获取用户数据。该函数供Proc调用。 |
| SetOutput | 设置指定index和options的输出，该函数供func函数调用。 |
| SetMultiOutputs | 批量设置指定index和options的输出，该函数供func函数调用。 |
| AllocTensorMsgWithAlign | 根据shape、data type和对齐大小申请Tensor类型的FlowMsg，与AllocTensorMsg函数区别是AllocTensorMsg默认申请以64字节对齐，此函数可以指定对齐大小，方便性能调优。 |
| AllocTensorListMsg | 根据输入的dtype shapes数组分配一块连续内存，用于承载Tensor数组。 |
| RaiseException | UDF主动上报异常，该异常可以被同作用域内的其他UDF捕获。 |
| GetException | UDF获取异常，如果开启了异常捕获功能，需要在UDF中Proc函数开始位置尝试捕获异常。 |
| AllocRawDataMsg | 根据输入的size申请一块连续内存，用于承载RawData类型的数据。 |
| ToFlowMsg | 根据输入的Tensor转换成用于承载Tensor的FlowMsg。 |


#### OutOptions类


**表12 OutOptions类接口**

| 接口名称 | 简介 |
| --- | --- |
| OutOptions构造函数和析构函数 | OutOptions的构造和析构函数。 |
| MutableBalanceConfig | 获取或创建BalanceConfig。 |
| GetBalanceConfig | 获取BalanceConfig。 |


#### BalanceConfig类


**表13 BalanceConfig类接口**

| 接口名称 | 简介 |
| --- | --- |
| BalanceConfig构造函数和析构函数 | BalanceConfig的构造和析构函数。 |
| SetAffinityPolicy | 设置均衡分发亲和性。 |
| GetAffinityPolicy | 获取亲和性。 |
| SetBalanceWeight | 设置均衡分发权重信息。 |
| GetBalanceWeight | 获取均衡分发权重信息。 |
| SetDataPos | 设置输出数据对应权重矩阵中的位置。 |
| GetDataPos | 获取输出数据对应权重矩阵中的位置。 |


#### FlowBufferFactory类


**表14 FlowBufferFactory类接口**

| 接口名称 | 简介 |
| --- | --- |
| AllocTensor | 根据shape、data type和对齐大小申请Tensor，默认申请以64字节对齐，可以指定对齐大小，方便性能调优。 |


#### FlowMsgQueue类


**表15 FlowMsgQueue类接口**

| 接口名称 | 简介 |
| --- | --- |
| FlowMsgQueue构造函数和析构函数 | FlowMsgQueue的构造和析构函数。 |
| Dequeue | 设置均衡分发亲和性。 |
| Depth | 获取队列的深度，即获取队列可容纳元素的最大个数。 |
| Size | 获取队列中当前元素的个数。 |


#### 注册宏


**表16 注册宏**

| 接口名称 | 简介 |
| --- | --- |
| MetaFlowFunc注册函数宏 | 注册MetaFlowFunc的实现类。 |
| MetaMultiFunc注册函数宏 | 注册MetaMultiFunc的实现类。 |


#### UDF日志接口


**表17 UDF日志接口**

| 接口名称 | 简介 |
| --- | --- |
| FlowFuncLogger构造函数和析构函数 | FlowFuncLogger构造函数和析构函数。 |
| GetLogger | 获取日志实现类。 |
| GetLogExtHeader | 获取日志扩展头信息。 |
| IsLogEnable | 查询对应级别和类型的日志是否开启。 |
| Error | 记录ERROR级别日志。 |
| Warn | 记录Warn级别日志。 |
| Info | 记录Info级别日志。 |
| Debug | 记录Debug级别日志。 |
| 运行日志Error级别日志宏 | 运行日志Error级别日志宏。 |
| 运行日志Info级别日志宏 | 运行日志Info级别日志宏。 |
| 调试日志Error级别日志宏 | 调试日志Error级别日志宏。 |
| 调试日志Warn级别日志宏 | 调试日志Warn级别日志宏。 |
| 调试日志Info级别日志宏 | 调试日志Info级别日志宏。 |
| 调试日志Debug级别日志宏 | 调试日志Debug级别日志宏。 |


#### 错误码


**表18 错误码**

| 错误码模块 | 简介 |
| --- | --- |
| flowfunc | 提供了flowfunc的错误码供用户使用，主要用于对异常逻辑的判断处理。 |
| AI CPU | AICPU在执行模型的过程中，有可能向用户上报的错误码。 |