FuncProcessPoint

Applicability

Product	Supported
Atlas A3 training product/Atlas A3 inference product	√
Atlas A2 training product/Atlas A2 inference product	√
Atlas 200I/500 A2 inference product	x
Atlas inference product	x
Atlas training product	x

Function Description

Defines the FuncProcessPoint constructor, which returns a FuncProcessPoint object.

Prototype

class FuncProcessPoint(compile_config_path: Optional[str] = None, name: Optional[str] = None,
py_func: Optional = None, workspace_dir: Optional = None)

Parameters

Parameter	Data Type	Description
compile_config_path	str	UDF compilation configuration file, which is mutually exclusive with py_func. After the py_func parameter is input, compile_config_path does not take effect.
name	str	Name of the ProcessPoint. The framework automatically ensures that the name is unique. If this parameter is not set, names such as FuncProcessPoint, FuncProcessPoint_1, FuncProcessPoint_2, and the like will be automatically generated.
py_func	class	UDF (Python) class (using proc_wrapper(func_list="ix:ox" to register inputs and outputs), which is mutually exclusive with compile_config_path. After the py_func parameter is input, compile_config_path does not take effect.
workspace_dir	str	Automatically generated UDF (Python) temporary workspace directory, which is used in conjunction with py_func. If this field is left empty, the py_func name is combined with _ws.

The following is an example of the UDF compilation configuration file:

{"func_list":[{"func_name":"Add", "inputs_index":[1,0], "outputs_index":[0]}],"input_num":2,"output_num":1,"target_bin":"libadd.so","workspace":"./","cmakelist_path":"CMakeLists.txt","compiler": "./cpu_compile.json","running_resources_info":[{"type":"cpu","num":2},{"type":"memory","num":100}],"heavy_load":false}

**Table 1** Parameters in the JSON configuration file of FuncProcessPoint
Configuration Item	Optional/Mandatory	Description
workspace	Mandatory	UDF workspace path, which is a string.
target_bin	Mandatory	Name of the .so file, which is a string compiled by the UDF project. To prevent the string from being tampered with, the string must be named with lib.so*. The string can contain only uppercase and lowercase letters, digits, underscores (_), and hyphens (-).
input_num	Mandatory	Number of UDF inputs, that is, the number of FuncProcessPoint inputs.
output_num	Mandatory	Number of UDF outputs, that is, the number of FuncProcessPoint outputs.
func_list	Mandatory	List of function descriptions. Currently, the list can contain descriptions of only one function.
func_list.func_name	Mandatory	Function name, which is a string and must be consistent with that defined in the UDF. If multiple functions are involved, the function name must be unique.
func_list.inputs_index	Optional	List of input indexes of FuncProcessPoint. This parameter is invalid if only one function is involved but mandatory if multiple functions are involved. Input indexes of multiple processing functions are not shared and cannot be repeated.
func_list.outputs_index	Optional	List of output indexes of FuncProcessPoint. This parameter is invalid if only one function is involved. If multiple functions are involved, output indexes can be shared.
cmakelist_path	Optional	Path of the compiled CMakeLists file relative to the workspace, which is a string. If this parameter is not specified, the default CMakeLists file in the workspace will be used.
compiler	Optional	Path configuration file of the compiler for compiling the source code in a heterogeneous environment, which is a string. If this parameter is not specified, the default compiler of the corresponding resource type will be used.
running_resources_info	Optional	List of resources required for running the current .so file. An element on the list is the description of a resource.
running_resources_info.type	Optional	This parameter is mandatory if running_resources_info is set. Type of resources required for running the current .so file, which is a string. The options are cpu and memory. If the memory value is used, the unit is MB.
running_resources_info.num	Optional	This parameter is mandatory if running_resources_info is set. Number of resources required for running the current .so file.
heavy_load	Optional	Compute power requirements of a node. true: heavy load, indicating that the node has high requirements for compute power. false: light load, indicating that the node has low requirements for compute power. The default value is false. If this parameter is set to true, the UDF deployment position will be affected.
buf_cfg	Optional	You can customize the level of the memory pool to improve the memory allocation efficiency and reduce memory fragments. If this parameter is not set, the default level is used to initialize the memory module. For details about the default level and parameter example, see the JSON configuration format of buf_cfg. A maximum of 64 levels are supported. If the number of levels exceeds 64, an error is reported during compilation.

JSON configuration of the compiler

The file content example and parameters in the file are as follows:

{"compiler":[{"resource_type":"X86","toolchain":"/usr/bin/g++"},{"resource_type":"Aarch","toolchain":"/usr/bin/g++"},{"resource_type":"Ascend","toolchain":"/usr/local/Ascend/hcc"}]}

**Table 2** Parameters in the JSON configuration file of the compiler
Configuration Item	Optional/Mandatory	Description
compiler	Mandatory	List of compiler descriptions corresponding to resource types.
compiler.resource_type	Mandatory	Supported resource type, which is a string.
compiler.toolchain	Mandatory	Compiler path corresponding to the resource type, which is a string.

JSON configuration of buf_cfg

The file content example and parameters in the file are as follows:

"buf_cfg":[{"total_size":2097152,"blk_size":256,"max_buf_size":8192,"page_type":"normal"},        // 1.total:2M  max:8K
           {"total_size":10485760,"blk_size":4096,"max_buf_size":8388608,"page_type":"normal"},   // 2.total:10M  max:8M
           {"total_size":2097152,"blk_size":256,"max_buf_size":8192,"page_type":"huge"},          // 3.total:2M  max:8K     
           {"total_size":10485760,"blk_size":8192,"max_buf_size":8388608,"page_type":"huge"},     // 4.total:10M  max:8M
           {"total_size":69206016,"blk_size":8192,"max_buf_size":67108864,"page_type":"huge"}]    // 5.total:66M  max:64M
Note:
In the preceding example, five memory levels are set. The first two levels are for common memory, and the last three levels are for hugepage memory.
After the memory management module is initialized with this configuration, if a process applies for 8 MB hugepage memory, the driver generates and manages a 10 MB memory pool based on the fourth configuration and allocate 8 MB memory from the pool.
If the process needs to apply for 1 MB hugepage memory again, the memory pool corresponding to the fourth configuration is still used because the maximum size of the third configuration is 8 KB. In this case, only 8 MB memory is used in the 10 MB memory pool, and the remaining memory is still greater than 1 MB. Therefore, 1 MB memory is allocated from the 10 MB memory pool generated last time.

The default levels are as follows.

ID	total_size	blk_size	max_buf_size	page_type
0	2 MB	256 bytes	8 KB	normal
1	32 MB	8 KB	8 MB	normal
3	2 MB	256 bytes	8 KB	huge
4	66 MB	8 KB	64 MB	huge

**Table 3** buf_cfg JSON configuration description
Configuration Item	Optional/Mandatory	Description
total_size	Mandatory	Size of the memory pool at the current level, in bytes. Constraints: For common memory, the value of total_size is a multiple of 4 KB. For hugepage memory, the value of total_size is a multiple of 2 MB and a multiple of blk_size.
blk_size	Mandatory	Minimum memory that can be allocated at a time at the current level, in bytes. Constraints: The value must be 2ⁿ within a range of (0, 2 MB], and less than the value of max_buf_size.
max_buf_size	Mandatory	Maximum memory that can be allocated at a time at the current level, in bytes. Constraints: The value must be less than that of total_size.
page_type	Mandatory	Memory type corresponding to the current level. Constraints: The value can be huge or normal, indicating hugepage memory and common memory, respectively.

CMakeLists file

The UDF compilation module of DataFlow parses the resource.json and cpu_compiler.json file in the heterogeneous environment, and matches cross compilers specified in cpu_compiler.json based on resource types configured in resource.json. If no cpu_compiler.json is specified or no compiler is configured for the resource type in cpu_compiler.json, the default compiler in the environment will be used for compilation. The names and paths of compilers for different resource types are as follows: 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.

x86 and AArch: g++
Ascend: ${INSTALL_DIR}/toolkit/toolchain/hcc/bin/aarch64-target-linux-gnu-g++

The source code project must comply with the following rules:

The source code project directory must contain all execution code and dependency library source code.
You need to configure the FuncProcessPoint execution code and the compilation script of the dependency library.
The compilation script needs to use the RELEASE_DIR variable as the final output directory. If there are dependent .so files, you need to copy them to this directory.
The compilation script needs to use the RESOURCE_TYPE variable to determine the resource type. If the current UDF does not support a resource type, you need to remove the corresponding comments.

The CMakeLists sample is as follows:

cmake_minimum_required(VERSION 3.5)
PROJECT(UDF)
if ("x${RESOURCE_TYPE}" STREQUAL "xAscend")
  message(STATUS "ascend compiler enter")
  # if unsupport current resource type, please uncomment the next line.
  # message(FATAL_ERROR "Unsupport compile Ascend target!")
elseif("x${RESOURCE_TYPE}" STREQUAL "xAarch")
  message(STATUS "aarch64 compiler enter")
  # if unsupport current resource type, please uncomment the next line.
  # message(FATAL_ERROR "Unsupport compile Aarch64 target!")
else()
  message(STATUS "x86 compiler enter")
  # if unsupport current resource type, please uncomment the next line.
  # message(FATAL_ERROR "Unsupport compile X86 target!")
endif()

if (DEFINED ENV{ASCEND_HOME_PATH})
    set(ASCEND_HOME_PATH $ENV{ASCEND_HOME_PATH})
    message(STATUS "Read ASCEND_HOME_PATH from ENV: ${ASCEND_HOME_PATH}")
else ()
    message(FATAL_ERROR "ASCEND_HOME_PATH is not set, please export ASCEND_HOME_PATH based on actual installation path.")
endif ()

# set dynamic library output path
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/${RELEASE_DIR})
# set static library output path
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/${RELEASE_DIR})

