Struct jlrs::multitask::AsyncJulia

pub struct AsyncJulia<T, R> where
    T: Send + Sync + 'static,
    R: ReturnChannel<T = T>,  { /* fields omitted */ }

A handle to the async runtime. It can be used to include files and create new tasks. The runtime shuts down when the last handle is dropped. The two generic type parameters T and R are the return type and return channel type respectively, which must be the same across all different implementations of JuliaTask that you use.

The easiest way to get started is to use T = Box<dyn Any + Send + Sync>, the return channel must implement the ReturnChannel trait. This trait is implemented for Sender from async_std and crossbeam_channel.

The initialization methods share several arguments:

• channel_capacity: the capacity of the channel used to communicate with the runtime.
• n_threads: the number of threads that can be used to run tasks at the same time, it must be less than the number of threads set with the JULIA_NUM_THREADS environment variable (which defaults to 1).
• stack_size: the size of a stack that is created for each of the tasks threads and the main thread (so n_thread + 1 stacks with stack_size slots are created).
• process_events_ms: to ensure the garbage collector can run and tasks that have yielded in Julia are rescheduled, events must be processed periodically when at least one task is running.

Implementations

impl<T, R> AsyncJulia<T, R> where
    T: Send + Sync + 'static,
    R: ReturnChannel<T = T>, 

pub unsafe fn init<P: AsRef<Path>>(
    channel_capacity: usize,
    n_threads: usize,
    stack_size: usize,
    process_events_ms: u64,
    jlrs_path: P
) -> JlrsResult<(Self, ThreadHandle<JlrsResult<()>>)>

Initialize Julia in a new thread, this function can only be called once. If Julia has already been initialized this will return an error, otherwise it will return a handle to the runtime and a handle to the thread. The runtime is shut down after the final handle to it has been dropped.

In addition to the common arguments to initialize the async runtime, you need to provide jlrs_path. This is the path to jlrs.jl, which is required for AsyncJulia to work correctly.

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 async unsafe fn init_async<P: AsRef<Path>>(
    channel_capacity: usize,
    n_threads: usize,
    stack_size: usize,
    process_events_ms: u64,
    jlrs_path: P
) -> JlrsResult<(Self, AsyncStdHandle<JlrsResult<()>>)>

Initialize Julia as a blocking task, this function can only be called once. If Julia was already initialized this will return an error, otherwise it will return a handle to the runtime and a handle to the task. The runtime is shut down after the final handle to it has been dropped.

In addition to the common arguments to initialize the async runtime, you need to provide jlrs_path. This is the path to jlrs.jl, this file is required for AsyncJulia to work correctly.

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, Q>(
    channel_capacity: usize,
    n_threads: usize,
    stack_size: usize,
    process_events_ms: u64,
    julia_bindir: P,
    image_path: Q
) -> JlrsResult<(Self, ThreadHandle<JlrsResult<()>>)> where
    P: AsRef<Path> + Send + 'static,
    Q: AsRef<Path> + Send + 'static, 

This function is similar to AsyncJulia::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.

In addition to the common arguments to initialize the async runtime, you need to provide julia_bindir and image_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. Note that jlrs.jl must be available in this custom image in the Main module, ie Main.Jlrs must exist.

This function will return an error if either of the two paths does not exist, if Julia has already been initialized, or if Main.Jlrs doesn't exist. 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 async unsafe fn init_with_image_async<P, Q>(
    channel_capacity: usize,
    n_threads: usize,
    stack_size: usize,
    process_events_ms: u64,
    julia_bindir: P,
    image_path: Q
) -> JlrsResult<(Self, AsyncStdHandle<JlrsResult<()>>)> where
    P: AsRef<Path> + Send + 'static,
    Q: AsRef<Path> + Send + 'static, 

This function is similar to AsyncJulia::init_async 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.

In addition to the common arguments to initialize the async runtime, you need to provide julia_bindir and image_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. Note that jlrs.jl must be available in this custom image in the Main module, ie Main.Jlrs must exist.

This function will return an error if either of the two paths does not exist, if Julia has already been initialized, or if Main.Jlrs doesn't exist. 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 async fn new_task<D: JuliaTask<T = T, R = R>, '_>(&'_ self, task: D)

Send a new task to the runtime, this method waits until there's room in the channel.

pub fn try_new_task<D: JuliaTask<T = T, R = R>>(
    &self,
    task: D
) -> JlrsResult<()>

Try to send a new task to the runtime, if there's no room in the channel an error is returned immediately.

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

Include a Julia file. This method waits until the call Main.include in Julia has been completed. It returns an error if the path does not exist or the call to Main.include throws an exception.

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

Include a Julia file. This method waits until the call Main.include in Julia has been completed. It returns an error if the path does not exist, the channel is full, or the call to Main.include throws an exception.

pub fn capacity(&self) -> usize

Returns the capacity of the channel.

pub fn len(&self) -> usize

Returns the number of messages in the channel.

pub fn is_empty(&self) -> bool

Returns true if the channel is empty.

pub fn is_full(&self) -> bool

Returns true if the channel is full.

Trait Implementations

impl<T: Clone, R: Clone> Clone for AsyncJulia<T, R> where
    T: Send + Sync + 'static,
    R: ReturnChannel<T = T>, 

fn clone(&self) -> AsyncJulia<T, R>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.