在 GitHub 上编辑

嵌入 Julia

正如我们在调用 C 和 Fortran 代码中看到的，Julia 有一种简单而高效的方法来调用用 C 编写的函数。但是，在某些情况下需要相反的操作：从 C 代码中调用 Julia 函数。这可以用于将 Julia 代码集成到更大的 C/C++ 项目中，而无需将所有内容都重写为 C/C++。Julia 提供了一个 C API 来实现这一点。由于几乎所有编程语言都有一些方法可以调用 C 函数，因此 Julia C API 也可以用于构建更进一步的语言桥接（例如，从 Python、Rust 或 C# 调用 Julia）。即使 Rust 和 C++ 可以直接使用 C 嵌入 API，两者都有一些包可以帮助实现这一点，对于 C++，Jluna 很有用。

高级嵌入

注意：本节介绍如何在类 Unix 操作系统上将 Julia 代码嵌入到 C 中。要在 Windows 上执行此操作，请参阅下一节使用 Visual Studio 在 Windows 上进行高级嵌入。

我们从一个简单的 C 程序开始，该程序初始化 Julia 并调用一些 Julia 代码

#include <julia.h>
JULIA_DEFINE_FAST_TLS // only define this once, in an executable (not in a shared library) if you want fast code.

int main(int argc, char *argv[])
{
    /* required: setup the Julia context */
    jl_init();

    /* run Julia commands */
    jl_eval_string("print(sqrt(2.0))");

    /* strongly recommended: notify Julia that the
         program is about to terminate. this allows
         Julia time to cleanup pending write requests
         and run all finalizers
    */
    jl_atexit_hook(0);
    return 0;
}

为了构建此程序，您必须将 Julia 头文件的路径添加到包含路径并链接到 libjulia。例如，当 Julia 安装到 $JULIA_DIR 时，可以使用 gcc 编译上述测试程序 test.c：

gcc -o test -fPIC -I$JULIA_DIR/include/julia -L$JULIA_DIR/lib -Wl,-rpath,$JULIA_DIR/lib test.c -ljulia

或者，查看 Julia 源代码树中 test/embedding/ 文件夹中的 embedding.c 程序。文件 cli/loader_exe.c 程序是另一个关于如何在链接到 libjulia 时设置 jl_options 选项的简单示例。

在调用任何其他 Julia C 函数之前，必须首先完成的第一件事是初始化 Julia。这是通过调用 jl_init 完成的，它尝试自动确定 Julia 的安装位置。如果您需要指定自定义位置或指定要加载的系统镜像，请改用 jl_init_with_image。

测试程序中的第二个语句使用对 jl_eval_string 的调用来评估一个 Julia 语句。

在程序终止之前，强烈建议调用 jl_atexit_hook。上面的示例程序在从 main 返回之前调用了此函数。

注意

当前，使用 libjulia 共享库进行动态链接需要传递 RTLD_GLOBAL 选项。在 Python 中，它看起来像这样：

>>> julia=CDLL('./libjulia.dylib',RTLD_GLOBAL)
>>> julia.jl_init.argtypes = []
>>> julia.jl_init()
250593296
注意

如果 julia 程序需要访问主可执行文件中的符号，则可能需要在 Linux 上的编译时添加 -Wl,--export-dynamic 链接器标志，此外还需要 julia-config.jl 下面描述的标志。在编译共享库时，不需要这样做。

使用 julia-config 自动确定构建参数

创建 julia-config.jl 脚本是为了帮助确定使用嵌入式 Julia 的程序所需的构建参数。此脚本使用调用它的特定 Julia 发行版的构建参数和系统配置来导出嵌入程序与该发行版交互所需的必要编译器标志。此脚本位于 Julia 共享数据目录中。

示例

#include <julia.h>

int main(int argc, char *argv[])
{
    jl_init();
    (void)jl_eval_string("println(sqrt(2.0))");
    jl_atexit_hook(0);
    return 0;
}

在命令行上

此脚本的一个简单用法是从命令行。假设 julia-config.jl 位于 /usr/local/julia/share/julia 中，则可以直接在命令行上调用它，并接受任何三个标志的组合：