message(STATUS "CMAKE_LIBRARY_OUTPUT_DIRECTORY= ${CMAKE_LIBRARY_OUTPUT_DIRECTORY}")

set(INC_DIR "${ASCEND_HOME_PATH}/include")
file(GLOB SRC_LIST "*.cpp")

# Specify cross compiler
add_definitions(-D_GLIBCXX_USE_CXX11_ABI=0)

# set c++ compiler
set(CMAKE_CXX_COMPILER ${TOOLCHAIN})

# =========================UDF so compile============================
# check if SRC_LIST is exist
if("x${SRC_LIST}" STREQUAL "x")
    message(UDF "=========no source file=============")
    add_custom_target(${UDF_TARGET_LIB}
        COMMAND echo "no source to make lib${UDF_TARGET_LIB}.so")
    return(0)
endif()

add_library(${UDF_TARGET_LIB} SHARED
  ${SRC_LIST}
)

target_include_directories(${UDF_TARGET_LIB} PRIVATE
  ${INC_DIR}
)

target_compile_options(${UDF_TARGET_LIB} PRIVATE
  -O2
  -std=c++11
  -ftrapv  
  -fstack-protector-all
  -fPIC
)

if ("x${RESOURCE_TYPE}" STREQUAL "xAscend")
  target_link_libraries(${UDF_TARGET_LIB} PRIVATE 
    -Wl,--whole-archive
    ${ASCEND_HOME_PATH}/devlib/device/libflow_func.so
    -Wl,--no-whole-archive
  )
  # If there have any dependent so, please release the following comments and copy dependent so to ${PROJECT_BINARY_DIR}/${RELEASE_DIR}
  # [[execute_process(
    COMMAND cp libdepend_xxx.so ${PROJECT_BINARY_DIR}/${RELEASE_DIR}
  )]]
