Gandiva 外部函数开发指南#

简介#

Gandiva 作为一个分析表达式编译框架，通过外部函数扩展其功能。本指南专注于帮助开发人员了解、创建和将外部函数集成到 Gandiva 中。外部函数是用户定义的第三方函数，可以在 Gandiva 表达式中使用。

Gandiva 中外部函数类型的概述#

Gandiva 支持两种主要的外部函数类型

  • C 函数：符合 C 调用约定的函数。开发人员可以使用各种语言（如 C++、Rust、C 或 Zig）实现函数，并将它们作为 C 函数公开给 Gandiva。

  • IR 函数：在 LLVM 中间表示 (LLVM IR) 中实现的函数。这些函数可以用多种语言编写，然后编译成 LLVM IR 以注册到 Gandiva 中。

为您的需求选择正确的外部函数类型#

将外部函数集成到 Gandiva 时，务必选择最符合您特定需求的类型。以下是 C 函数和 IR 函数之间的主要区别，以指导您的决策

  • C 函数

    • 语言灵活性：C 函数提供了在首选编程语言中实现逻辑的灵活性，随后将其作为 C 函数公开。

    • 广泛的适用性：由于它们的兼容性和易于集成，它们通常是各种用例的首选。

  • IR 函数

    • 推荐的使用场景：IR 函数擅长处理不需要复杂逻辑或依赖复杂第三方库的简单任务。与 C 函数不同，IR 函数具有内联的优势，这对于简单的操作特别有用，在这些操作中，调用开销构成了重大的开支。此外，它们是已经与 LLVM 工具链集成的项目的理想选择。

    • IR 编译要求：对于 IR 函数，整个实现，包括使用的任何第三方库，都必须编译成 LLVM IR。这可能会影响性能，尤其是在依赖库很复杂的情况下。

    • 功能限制：某些高级功能（例如使用线程局部变量）在 IR 函数中不受支持。这是由于 Gandiva 内部使用的当前 JIT（即时）引擎的限制。

External C functions and IR functions integrating with Gandiva

外部函数注册#

要使函数可用于 Gandiva，您需要将其注册为外部函数，同时向 Gandiva 提供函数的元数据及其实现。

使用 NativeFunction 类进行元数据注册#

要在 Gandiva 中注册函数，请使用 gandiva::NativeFunction 类。此类捕获外部函数的签名和元数据。

gandiva::NativeFunction 的构造函数详细信息

NativeFunction(const std::string& base_name, const std::vector<std::string>& aliases,
               const DataTypeVector& param_types, const DataTypePtr& ret_type,
               the ResultNullableType& result_nullable_type, std::string pc_name,
               int32_t flags = 0);

NativeFunction 类用于定义外部函数的元数据。以下是其构造函数参数的细分

  • base_name：函数的名称，将在表达式中使用。

  • aliases：函数的替代名称列表。

  • param_types：arrow::DataType 对象的向量，表示函数接受的参数的类型。

  • ret_type：std::shared_ptr<arrow::DataType>，表示函数的返回类型。

  • result_nullable_type：此参数指示结果是否可以为 null，具体取决于输入参数的可空性。它可以采用以下值之一

    • ResultNullableType::kResultNullIfNull：结果有效性是子级有效性的交集。

    • ResultNullableType::kResultNullNever：结果始终有效。

    • ResultNullableType::kResultNullInternal：结果有效性取决于某些内部逻辑。

  • pc_name：相应预编译函数的名称。* 通常，此名称遵循约定 {base_name} + _{param1_type} + {param2_type} + … + {paramN_type}。例如，如果基本名称为 add 并且函数接受两个 int32 参数并返回一个 int32，则预编译函数名称将为 add_int32_int32，但只要您可以保证其唯一性，此约定不是强制性的。

  • flags：用于附加函数属性的可选标志（默认为 0）。请查看 NativeFunction::kNeedsContext、NativeFunction::kNeedsFunctionHolder 和 NativeFunction::kCanReturnErrors 以了解更多详细信息。

注册函数后，需要通过 C 函数指针或 LLVM IR 函数提供其实现。

外部 C 函数#

外部 C 函数可以使用不同的语言编写并公开为 C 函数。与 Gandiva 的类型系统兼容至关重要。

C 函数签名#

签名映射#

并非所有 Arrow 数据类型都受 Gandiva 支持。下表列出了 Gandiva 外部函数签名类型与 C 函数签名类型之间的映射

Gandiva 类型 (arrow 数据类型)

C 函数类型

int8

int8_t

int16

int16_t

int32

int32_t

int64

int64_t

uint8

uint8_t

uint16

uint16_t

uint32

uint32_t

uint64

uint64_t

float32

float

float64

double

boolean

bool

date32

int32_t

date64

int64_t

timestamp

int64_t

time32

int32_t

time64

int64_t

interval_month

int32_t

interval_day_time

int64_t

utf8（作为参数类型）

const char*，uint32_t [参见下一节]

utf8（作为返回类型）

int64_t context，const char*，uint32_t* [参见下一节]

binary（作为参数类型）

const char*，uint32_t [参见下一节]

utf8（作为返回类型）