/usr/local/julia/share/julia/julia-config.jl
Usage: julia-config [--cflags|--ldflags|--ldlibs]

如果将上述示例源代码保存在文件 embed_example.c 中，则以下命令将将其编译成 Linux 和 Windows（MSYS2 环境）上的可执行程序。在 macOS 上，将 clang 替换为 gcc。

/usr/local/julia/share/julia/julia-config.jl --cflags --ldflags --ldlibs | xargs gcc embed_example.c

在 Makefile 中使用

通常，嵌入项目将比上面的示例更复杂，因此以下内容也允许通用 makefile 支持——假设使用 GNU make，因为使用了 shell 宏扩展。此外，尽管 julia-config.jl 通常位于 /usr/local 目录中，但如果不在，则 Julia 本身可以用来查找 julia-config.jl，并且 makefile 可以利用这一点。上面的示例扩展为使用 makefile：

JL_SHARE = $(shell julia -e 'print(joinpath(Sys.BINDIR, Base.DATAROOTDIR, "julia"))')
CFLAGS   += $(shell $(JL_SHARE)/julia-config.jl --cflags)
CXXFLAGS += $(shell $(JL_SHARE)/julia-config.jl --cflags)
LDFLAGS  += $(shell $(JL_SHARE)/julia-config.jl --ldflags)
LDLIBS   += $(shell $(JL_SHARE)/julia-config.jl --ldlibs)

all: embed_example

现在构建命令只需 make。

使用 Visual Studio 在 Windows 上进行高级嵌入

如果尚未设置 JULIA_DIR 环境变量，请在启动 Visual Studio 之前使用系统面板进行设置。JULIA_DIR 下的 bin 文件夹应位于系统 PATH 中。

我们首先打开 Visual Studio 并创建一个新的控制台应用程序项目。打开 'stdafx.h' 头文件，并在末尾添加以下行：

#include <julia.h>

然后，用以下代码替换项目中的 main() 函数：

int main(int argc, char *argv[])
{
    /* required: setup the Julia context */
    jl_init();

    /* run Julia commands */
    jl_eval_string("print(sqrt(2.0))");

    /* strongly recommended: notify Julia that the
         program is about to terminate. this allows
         Julia time to cleanup pending write requests
         and run all finalizers
    */
    jl_atexit_hook(0);
    return 0;
}

下一步是设置项目以查找 Julia 包含文件和库。了解 Julia 安装是 32 位还是 64 位非常重要。在继续之前，请删除与 Julia 安装不对应的任何平台配置。

使用项目属性对话框，转到 C/C++ | 常规 并将 $(JULIA_DIR)\include\julia\ 添加到“附加包含目录”属性中。然后，转到 链接器 | 常规 部分，并将 $(JULIA_DIR)\lib 添加到“附加库目录”属性中。最后，在 链接器 | 输入 下，将 libjulia.dll.a;libopenlibm.dll.a; 添加到库列表中。

此时，项目应该可以构建和运行。

转换类型

实际应用程序不仅需要执行表达式，还需要将其值返回给主机程序。jl_eval_string 返回一个 jl_value_t*，它是指向堆分配的 Julia 对象的指针。以这种方式存储简单的类型，例如Float64，称为 装箱，而提取存储的原始数据称为 拆箱。我们改进的示例程序在 Julia 中计算 2 的平方根并在 C 中读取结果，其主体现在包含以下代码：

jl_value_t *ret = jl_eval_string("sqrt(2.0)");

if (jl_typeis(ret, jl_float64_type)) {
    double ret_unboxed = jl_unbox_float64(ret);
    printf("sqrt(2.0) in C: %e \n", ret_unboxed);
}
else {
    printf("ERROR: unexpected return type from sqrt(::Float64)\n");
}

为了检查ret是否为特定的Julia类型，我们可以使用jl_isa、jl_typeis或jl_is_...函数。通过在Julia shell中输入typeof(sqrt(2.0))，我们可以看到返回类型是Float64（C语言中的double）。为了将封装的Julia值转换为C语言的double，上述代码片段中使用了jl_unbox_float64函数。

相应的jl_box_...函数用于进行反向转换。

