我要评分

文档获取效率

文档正确性

内容完整性

文档易理解

在线提单

论坛求助

昇腾小AI

接口列表

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

您可以在CANN软件安装后文件存储路径下的“include/flow_func”查看对应接口的头文件。

接口分类及对应头文件

表1 接口分类及对应头文件
接口分类	头文件路径
AttrValue类	attr_value.h
AscendString类	ascend_string.h
MetaContext类	meta_context.h
FlowMsg类	flow_msg.h
Tensor类	flow_msg.h
MetaFlowFunc类	meta_flow_func.h
MetaMultiFunc类	meta_multi_func.h
FlowFuncRegistrar类	meta_multi_func.h
MetaParams类	meta_params.h
MetaRunContext类	meta_run_context.h
UdfTprt类	udf_tprt.h
UdfTprtTaskAttr类	udf_tprt.h
OutOptions类	out_options.h
BalanceConfig类	balance_config.h
注册宏	meta_flow_func.h meta_multi_func.h
UDF日志接口	flow_func_log.h
错误码	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类型的数据对应的数据指针和数据大小。

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。
其他	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。

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函数开始位置尝试捕获异常。

UdfTprt类

**表12** UdfTprt类接口
接口名称	简介
Init	打开TPRT并行能力，默认关闭。
Submit	用户自定义函数将task提交给TPRT调度，并描述task间的数据依赖关系。Submit是异步接口，返回时task不一定执行完成。如果用户需要等待task完成，可以调用Wait接口进行同步。
Wait	同步等待提交给TPRT的task全部执行完成。
GetNumThreads	获取工作线程数量。
GetThreadNum	获取当前函数执行线程的id。
ParallelFor	纯数据并发接口。

UdfTprtTaskAttr类

**表13** UdfTprtTaskAttr类接口
接口名称	简介
UdfTprtTaskAttr构造函数和析构函数	UdfTprtTaskAttr的构造和析构函数。
SetName	设置任务名称。
GetName	获取任务名称。
SetPriority	设置任务优先级。
GetPriority	获取任务优先级。

OutOptions类

**表14** OutOptions类接口
接口名称	简介
OutOptions构造函数和析构函数	OutOptions的构造和析构函数。
MutableBalanceConfig	获取或创建BalanceConfig。
GetBalanceConfig	获取BalanceConfig。

BalanceConfig类

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

注册宏

**表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** 错误码
错误码模块	简介
udfrefc_23_00156.html#ZH-CN_TOPIC_0000002082061833__section1390959132616	提供了flowfunc的错误码供用户使用，主要用于对异常逻辑的判断处理。
udfrefc_23_00156.html#ZH-CN_TOPIC_0000002082061833__section119131377263	AICPU在执行模型的过程中，有可能向用户上报的错误码。

父主题： UDF API（C++）