int64_t context，const char*，uint32_t* [参见下一节]
处理 arrow::StringType (utf8 类型) 和 arrow::BinaryType#

arrow::StringType 和 arrow::BinaryType 都是可变长度类型。并且它们在外部函数中的处理方式类似。由于 arrow::StringType (utf8 类型) 使用更广泛，因此我们将在下面使用它作为示例来解释如何在外部函数中处理可变长度类型。

在外部函数中使用 arrow::StringType（也称为 utf8 类型）作为函数参数或返回值需要特殊处理。本节详细介绍如何处理 arrow::StringType。

作为参数

当 arrow::StringType 用作函数签名中的参数类型时，相应的 C 函数应定义为接受两个参数

  • const char*：此参数用作指向字符串数据的指针。

  • uint32_t：此参数表示字符串数据的长度。

作为返回类型

当 arrow::StringType (utf8 类型) 用作函数签名中的返回类型时，会应用一些特定的注意事项

  1. NativeFunction 元数据标志：* 此函数的 NativeFunction 元数据必须包含 NativeFunction::kNeedsContext 标志。此标志对于确保函数中正确的上下文管理至关重要。

  2. 函数参数

    • 上下文参数：C 函数应以一个额外的参数 int64_t context 开头。此参数对于函数内的上下文管理至关重要。

    • 字符串长度输出参数：该函数还应在末尾包含一个 uint32_t* 参数。此输出参数将存储返回的字符串数据的长度。

  3. 返回值：该函数应返回一个 const char* 指针，指向字符串数据。

  4. 函数实现：* 内存分配和错误消息：在函数的实现中，分别使用 gdv_fn_context_arena_malloc 和 gdv_fn_context_set_error_msg 进行内存分配和错误消息传递。这两个函数都将 int64_t context 作为其第一个参数，以便有效地利用上下文。

外部 C 函数注册 API#

您可以使用 gandiva::FunctionRegistry 的 API 来注册外部 C 函数

/// \brief register a C function into the function registry
/// @param func the registered function's metadata
/// @param c_function_ptr the function pointer to the
/// registered function's implementation
/// @param function_holder_maker this will be used as the function holder if the
/// function requires a function holder
arrow::Status Register(
    NativeFunction func, void* c_function_ptr,
    std::optional<FunctionHolderMaker> function_holder_maker = std::nullopt);

以上 API 允许您注册外部 C 函数。

  • NativeFunction 对象描述外部 C 函数的元数据。

  • c_function_ptr 是指向外部 C 函数实现的函数指针。

  • 可选的 function_holder_maker 用于为外部 C 函数创建函数持有者，如果外部 C 函数需要函数持有者。查看 gandiva::FunctionHolder 类及其几个子类以了解更多详细信息。

外部 IR 函数#

IR 函数实现#

Gandiva 对 IR（中间表示）函数的支持提供了灵活性，允许您根据具体需求使用各种编程语言来实现这些函数。

编译示例和工具#

  1. 使用 C++ 或 C

    • 如果您的 IR 函数是用 C++ 或 C 实现的，则可以将其编译成 LLVM 位码，这是 Gandiva 理解的中间表示。

    • 使用 Clang 编译：对于 C++ 实现，您可以使用 clang 以及 -emit-llvm 选项。这种方法将您的 IR 函数直接编译成 LLVM 位码，使它们能够与 Gandiva 集成。

  2. 与 CMake 集成

    • 在 C++ 与 CMake 一起使用的项目中，请考虑利用 Arrow 存储库中的 GandivaAddBitcode.cmake 模块。此模块可以简化将自定义位码添加到 Gandiva 的过程。

参数和返回值类型的统一性#

务必与 C 函数中定义的参数和返回值类型保持一致。遵守上一节中讨论的规则可确保与 Gandiva 的类型系统兼容。

在 Gandiva 中注册外部 IR 函数#

  1. 实现和编译后

    成功将您的 IR 函数实现并编译成 LLVM 位码后，下一步关键步骤是在 Gandiva 中注册它们。

  2. 使用 Gandiva 的 FunctionRegistry API

    Gandiva 在 gandiva::FunctionRegistry 类中提供了特定的 API 来促进此注册过程。

    注册 API

    • 从位码文件注册

      // Registers a set of functions from a specified bitcode file
arrow::Status Register(const std::vector<NativeFunction>& funcs,
                       const std::string& bitcode_path);

    • 从位码缓冲区注册

      // Registers a set of functions from a bitcode buffer
arrow::Status Register(const std::vector<NativeFunction>& funcs,
                       std::shared_ptr<arrow::Buffer> bitcode_buffer);

    关键点

    • 这些 API 旨在从指定的位码文件或预加载的位码缓冲区注册一组外部 IR 函数。

    • 必须确保位码文件或缓冲区包含正确编译的 IR 函数。

    • NativeFunction 实例在此过程中发挥着至关重要的作用，用于定义正在注册的每个外部 IR 函数的元数据。

结论#

本指南概述了将外部函数集成到 Gandiva 的详细步骤。它涵盖了 C 和 IR 函数以及它们在 Gandiva 中的注册。对于更复杂的情况，请参阅 Gandiva 的文档和源代码中的示例实现。

本页面内容
在 GitHub 上编辑