jl_value_t *a = jl_box_float64(3.0);
jl_value_t *b = jl_box_float32(3.0f);
jl_value_t *c = jl_box_int32(3);

正如我们接下来将看到的，封装是使用特定参数调用Julia函数所必需的。

调用Julia函数

虽然jl_eval_string允许C获取Julia表达式的结果，但它不允许将C中计算的参数传递给Julia。为此，您需要使用jl_call直接调用Julia函数。

jl_function_t *func = jl_get_function(jl_base_module, "sqrt");
jl_value_t *argument = jl_box_float64(2.0);
jl_value_t *ret = jl_call1(func, argument);

第一步，通过调用jl_get_function获取Julia函数sqrt的句柄。传递给jl_get_function的第一个参数是指向定义sqrt的Base模块的指针。然后，使用jl_box_float64将double值封装。最后，在最后一步中，使用jl_call1调用该函数。jl_call0、jl_call2和jl_call3函数也存在，以便方便地处理不同数量的参数。要传递更多参数，请使用jl_call。

jl_value_t *jl_call(jl_function_t *f, jl_value_t **args, int32_t nargs)

它的第二个参数args是一个jl_value_t*参数数组，nargs是参数的数量。

还有一种替代方法，可能更简单，可以调用Julia函数，那就是通过@cfunction。使用@cfunction允许您在Julia端进行类型转换，这通常比在C端进行类型转换更容易。上面的sqrt示例将使用@cfunction编写为

double (*sqrt_jl)(double) = jl_unbox_voidpointer(jl_eval_string("@cfunction(sqrt, Float64, (Float64,))"));
double ret = sqrt_jl(2.0);

在这里，我们首先在Julia中定义一个C可调用函数，从中提取函数指针，最后调用它。

内存管理

正如我们所看到的，Julia对象在C中表示为类型为jl_value_t*的指针。这就引出了一个问题，谁负责释放这些对象。

通常，Julia对象由垃圾收集器（GC）释放，但GC不会自动知道我们从C持有对Julia值的引用。这意味着GC可能会从您的控制下释放对象，从而使指针无效。

GC仅在分配新的Julia对象时运行。像jl_box_float64这样的调用会执行分配，但分配也可能在运行Julia代码的任何时候发生。

在编写嵌入Julia的代码时，在jl_...调用之间使用jl_value_t*值通常是安全的（因为GC只会由这些调用触发）。但是，为了确保值能够在jl_...调用中存活下来，我们必须告诉Julia我们仍然持有对Julia根值的引用，这个过程称为“GC根化”。根化一个值将确保垃圾收集器不会意外地将该值识别为未使用的值并释放该值所支持的内存。这可以通过使用JL_GC_PUSH宏来实现。

jl_value_t *ret = jl_eval_string("sqrt(2.0)");
JL_GC_PUSH1(&ret);
// Do something with ret
JL_GC_POP();

JL_GC_POP调用释放先前JL_GC_PUSH建立的引用。请注意，JL_GC_PUSH在C栈上存储引用，因此它必须在作用域退出之前与JL_GC_POP完全配对。也就是说，在函数返回之前，或控制流以其他方式离开调用JL_GC_PUSH的块。

可以使用JL_GC_PUSH2到JL_GC_PUSH6宏一次推送多个Julia值。

JL_GC_PUSH2(&ret1, &ret2);
// ...
JL_GC_PUSH6(&ret1, &ret2, &ret3, &ret4, &ret5, &ret6);

要推送Julia值的数组，可以使用JL_GC_PUSHARGS宏，使用方法如下

jl_value_t **args;
JL_GC_PUSHARGS(args, 2); // args can now hold 2 `jl_value_t*` objects
args[0] = some_value;
args[1] = some_other_value;
// Do something with args (e.g. call jl_... functions)
JL_GC_POP();

每个作用域只能有一个对JL_GC_PUSH*的调用，并且应该只与一个JL_GC_POP调用配对。如果所有需要根化的变量都不能通过对JL_GC_PUSH*的一次调用来推送，或者有超过6个变量需要推送并且使用参数数组不是一种选择，那么可以使用内部块。

