use udf::prelude::*;

struct SumInt;

#[register]
impl BasicUdf for SumInt {
    type Returns<'a> = Option<i64>;

    fn init<'a>(
      cfg: &UdfCfg<Init>,
      args: &'a ArgList<'a, Init>
    ) -> Result<Self, String> {
      // ...
    }

    fn process<'a>(
        &'a mut self,
        cfg: &UdfCfg<Process>,
        args: &ArgList<Process>,
        error: Option<NonZeroU8>,
    ) -> Result<Self::Returns<'a>, ProcessError> {
      // ...
    }
}

编译

假设以上步骤已执行，所需做的只是为该项目生成一个C动态库。这可以通过在您的Cargo.toml文件中指定crate-type = ["cdylib"]来完成。之后，使用cargo build --release编译将会生成一个可加载的.so文件（位于target/release）。

重要版本说明：此crate依赖于名为泛型关联类型（GATs）的功能，该功能仅在rust >= 1.65的版本中可用。此版本刚刚稳定（2022-11-03），因此如果您遇到编译器问题，请务必运行rustup update。

CI在Linux和Windows上都运行测试，因此此crate应适用于任一平台。MacOS尚未经过测试，但可能也能正常工作。

符号检查

如果您想验证是否存在正确的C可调用函数，可以使用nm检查动态库。

# Output of example .so
$ nm -gC --defined-only target/release/libudf_examples.so
00000000000081b0 T avg_cost
0000000000008200 T avg_cost_add
00000000000081e0 T avg_cost_clear
0000000000008190 T avg_cost_deinit
0000000000008100 T avg_cost_init
0000000000009730 T is_const
0000000000009710 T is_const_deinit
0000000000009680 T is_const_init
0000000000009320 T sql_sequence
...

使用方法

编译完成后，需要将生成的目标文件复制到SQL变量plugin_dir的位置 - 通常这是/usr/lib/mysql/plugin/。

完成此操作后，在MariaDB/MySql中可以使用CREATE FUNCTION来加载它。

Docker使用

强烈建议在Docker中进行测试，以避免干扰主机SQL安装。有关如何操作的说明，请参阅udf-examples的readme。

示例

udf-examples crate包含了各种UDF的示例以及如何编译它们的说明。有关详细信息，请参阅该readme。

日志记录与调试说明

如果您需要在函数的正常使用过程中记录诸如警告之类的信息，任何打印到stderr的内容都将出现在服务器日志中（例如，如果使用Docker进行测试，可以通过docker logs mariadb_udf_test查看）。udf_log!宏将打印与SQL日志信息格式匹配的消息。您还可以启用crate功能logging-debug以进行函数入口/退出点调试，或启用logging-debug-calls以获取来自MariaDB/MySQL服务器的确切调用参数信息。

调试的最佳方法是使用udf::mock模块创建单元测试。这些测试可以运行以验证正确性，如果需要，也可以使用调试器逐步执行（这种情况可能相对较少）。所有类型都实现了Debug，因此也可以轻松打印（内置的dbg!宏将打印到stderr，因此这也会出现在日志中）。

dbg!(&self);
let arg0 = dbg!(args.get(0).unwrap())

[udf_examples/src/avgcost.rs:58] &self = AvgCost {
    count: 0,
    total_qty: 0,
    total_price: 0.0,
}

[udf_examples/src/avgcost.rs:60] args.get(0).unwrap() = SqlArg {
    value: Int(
        Some(
            10,
        ),
    ),
    attribute: "qty",
    maybe_null: true,
    arg_type: Cell {
        value: INT_RESULT,
    },
    marker: PhantomData<udf::traits::Process>,
}

许可证

自版本0.5.1起，此作品采用Apache 2.0和GPL 2.0（或任何后续版本）双重许可。如果您使用此作品，可以选择其中之一。

SPDX-许可证-标识符:Apache-2.0 或 GPL-2.0-或-后续版本