elseif("x${RESOURCE_TYPE}" STREQUAL "xAarch")
  target_link_libraries(${UDF_TARGET_LIB} PRIVATE 
    -Wl,--whole-archive
    ${ASCEND_HOME_PATH}/devlib/linux/aarch64/libflow_func.so
    -Wl,--no-whole-archive
  )
  # If there have any dependent so, please release the following comments and copy dependent so to ${PROJECT_BINARY_DIR}/${RELEASE_DIR}
  # [[execute_process(
    COMMAND cp libdepend_xxx.so ${PROJECT_BINARY_DIR}/${RELEASE_DIR}
  )]]
else()
  target_link_libraries(${UDF_TARGET_LIB} PRIVATE 
    -Wl,--whole-archive
    ${ASCEND_HOME_PATH}/devlib/linux/x86_64/libflow_func.so
    -Wl,--no-whole-archive
  )
  # If there have any dependent so, please release the following comments and copy dependent so to ${PROJECT_BINARY_DIR}/${RELEASE_DIR}
  # [[execute_process(
    COMMAND cp libdepend_xxx.so ${PROJECT_BINARY_DIR}/${RELEASE_DIR}
  )]]
endif()

Returns

None is returned in normal scenarios.

TypeError is returned when the parameter type is incorrect.

Examples

import dataflow as df
pp = df.FuncProcessPoint(...)

Constraints

None

Parent topic: dataflow.FuncProcessPoint