jl_value_t *ret1 = jl_eval_string("sqrt(2.0)");
JL_GC_PUSH1(&ret1);
jl_value_t *ret2 = 0;
{
    jl_function_t *func = jl_get_function(jl_base_module, "exp");
    ret2 = jl_call1(func, ret1);
    JL_GC_PUSH1(&ret2);
    // Do something with ret2.
    JL_GC_POP();    // This pops ret2.
}
JL_GC_POP();    // This pops ret1.

请注意，在调用JL_GC_PUSH*之前，不需要有有效的jl_value_t*值。可以将其中一些初始化为NULL，将它们传递给JL_GC_PUSH*，然后创建实际的Julia值。例如

jl_value_t *ret1 = NULL, *ret2 = NULL;
JL_GC_PUSH2(&ret1, &ret2);
ret1 = jl_eval_string("sqrt(2.0)");
ret2 = jl_eval_string("sqrt(3.0)");
// Use ret1 and ret2
JL_GC_POP();

如果需要在函数（或块作用域）之间保存指向变量的指针，则无法使用JL_GC_PUSH*。在这种情况下，需要在Julia全局作用域中创建并保留对该变量的引用。实现此目的的一种简单方法是使用一个全局IdDict来保存引用，避免GC释放。但是，此方法仅适用于可变类型。

// This functions shall be executed only once, during the initialization.
jl_value_t* refs = jl_eval_string("refs = IdDict()");
jl_function_t* setindex = jl_get_function(jl_base_module, "setindex!");

...

// `var` is the variable we want to protect between function calls.
jl_value_t* var = 0;

...

// `var` is a `Vector{Float64}`, which is mutable.
var = jl_eval_string("[sqrt(2.0); sqrt(4.0); sqrt(6.0)]");

// To protect `var`, add its reference to `refs`.
jl_call3(setindex, refs, var, var);

如果变量是不可变的，则需要将其包装在等效的可变容器中，或者最好包装在RefValue{Any}中，然后再将其推送到IdDict。在这种方法中，容器必须通过C代码创建或填充，例如使用函数jl_new_struct。如果容器由jl_call*创建，则需要重新加载要用于C代码的指针。

// This functions shall be executed only once, during the initialization.
jl_value_t* refs = jl_eval_string("refs = IdDict()");
jl_function_t* setindex = jl_get_function(jl_base_module, "setindex!");
jl_datatype_t* reft = (jl_datatype_t*)jl_eval_string("Base.RefValue{Any}");

...

// `var` is the variable we want to protect between function calls.
jl_value_t* var = 0;

...

// `var` is a `Float64`, which is immutable.
var = jl_eval_string("sqrt(2.0)");

// Protect `var` until we add its reference to `refs`.
JL_GC_PUSH1(&var);

// Wrap `var` in `RefValue{Any}` and push to `refs` to protect it.
jl_value_t* rvar = jl_new_struct(reft, var);
JL_GC_POP();

jl_call3(setindex, refs, rvar, rvar);

可以通过使用函数delete!从refs中删除对变量的引用来允许GC释放变量，前提是任何其他地方都没有保留对该变量的引用。

jl_function_t* delete = jl_get_function(jl_base_module, "delete!");
jl_call2(delete, refs, rvar);

作为非常简单情况的替代方案，可以只创建一个类型为Vector{Any}的全局容器，并在需要时从中获取元素，甚至可以使用以下方法为每个指针创建一个全局变量。

jl_module_t *mod = jl_main_module;
jl_sym_t *var = jl_symbol("var");
jl_binding_t *bp = jl_get_binding_wr(mod, var);
jl_checked_assignment(bp, mod, var, val);

更新GC管理对象的字段

垃圾收集器还在这样的假设下运行：它知道每个指向年轻一代对象的旧一代对象。任何时候指针更新破坏了该假设，都必须使用jl_gc_wb（写屏障）函数向收集器发出信号，如下所示。

jl_value_t *parent = some_old_value, *child = some_young_value;
((some_specific_type*)parent)->field = child;
jl_gc_wb(parent, child);

