Struct jlrs::Julia

pub struct Julia { /* fields omitted */ }

This struct can be created only once during the lifetime of your program. You must create it with Julia::init or Julia::init_with_image before you can do anything related to Julia. While this struct exists, Julia is active; dropping it causes the shutdown code to be called.

Implementations

impl Julia

pub unsafe fn init(stack_size: usize) -> JlrsResult<Self>

Initializes Julia, this function can only be called once. If you call it a second time it will return an error. If this struct is dropped, you will need to restart your program to be able to call Julia code again.

You have to choose a stack size when calling this function. This will be the total number of slots that will be available for the GC stack. One of these slots will always be in use. Each frame needs two slots of overhead, plus one for every value created with that frame. A StaticFrame preallocates its slots, while a DynamicFrame grows to the required size. If calling a method requires one or more slots, this amount is explicitly documented.

This function is unsafe because this crate provides you with a way to execute arbitrary Julia code which can’t be checked for correctness.

pub unsafe fn init_with_image<P: AsRef<Path>>(
    stack_size: usize,
    julia_bindir: P,
    image_path: P
) -> JlrsResult<Self>

This function is similar to Julia::init except that it loads a custom system image. A custom image can be generated with the PackageCompiler package for Julia. The main advantage of using a custom image over the default one is that it allows you to avoid much of the compilation overhead often associated with Julia.

Two additional arguments are required to call this function compared to Julia::init; julia_bindir and image_relative_path. The first must be the absolute path to a directory that contains a compatible Julia binary (eg ${JULIA_DIR}/bin), the second must be either an absolute or a relative path to a system image.

This function will return an error if either of the two paths does not exist or if Julia has already been initialized.

pub fn set_stack_size(&mut self, stack_size: usize)

Change the stack size to stack_size.

pub fn stack_size(&self) -> usize

Returns the current stack size.

pub fn include<P: AsRef<Path>>(&mut self, path: P) -> JlrsResult<()>

Calls include in the Main module in Julia, which executes the file’s contents in that module. This has the same effect as calling include in the Julia REPL.

Example:

julia.include("MyJuliaCode.jl").unwrap();

pub fn frame<'base, 'julia: 'base, T, F>(
    &'julia mut self,
    capacity: usize,
    func: F
) -> JlrsResult<T> where
    F: FnOnce(Global<'base>, &mut StaticFrame<'base, Sync>) -> JlrsResult<T>, 

Create a StaticFrame that can hold capacity values, and call the given closure. Returns the result of this closure, or an error if the new frame can’t be created because there’s not enough space on the GC stack. The number of required slots on the stack is capacity + 2.

Every output and value you create inside the closure using the StaticFrame, either directly or through calling a Value, will reduce the available capacity of the StaticFrame by 1.

Example:

  julia.frame(1, |_global, frame| {
      let i = Value::new(frame, 1u64)?;
      Ok(())
  }).unwrap();

pub fn dynamic_frame<'base, 'julia: 'base, T, F>(
    &'julia mut self,
    func: F
) -> JlrsResult<T> where
    F: FnOnce(Global<'base>, &mut DynamicFrame<'base, Sync>) -> JlrsResult<T>, 

Create a DynamicFrame and call the given closure. Returns the result of this closure, or an error if the new frame can’t be created because the stack is too small. The number of required slots on the stack is 2.

Every output and value you create inside the closure using the DynamicFrame, either directly or through calling a Value, will occupy a single slot on the GC stack.

Example:

julia.dynamic_frame(|_global, frame| {
    let j = Value::new(frame, 1u64)?;
    Ok(())
}).unwrap();

Trait Implementations

impl Drop for Julia

fn drop(&mut self)

Executes the destructor for this type.

impl Gc for Julia

unsafe fn enable_gc(&mut self, on: bool) -> bool

Enable or disable the GC.

fn gc_is_enabled(&mut self) -> bool

Returns true if the GC is enabled.

unsafe fn gc_collect(&mut self, mode: GcCollection)

Force a collection.