UDF APIs

This section describes the external APIs provided by the UDF module. You can call these APIs to develop custom processing functions, and then execute such functions on the CPU through DataFlow graph construction.

You can view the header files of the corresponding APIs in ${INSTALL_DIR}/include/flow_func.

Replace ${INSTALL_DIR} with the CANN component directory. For example, if the installation is performed by the root user, the default file storage path is /usr/local/Ascend/cann.

API categories and corresponding header files

**Table 1** API categories and corresponding header files
API Category	Header File Path	Description
Class AttrValue	attr_value.h	Used to obtain the attribute value set by the user.
Class AscendString	ascend_string.h	Encapsulation for the string type.
Class MetaContext	meta_context.h	Used to process UDF context, such as allocating tensors and obtaining configured attributes.
Class FlowMsg	flow_msg.h	Used to process the input and output operations of FlowFunc.
Class Tensor	flow_msg.h	Used to perform tensor-related operations.
Class MetaFlowFunc	meta_flow_func.h	Defined in meta_flow_func.h. You can inherit this class to compile custom single-func processing function.
Class MetaMultiFunc	meta_multi_func.h	Defined in meta_multi_func.h. You can inherit this class to compile custom multi-func processing function.
Class FlowFuncRegistrar	meta_multi_func.h	Defined in meta_multi_func.h. This is an auxiliary template class for registering MetaMultiFunc.
Class MetaParams	meta_params.h	Defined in meta_params.h and used in the multi-func processing function of FlowFunc to obtain shared variable information.
Class MetaRunContext	meta_run_context.h	Used to process the context of the multi-func processing function of FlowFunc, such as allocating a tensor, setting the output, and running FlowModel.
Class OutOptions	out_options.h	Used to carry related options when a service releases data.
Class BalanceConfig	balance_config.h	When balanced distribution is required, you need to configure the output data identifier and weight matrix. The scheduling module can implement balanced distribution among multiple instances based on the configuration.
Class FlowBufferFactory	flow_msg.h	-
Class FlowMsgQueue	flow_msg_queue.h	Used to serve as the input queue of FlowFunc in scenarios with streaming input (the input parameter of FlowFunc is a queue). The data object in the queue is Class FlowMsg.
Registering Macros	meta_flow_func.h meta_multi_func.h	-
UDF Log API	flow_func_log.h	flow_func_log.h provides log APIs to facilitate log recording during FlowFunc development.
Error Code	flow_func_defines.h	-

Class AttrValue

**Table 2** Class AttrValue APIs
API	Overview
AttrValue Constructor and Destructor	Constructs and destructs an object of class AttrValue.
GetVal(AscendString &value)	Obtains the attribute value of the string type.
GetVal(std::vector<AscendString> &value)	Obtains the attribute value of the list string type.
GetVal(int64_t &value)	Obtains the attribute value of the int type.
GetVal(std::vector<int64_t> &value)	Obtains the attribute value of the list int type.
GetVal(std::vector<std::vector<int64_t >> &value)	Obtains the attribute value of the list list int type.
GetVal(float &value)	Obtains the attribute value of the float type.
GetVal(std::vector<float> &value)	Obtains the attribute value of the list float type.
GetVal(bool &value)	Obtains the attribute value of the bool type.
GetVal(std::vector<bool> &value)	Obtains the attribute value of the list bool type.
GetVal(TensorDataType &value)	Obtains the attribute value of the TensorDataType type.
GetVal(std::vector<TensorDataType> &value)	Obtains the attribute value of the list TensorDataType type.

Class AscendString

**Table 3** AscendString APIs
API	Overview
AscendString Constructor and Destructor	Constructs and destructs an object of class AscendString.
GetString	Obtains the address of a string.
Relational Operator Overloading	Compares AscendString objects (sort key values by data structure of map). See the following examples.
GetLength	Obtains the length of a string.

Class MetaContext

**Table 4** MetaContext APIs
API	Overview
MetaContext Constructor and Destructor	Constructs and destructs an object of class MetaContext.
AllocTensorMsg	Allocates a message of the tensor type based on the shape and data type. This function is called by Proc.
AllocEmptyDataMsg	Allocates a message of the MsgType type that carries empty data. This function is called by Proc.
SetOutput	Sets the tensor of the output with a specified index. This function is called by Proc.
GetAttr (const char *attrName)	Obtains the pointer to AttrValue based on the attribute name. This function is called by Init.
GetAttr (const Char *attrName, T &value)	Obtains the attribute value based on the attribute name. This function is called by Init.
RunFlowModel	Runs a specified model synchronously. This function is called by Proc.
GetInputNum	Obtains the number of FlowFunc inputs. This function is called by Init.
GetOutputNum	Obtains the number of FlowFunc outputs. This function is called by Init.
GetWorkPath	Obtains the working path of FlowFunc. This function is called by Init.
GetRunningDeviceId	Obtains the ID of the running device. This function is called by Init.
GetUserData	Obtains user data. This function is called by Proc.
AllocTensorMsgWithAlign	Allocates FlowMsg of the tensor type based on the shape, data type, and alignment size. Its difference from AllocTensorMsg lies in that AllocTensorMsg allocates tensors with 64-byte alignment by default, while this function allows custom alignment size for performance tuning.
RaiseException	Throws exceptions from the UDF, which are catchable by other UDFs in the same scope.
GetException	Retrieves exceptions inside the UDF. If the exception capture function is enabled, you need to attempt to capture exceptions at the start of the Proc function within the UDF.