通常不可能预测运行时哪些值将是旧的，因此必须在所有显式存储之后插入写屏障。一个值得注意的例外是，如果parent对象刚刚被分配，并且从那时起没有运行垃圾收集。请注意，大多数jl_...函数有时会调用垃圾收集。

当直接更新指针数组的数据时，写屏障也是必要的。例如

jl_array_t *some_array = ...; // e.g. a Vector{Any}
void **data = (void**)jl_array_data(some_array);
jl_value_t *some_value = ...;
data[0] = some_value;
jl_gc_wb(some_array, some_value);

控制垃圾收集器

有一些函数可以控制GC。在正常使用情况下，这些函数不应是必需的。

函数描述
jl_gc_collect()强制运行GC
jl_gc_enable(0)禁用GC，以int形式返回先前的状态
jl_gc_enable(1)启用GC，以int形式返回先前的状态
jl_gc_is_enabled()以int形式返回当前状态

使用数组

Julia和C可以共享数组数据而无需复制。下面的示例将展示其工作原理。

Julia数组在C中由数据类型jl_array_t*表示。基本上，jl_array_t是一个包含以下内容的结构体：

  • 有关数据类型的信息
  • 指向数据块的指针
  • 有关数组大小的信息

为了简单起见，我们从一维数组开始。创建包含长度为10的Float64元素的数组可以这样完成：

jl_value_t* array_type = jl_apply_array_type((jl_value_t*)jl_float64_type, 1);
jl_array_t* x          = jl_alloc_array_1d(array_type, 10);

或者，如果您已经分配了数组，则可以围绕其数据生成一个薄包装器。

double *existingArray = (double*)malloc(sizeof(double)*10);
jl_array_t *x = jl_ptr_to_array_1d(array_type, existingArray, 10, 0);

最后一个参数是一个布尔值，指示Julia是否应获取数据的所有权。如果此参数非零，则GC将在数组不再被引用时对数据指针调用free。

为了访问x的数据，我们可以使用jl_array_data。

double *xData = (double*)jl_array_data(x);

现在我们可以填充数组了。

for(size_t i=0; i<jl_array_len(x); i++)
    xData[i] = i;

现在让我们调用一个Julia函数，该函数对x执行就地操作。

jl_function_t *func = jl_get_function(jl_base_module, "reverse!");
jl_call1(func, (jl_value_t*)x);

通过打印数组，可以验证x的元素现在是否已反转。

访问返回的数组

如果Julia函数返回一个数组，则jl_eval_string和jl_call的返回值可以转换为jl_array_t*。

jl_function_t *func  = jl_get_function(jl_base_module, "reverse");
jl_array_t *y = (jl_array_t*)jl_call1(func, (jl_value_t*)x);

现在可以使用jl_array_data像以前一样访问y的内容。与往常一样，请确保在使用数组时保留对它的引用。

多维数组

Julia的多维数组以列主序存储在内存中。以下是一些创建二维数组并访问其属性的代码。

// Create 2D array of float64 type
jl_value_t *array_type = jl_apply_array_type((jl_value_t*)jl_float64_type, 2);
jl_array_t *x  = jl_alloc_array_2d(array_type, 10, 5);

// Get array pointer
double *p = (double*)jl_array_data(x);
// Get number of dimensions
int ndims = jl_array_ndims(x);
// Get the size of the i-th dim
size_t size0 = jl_array_dim(x,0);
size_t size1 = jl_array_dim(x,1);

// Fill array with data
for(size_t i=0; i<size1; i++)
    for(size_t j=0; j<size0; j++)
        p[j + size0*i] = i + j;

请注意，虽然Julia数组使用基于1的索引，但C API使用基于0的索引（例如在调用jl_array_dim时）以便读取为惯用的C代码。

异常

Julia代码可以抛出异常。例如，考虑一下

jl_eval_string("this_function_does_not_exist()");

此调用似乎什么也不做。但是，可以检查是否抛出了异常。

if (jl_exception_occurred())
    printf("%s \n", jl_typeof_str(jl_exception_occurred()));

如果您正在从支持异常的语言（例如Python、C#、C++）使用Julia C API，则将对libjulia的每个调用包装到一个检查是否抛出了异常的函数中，然后在主机语言中重新抛出异常是有意义的。

