Julia Code Implementation

Note. This section provides information about the implementation of Julia code in C on operating systems like Unix. For information about performing this task on Windows, see High-level implementation in Windows using Visual Studio.

Let’s start with a simple C program that initializes Julia and calls some Julia code.:

To create this program, you need to add the Julia header path to the path of the included files and link with libjulia. For example, if the Julia code is set to $JULIA_DIR, you can compile the above test program test.c with gcc using the following line:

Alternatively, take a look at the embedding.c program in the Julia source code tree in the test/embed/ folder. The program file cli/loader_exe.c is another simple example of setting the parameters jl_options when linking with `libjulia'.

The first thing to do before calling any other C function in Julia is to initialize Julia. To do this, call the jl_init method, which tries to automatically determine the location of the Julia installation. If you need to specify a custom location or specify which system image to download, use `jl_init_with_image'.

The second operator in the test program computes the Julia operator by calling `jl_eval_string'.

It is strongly recommended to call jl_atexit_hook before terminating the program. In the above command example, the call is executed immediately before returning from `main'.

If the environment variable JULIA_DIR is missing, add it using the System panel before launching Visual Studio. The bin folder in JULIA_DIR should be located in the PATH system variable.

Let’s start by opening Visual Studio and creating a console application project. Open the stdafx header file.h and add the following lines to the end of it:

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

The next step is to set up a project to search for included Julia files and libraries. It is important to know the Julia installation version: 32-bit or 64-bit. Before proceeding, delete all platform configurations that do not match the Julia installation.

At this stage, the project must be assembled and launched.

Real applications will not only have to execute expressions, but also return their values to the main program. 'jl_eval_string` returns the value jl_value_t*, which is a pointer to the Julia object allocated on the heap. Storing simple data types like Float64 is called `boxing', and extracting stored primitive data is called `unboxing'. An improved example of a program that calculates the square root of two in Julia and returns the result in C contains the following code in its body:

To check whether ret belongs to a specific Julia type, you can use the functions jl_isa, jl_typeis or jl_is_.... When entering typeof(sqrt(2.0)) in the Julia shell, you can see that the return type is Float64 (double in C). The above code snippet uses the function jl_unbox_float64 to convert the packed Julia value to the C double type.

The corresponding functions jl_box_... are used for the reverse conversion.:

As we will see later, to call Julia functions with certain arguments, a packaging transformation is required.

Although the 'jl_eval_string` script allows you to get the result of the Julia expression in C, it prohibits passing arguments calculated in C to Julia. To do this, you will need to call Julia functions directly using jl_call:

In the first step, the descriptor for the Julia function sqrt is extracted by calling jl_get_function'. The first argument passed to the `jl_get_function function is a pointer to the Base module in which the sqrt function is defined. The double-precision decimal value is then packed using jl_box_float64'. In the last step, the function is called using `jl_call1'. There are also functions `jl_call0, jl_call2 and jl_call3' that allow efficient processing of any number of arguments. To pass a large number of arguments, use the `jl_call function.:

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

There is also an alternative and possibly simpler way to call Julia functions — by @cfunction. Using @cfunction allows type conversion on the Julia side, which is usually easier than on the C side. The above example with the sqrt function can be rewritten using @cfunction like this:

Here, we first define the called C function in Julia, then extract the function pointer from it, and finally call it. In addition to simplifying type conversion by executing in a higher-level language, calling Julia functions via @cfunction pointers eliminates the cost of dynamic dispatch required by jl_call pointers (for which all arguments are "packed"), and should have performance equivalent to native C function pointers.

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

Julia objects are usually freed by the garbage collector, but it is initially unaware of the stored reference to the Julia value from C. This means that the garbage collector can free objects, invalidating pointers.

The garbage collector will only work when new Julia objects are placed in memory. Allocation is performed using calls like jl_box_float64, but it can also occur at any time during the execution of Julia code.

When writing code with embedded Julia functions, it is usually safe to use the values of jl_value_t* between calls to jl_... (since the garbage collector is activated only by these calls). But so that the values can be guaranteed to persist after calls to jl_..., it is necessary to inform Julia that there is a reference to Julia values that require https://www.cs.purdue.edu/homes/hosking/690M/p611-fenichel.pdf [superuser rights]. This process is called granting superuser rights to the garbage collector. Obtaining superuser rights for a value ensures that the garbage collector does not accidentally identify it as unused and free up the memory in which it is stored. This can be done using the macro JL_GC_PUSH:

Calling 'JL_GC_POP` releases the links set by the previous macro JL_GC_PUSH'. Note that the macro `JL_GC_PUSH stores references in the C stack, so it must be precisely paired with the macro JL_GC_POP before exiting the scope. That is, before the function returns a value or the control flow leaves the block in which the macro JL_GC_PUSH was called.

Using macros JL_GC_PUSH2--JL_GC_PUSH6, you can send multiple Julia values simultaneously:

To send an array of Julia values, you can use the macro JL_GC_PUSHARGS as follows.

There should be only one call to JL_GC_PUSH* in each area, which should be matched with only one call to JL_GC_POP. If all the necessary variables cannot be sent simultaneously using a single macro call JL_GC_PUSH* or more than six variables need to be sent, and using an array of arguments is not an appropriate solution, internal blocks can be used.:

Note that it is optional to have valid values of jl_value_t* before calling JL_GC_PUSH*'. It is acceptable to initialize some variables with the value `NULL, pass them to JL_GC_PUSH*, and then create valid Julia values. For example:

If you need to save a pointer to a variable between functions (or block scopes), you cannot use the macro JL_GC_PUSH*. In this case, you need to create and save a reference to the variable in the Julia global scope. One of the easiest ways to accomplish this task is to use the global type IdDict, which will store references, prohibiting the garbage collector from releasing them. However, this method will only work correctly with mutable data.

If the variable is immutable, it must be enclosed in an equivalent mutable container or, preferably, in a RefValue{Any} before sending it to the 'IdDict'. With this approach, the container must be created or filled using C code using, for example, the 'jl_new_struct` function. If the container is created using jl_call*, the pointer that will be used in the C code must be reloaded.

To allow the garbage collector to free a variable, remove the reference to it from refs using the delete!' function. provided that no other reference to the variable is stored in any other location.:

Alternatively, for very simple cases, you can simply create a global container of type Vector'.{Any} and extract elements from it when necessary. Or you can even create one global variable for each pointer using the example below.

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

Julia arrays are represented in C with the data type 'jl_array_t*. In fact, `jl_array_t is a structure that contains:

For simplicity, let’s start with a one-dimensional array. You can create an array containing Float64 elements with a length of 10 as follows.

Or if you have already allocated an array, you can create a thin shell around its data.:

The last argument is logical and indicates whether the data should be taken over by Julia. If this argument is non-zero, the garbage collector will call free for the data pointer when the array is no longer referenced.

To access the x data, you can use jl_array_data:

Now you can fill in the array:

Let’s call the Julia function, which performs an operation with x in place.:

When outputting the array, you can make sure that the elements of x are now arranged in reverse order.

Julia’s code can cause exceptions. For example, consider the following.

This call doesn’t seem to do anything. However, you can check if an exception has occurred.:

If you use the Julia API for C from a language that supports exceptions (for example, Python, C#, C++), it makes sense to enclose each call to libjulia in a function that checks if an exception has been raised, and then re-creates the exception in the main language.