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：此参数指示结果是否可能为空（基于输入参数的可空性）。它可以取以下值之一：

    • 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 函数需要函数持有者时创建函数持有者。请查看 gandiva::FunctionHolder 类及其多个子类以获取更多详细信息。

外部 IR 函数#

IR 函数实现#

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

编译示例与工具#

  1. 使用 C++ 或 C

    • 如果您的 IR 函数是用 C++ 或 C 实现的，它们可以被编译成 LLVM 位码 (bitcode)，这是 Gandiva 可识别的中间表示。

    • 使用 Clang 编译：对于 C++ 实现，您可以使用带有 -emit-llvm 选项的 clang。此方法直接将您的 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 的文档以及源代码中的示例实现。