抛出Julia异常

在编写Julia可调用函数时，可能需要验证参数并抛出异常以指示错误。一个典型的类型检查如下所示：

if (!jl_typeis(val, jl_float64_type)) {
    jl_type_error(function_name, (jl_value_t*)jl_float64_type, val);
}

可以使用以下函数引发常规异常：

void jl_error(const char *str);
void jl_errorf(const char *fmt, ...);

jl_error接受一个C字符串，jl_errorf的调用方式类似于printf。

jl_errorf("argument x = %d is too large", x);

在此示例中，假设x是一个整数。

线程安全

通常，Julia C API不是完全线程安全的。在将Julia嵌入到多线程应用程序中时，需要注意不要违反以下限制。

  • jl_init()只能在应用程序的生命周期中调用一次。jl_atexit_hook()也一样，它只能在jl_init()之后调用。

  • jl_...() API 函数只能在调用 jl_init() 的线程中调用，或在 Julia 运行时启动的线程中调用。从用户启动的线程调用 Julia API 函数不受支持，可能会导致未定义的行为和崩溃。

上述第二个条件意味着您不能安全地从非 Julia 启动的线程（调用 jl_init() 的线程除外）调用 jl_...() 函数。例如，以下操作不受支持，并且很可能会导致段错误

void *func(void*)
{
    // Wrong, jl_eval_string() called from thread that was not started by Julia
    jl_eval_string("println(Threads.threadid())");
    return NULL;
}

int main()
{
    pthread_t t;

    jl_init();

    // Start a new thread
    pthread_create(&t, NULL, func, NULL);
    pthread_join(t, NULL);

    jl_atexit_hook(0);
}

相反，从同一个用户创建的线程执行所有 Julia 调用将可以正常工作

void *func(void*)
{
    // Okay, all jl_...() calls from the same thread,
    // even though it is not the main application thread
    jl_init();
    jl_eval_string("println(Threads.threadid())");
    jl_atexit_hook(0);
    return NULL;
}

int main()
{
    pthread_t t;
    // Create a new thread, which runs func()
    pthread_create(&t, NULL, func, NULL);
    pthread_join(t, NULL);
}

从 Julia 本身启动的线程调用 Julia C API 的示例

#include <julia/julia.h>
JULIA_DEFINE_FAST_TLS

double c_func(int i)
{
    printf("[C %08x] i = %d\n", pthread_self(), i);

    // Call the Julia sqrt() function to compute the square root of i, and return it
    jl_function_t *sqrt = jl_get_function(jl_base_module, "sqrt");
    jl_value_t* arg = jl_box_int32(i);
    double ret = jl_unbox_float64(jl_call1(sqrt, arg));

    return ret;
}

int main()
{
    jl_init();

    // Define a Julia function func() that calls our c_func() defined in C above
    jl_eval_string("func(i) = ccall(:c_func, Float64, (Int32,), i)");

    // Call func() multiple times, using multiple threads to do so
    jl_eval_string("println(Threads.threadpoolsize())");
    jl_eval_string("use(i) = println(\"[J $(Threads.threadid())] i = $(i) -> $(func(i))\")");
    jl_eval_string("Threads.@threads for i in 1:5 use(i) end");

    jl_atexit_hook(0);
}

如果我们使用 2 个 Julia 线程运行此代码，我们将得到以下输出（注意：输出会因运行和系统而异）

$ JULIA_NUM_THREADS=2 ./thread_example
2
[C 3bfd9c00] i = 1
[C 23938640] i = 4
[J 1] i = 1 -> 1.0
[C 3bfd9c00] i = 2
[J 1] i = 2 -> 1.4142135623730951
[C 3bfd9c00] i = 3
[J 2] i = 4 -> 2.0
[C 23938640] i = 5
[J 1] i = 3 -> 1.7320508075688772
[J 2] i = 5 -> 2.23606797749979

可以看到，Julia 线程 1 对应于 pthread ID 3bfd9c00，Julia 线程 2 对应于 ID 23938640，这表明确实在 C 层使用了多个线程，并且我们可以安全地从这些线程调用 Julia C API 例程。