Embedding Julia

We start with a simple C program that initializes Julia and calls some Julia code:

In order to build this program you must add the path to the Julia header to the include path and link against libjulia. For instance, when Julia is installed to $JULIA_DIR, one can compile the above test program test.c with gcc using:

Alternatively, look at the embedding.c program in the Julia source tree in the test/embedding/ folder. The file cli/loader_exe.c program is another simple example of how to set jl_options options while linking against libjulia.

The first thing that must be done before calling any other Julia C function is to initialize Julia. This is done by calling jl_init, which tries to automatically determine Julia’s install location. If you need to specify a custom location, or specify which system image to load, use jl_init_with_image instead.

The second statement in the test program evaluates a Julia statement using a call to jl_eval_string.

Before the program terminates, it is strongly recommended that jl_atexit_hook is called. The above example program calls this just before returning from main.

If the JULIA_DIR environment variable hasn’t been setup, add it using the System panel before starting Visual Studio. The bin folder under JULIA_DIR should be on the system PATH.

We start by opening Visual Studio and creating a new Console Application project. Open the 'stdafx.h' header file, and add the following lines at the end:

Then, replace the main() function in the project with this code:

The next step is to set up the project to find the Julia include files and the libraries. It’s important to know whether the Julia installation is 32- or 64-bit. Remove any platform configuration that doesn’t correspond to the Julia installation before proceeding.

At this point, the project should build and run.

Real applications will not only need to execute expressions, but also return their values to the host program. jl_eval_string returns a jl_value_t*, which is a pointer to a heap-allocated Julia object. Storing simple data types like Float64 in this way is called boxing, and extracting the stored primitive data is called unboxing. Our improved sample program that calculates the square root of 2 in Julia and reads back the result in C has a body that now contains this code:

In order to check whether ret is of a specific Julia type, we can use the jl_isa, jl_typeis, or jl_is_... functions. By typing typeof(sqrt(2.0)) into the Julia shell we can see that the return type is Float64 (double in C). To convert the boxed Julia value into a C double the jl_unbox_float64 function is used in the above code snippet.

Corresponding jl_box_... functions are used to convert the other way:

As we will see next, boxing is required to call Julia functions with specific arguments.

While jl_eval_string allows C to obtain the result of a Julia expression, it does not allow passing arguments computed in C to Julia. For this you will need to invoke Julia functions directly, using jl_call:

In the first step, a handle to the Julia function sqrt is retrieved by calling jl_get_function. The first argument passed to jl_get_function is a pointer to the Base module in which sqrt is defined. Then, the double value is boxed using jl_box_float64. Finally, in the last step, the function is called using jl_call1. jl_call0, jl_call2, and jl_call3 functions also exist, to conveniently handle different numbers of arguments. To pass more arguments, use jl_call:

Its second argument args is an array of jl_value_t* arguments and nargs is the number of arguments.

There is also an alternative, possibly simpler, way of calling Julia functions and that is via @cfunction. Using @cfunction allows you to do the type conversions on the Julia side which typically is easier than doing it on the C side. The sqrt example above would with @cfunction be written as:

where we first define a C callable function in Julia, extract the function pointer from it and finally call it.

As we have seen, Julia objects are represented in C as pointers of type jl_value_t*. This raises the question of who is responsible for freeing these objects.

Typically, Julia objects are freed by the garbage collector (GC), but the GC does not automatically know that we are holding a reference to a Julia value from C. This means the GC can free objects out from under you, rendering pointers invalid.

The GC will only run when new Julia objects are being allocated. Calls like jl_box_float64 perform allocation, but allocation might also happen at any point in running Julia code.

When writing code that embeds Julia, it is generally safe to use jl_value_t* values in between jl_... calls (as GC will only get triggered by those calls). But in order to make sure that values can survive jl_... calls, we have to tell Julia that we still hold a reference to Julia root values, a process called "GC rooting". Rooting a value will ensure that the garbage collector does not accidentally identify this value as unused and free the memory backing that value. This can be done using the JL_GC_PUSH macros:

The JL_GC_POP call releases the references established by the previous JL_GC_PUSH. Note that JL_GC_PUSH stores references on the C stack, so it must be exactly paired with a JL_GC_POP before the scope is exited. That is, before the function returns, or control flow otherwise leaves the block in which the JL_GC_PUSH was invoked.

Several Julia values can be pushed at once using the JL_GC_PUSH2 to JL_GC_PUSH6 macros:

To push an array of Julia values one can use the JL_GC_PUSHARGS macro, which can be used as follows:

Each scope must have only one call to JL_GC_PUSH*, and should be paired with only a single JL_GC_POP call. If all necessary variables you want to root cannot be pushed by a one single call to JL_GC_PUSH*, or if there are more than 6 variables to be pushed and using an array of arguments is not an option, then one can use inner blocks:

Note that it is not necessary to have valid jl_value_t* values before calling JL_GC_PUSH*. It is fine to have a number of them initialized to NULL, pass those to JL_GC_PUSH* and then create the actual Julia values. For example:

If it is required to hold the pointer to a variable between functions (or block scopes), then it is not possible to use JL_GC_PUSH*. In this case, it is necessary to create and keep a reference to the variable in the Julia global scope. One simple way to accomplish this is to use a global IdDict that will hold the references, avoiding deallocation by the GC. However, this method will only work properly with mutable types.

If the variable is immutable, then it needs to be wrapped in an equivalent mutable container or, preferably, in a RefValue{Any} before it is pushed to IdDict. In this approach, the container has to be created or filled in via C code using, for example, the function jl_new_struct. If the container is created by jl_call*, then you will need to reload the pointer to be used in C code.

The GC can be allowed to deallocate a variable by removing the reference to it from refs using the function delete!, provided that no other reference to the variable is kept anywhere:

As an alternative for very simple cases, it is possible to just create a global container of type Vector{Any} and fetch the elements from that when necessary, or even to create one global variable per pointer using

Julia and C can share array data without copying. The next example will show how this works.

Julia arrays are represented in C by the datatype jl_array_t*. Basically, jl_array_t is a struct that contains:

To keep things simple, we start with a 1D array. Creating an array containing Float64 elements of length 10 can be done like this:

Alternatively, if you have already allocated the array you can generate a thin wrapper around its data:

The last argument is a boolean indicating whether Julia should take ownership of the data. If this argument is non-zero, the GC will call free on the data pointer when the array is no longer referenced.

In order to access the data of x, we can use jl_array_data:

Now we can fill the array:

Now let us call a Julia function that performs an in-place operation on x:

By printing the array, one can verify that the elements of x are now reversed.

Julia code can throw exceptions. For example, consider:

This call will appear to do nothing. However, it is possible to check whether an exception was thrown:

If you are using the Julia C API from a language that supports exceptions (e.g. Python, C#, C++), it makes sense to wrap each call into libjulia with a function that checks whether an exception was thrown, and then rethrows the exception in the host language.