Class FlowMsg

**Table 5** FlowMsg APIs
API	Overview
FlowMsg Constructor and Destructor	Constructs and destructs an object of class FlowMsg.
GetMsgType	Obtains the message type of FlowMsg.
GetTensor	Obtains the tensor pointer in FlowMsg.
SetRetCode	Sets the error code in the FlowMsg message.
GetRetCode	Obtains the error code in the input FlowMsg message.
SetStartTime	Sets the start timestamp in the FlowMsg message header.
GetStartTime	Obtains the start timestamp in the FlowMsg message.
SetEndTime	Sets the end timestamp in the FlowMsg message header.
GetEndTime	Obtains the end timestamp in the FlowMsg message.
SetFlowFlags	Sets flags in the FlowMsg message header.
GetFlowFlags	Obtains flags in the FlowMsg message header.
SetRouteLabel	Sets route labels.
GetTransactionId	Obtains the transaction ID in the FlowMsg message. The transaction ID starts from 1, and is incremented by 1 each time a batch of data is fed. This function can be used to identify the ID of the data batch.
GetTensorList	Obtains the list of all tensor pointers in FlowMsg.
GetRawData	Obtains the pointer to and size of data of the RawData type.
SetMsgType	Sets the message type of FlowMsg.
SetTransactionId	Sets the transaction ID in FlowMsg.

Class Tensor

**Table 6** Tensor APIs
API	Overview
Tensor Constructor and Destructor	Constructs or destructs an object of class Tensor.
GetShape	Obtains the shape of a tensor.
GetDataType	Obtains the data type of a tensor.
GetData	Obtains the data of a tensor.
GetDataSize	Obtains the size of data in a tensor.
GetElementCnt	Obtains the number of elements in a tensor.
GetDataBufferSize	Obtains the aligned data size of a tensor.
Reshape	Reshapes a tensor without changing the tensor content.

Class MetaFlowFunc

**Table 7** Class MetaFlowFunc APIs
API	Overview
MetaFlowFunc Constructor and Destructor	Compile the user-defined single-func processing function. The MetaMultiFunc destructor releases resources.
SetContext	Sets the context of FlowFunc.
Init	Defines the user-defined FlowFunc initialization function.
Proc	Defines the user-defined FlowFunc processing function.
RegisterFlowFunc	Registers FlowFunc. You are advised to use MetaFlowFunc registration function macro to register FlowFunc.
ResetFlowFuncState	In the fault recovery scenario, the FlowFunc is quickly reset to the initial state.
Others	REGISTER_FLOW_FUNC_INNER(name, ctr, clazz) and REGISTER_FLOW_FUNC_IMPL(name, ctr, clazz) are implemented in MetaFlowFunc Registration Function Macro. You are advised not to call them directly.

Class MetaMultiFunc

**Table 8** Class MetaMultiFunc APIs
API	Overview
MetaMultiFunc Constructor and Destructor	Compile the user-defined multi-func processing function. The MetaMultiFunc destructor releases resources.
Init	Defines the user-defined FlowFunc initialization function.
Multi-Func Processing Function	Defines the user-defined multiple FlowFunc processing function.
RegisterMultiFunc	Registers multiple FlowFunc. You are advised to use MetaMultiFunc Registration Function Macro to register FlowFunc.
ResetFlowFuncState	In the fault recovery scenario, quickly resets FlowFunc to the initial state.

Class FlowFuncRegistrar

**Table 9** Class FlowFuncRegistrar APIs
API	Overview
RegProcFunc	Registers the multiple flow func processing function by using MetaMultiFunc Registration Function Macro.
CreateMultiFunc	Creates the multi-func processing object and processing function. This command is internally called by the function. You are advised not to use it directly.

Class MetaParams

**Table 10** MetaParams APIs
API	Overview
MetaParams Constructor and Destructor	Constructs and destructs an object of class MetaParams.
GetName	Obtains the instance name of FlowFunc.
GetAttr (const char *attrName)	Obtains the pointer to AttrValue based on the attribute name. This function is called by Init.
GetAttr (const Char *attrName, T &value)	Obtains the attribute value based on the attribute name. This function is called by Init.
GetInputNum	Obtains the number of FlowFunc inputs. This function is called by Init.
GetOutputNum	Obtains the number of FlowFunc outputs. This function is called by Init.
GetWorkPath	Obtains the working path of FlowFunc. This function is called by Init.
GetRunningDeviceId	Obtains the ID of the running device.

