jlrs

The jlrs project utilizes two distinct Foreign Function Interface (FFI) crates to interact with Julia:

1. jl-sys: Provides direct bindings to libjulia.
2. jlrs-sys: Provides low-level extensions to the standard Julia bindings. These extensions are primarily implemented in C and include:
   • Accessors for specific struct fields.
   • Wrappers for inline functions and functional macros.
   • Trampoline functions to enable advanced features like try-catch blocks and non-statically-sized GC frames.

jlrs-sys is compiled as a static library to facilitate fast Thread Local Storage (TLS) access and to enable cross-language Link Time Optimization (LTO).

The jlrs-sys crate provides low-level extensions to libjulia that are not available in the standard Rust bindings. It is intended for developers who need fine-grained control over the Julia runtime from Rust.

Key capabilities provided by jlrs-sys include:

• Implementing Try/catch blocks
• Managing GC (Garbage Collector) frames
• Accessing Fast TLS (Thread Local Storage)
• Accessing specific struct field accessors
• Using wrappers for Julia functional macros and static inline functions

Runtimes allow you to initialize Julia from within a Rust application.

WARNING: Runtime features must only be enabled by applications that embed Julia. Libraries must never enable a runtime feature.

Available Runtimes

• local-rt: Provides single-threaded, blocking access to Julia.
• async-rt: Runs Julia on a separate thread and can be used from multiple threads.
• tokio-rt: Provides a tokio-based executor for the async-rt.
• multi-rt: Enables calling Julia from arbitrary threads. When combined with async-rt, it creates Julia-aware thread pools.

Performance Optimization

When building an application that embeds Julia, set the following environment variable to ensure fast code execution:

RUSTFLAGS="-Clink-arg=-rdynamic"

The ccall and ccall_throw_exceptions examples are libraries designed to be called from within Julia. To use them, follow these steps:

1. Build the libraries:

   cargo build --example $name

2. **Configure the environment**: Add the build output directory to your system's library path so Julia can locate the compiled libraries.
   - **Linux**: Add `$REPO_ROOT/target/debug/examples` to the `LD_LIBRARY_PATH` environment variable.
   - **Windows**: Add `$REPO_ROOT/target/debug/examples` to the `PATH` environment variable.

3. **Execute from Julia**:
   Run your Julia script using the compiled example name:
   ```bash
julia $name.jl

cargo build --example $name
# Then set LD_LIBRARY_PATH or PATH
# and run:
julia $name.jl

The ffi-validator is a utility crate used to verify that all globals and functions exported by jl_sys and jlrs_sys exist and possess the correct signatures. It achieves this by generating a C file that performs these checks.

To use the validator, run the CLI tool providing the paths to the jl_sys and jlrs_sys bindings as arguments.

ffi-validator [OPTIONS] <JL_SYS_BINDINGS_PATH> <JLRS_SYS_BINDINGS_PATH>

jlrs uses the JlrsCore package in Julia. By default, it installs the latest version automatically. You can control this behavior using the following environment variables:

Precedence: JLRS_CORE_NO_INSTALL > JLRS_CORE_REVISION > JLRS_CORE_VERSION.

For arrays where elements are Julia Values (objects), use ValueAccessor. These accessors handle the atomic nature of Julia values.

• get(target, index): Returns Option<ValueData<'target, 'data, Tgt>> by loading the atomic reference.
• as_slice(): Returns a slice of AtomicValueRef<Value<'scope, 'data>>.

ValueAccessorMut allows for direct manipulation of these values:

• push(value): Appends a Value to the end of the vector.
• append(arr): Appends another VectorAny to the end of the vector.

// Example: Appending to a ValueAccessorMut
value_accessor_mut.push(new_value);
value_accessor_mut.append(other_vector_any);