Class MetaRunContext

**Table 11** MetaRunContext APIs
API	Overview
MetaRunContext Constructor and Destructor	Constructs and destructs an object of class MetaRunContext.
AllocTensorMsg	Allocates a message of the tensor type based on the shape and data type. This function is called by Proc.
SetOutput	Sets the tensor of the output with a specified index. This function is called by Proc.
RunFlowModel	Runs a specified model synchronously. This function is called by Proc.
AllocEmptyDataMsg	Allocates a message of the MsgType type that carries empty data.
GetUserData	Obtains user data. This function is called by Proc.
SetOutput	Sets the output of the specified index and options. This function is called by the func function.
SetMultiOutputs	Sets the output of the specified index and options in batches. This function is called by the func function.
AllocTensorMsgWithAlign	Allocates FlowMsg of the tensor type based on the shape, data type, and alignment size. Its difference from AllocTensorMsg lies in that AllocTensorMsg allocates tensors with 64-byte alignment by default, while this function allows custom alignment size for performance tuning.
AllocTensorListMsg	Allocates a continuous memory block based on the input dtype shapes array to carry the tensor array.
RaiseException	Throws exceptions from the UDF, which are catchable by other UDFs in the same scope.
GetException	Retrieves exceptions inside the UDF. If the exception capture function is enabled, you need to attempt to capture exceptions at the start of the Proc function within the UDF.
AllocRawDataMsg	Allocates a continuous memory block based on the input size to carry data of the RawData type.
ToFlowMsg	Converts the input tensor to FlowMsg that carries tensors.

Class OutOptions

**Table 12** Class OutOptions APIs
API	Overview
OutOptions Constructor and Destructor	Constructs and destructs an object of class OutOptions.
MutableBalanceConfig	Obtains or creates BalanceConfig.
GetBalanceConfig	Obtains BalanceConfig.

Class BalanceConfig

**Table 13** BalanceConfig APIs
API	Overview
BalanceConfig Constructor and Destructor	Constructs and destructs an object of class BalanceConfig.
SetAffinityPolicy	Sets the balanced distribution affinity.
GetAffinityPolicy	Obtains affinity.
SetBalanceWeight	Sets the weight of balanced distribution.
GetBalanceWeight	Obtains the weight of balanced distribution.
SetDataPos	Sets the position of the output data in the weight matrix.
GetDataPos	Obtains the position of the output data in the weight matrix.

Class FlowBufferFactory

**Table 14** FlowBufferFactory APIs
API	Description
AllocTensor	Allocates tensors based on the shape, data type, and alignment size. By default, the tensor is 64-byte aligned. You can specify the alignment size for performance tuning.

Class FlowMsgQueue

**Table 15** FlowMsgQueue APIs
API	Description
FlowMsgQueue Constructor and Destructor	Constructs and destructs an object of class FlowMsgQueue.
Dequeue	Sets the balanced distribution affinity.
Depth	Obtains the queue depth, that is, the maximum number of elements in a queue.
Size	Obtains the number of current elements in a queue.

Registering Macros

**Table 16** Registering Macros
API	Overview
MetaFlowFunc Registration Function Macro	Registers the implementation class of MetaFlowFunc.
MetaMultiFunc Registration Function Macro	Registers the implementation class of MetaMultiFunc.

UDF Log APIs

**Table 17** UDF Log APIs
API	Overview
FlowFuncLogger Constructor and Destructor	Constructs and destructs an object of class FlowFuncLogger.
GetLogger	Obtains the log implementation class.
GetLogExtHeader	Obtains log extension header information.
IsLogEnable	Checks whether logs of the corresponding level and type are enabled.
Error	Records error-level logs.
Warn	Records warn-level logs.
Info	Records info-level logs.
Debug	Records debug-level logs.
Error-Level Log Macro of Run Logs	Defines the error-level log macro of run logs.
Info-Level Log Macro of Run Logs	Defines the info-level log macro of run logs.
Error-Level Log Macro of Debug Logs	Defines the error-level log macro of debug logs.
Warn-Level Log Macro of Debug Logs	Defines the warn-level log macro of debug logs.
Info-Level Log Macro of Debug Logs	Defines the info-level log macro of debug logs.
Debug-Level Log Macro of Debug Logs	Defines the debug-level log macro of debug logs.

Error Codes

**Table 18** Error codes
Error Code Module	Overview
flowfunc	Provides FlowFunc error codes for you to process abnormal logic.
AI CPU	Error codes that may be reported by the AICPU to users during model execution.

Parent topic: UDF APIs