Struct jlrs::wrappers::ptr::value::Value

#[repr(transparent)]
pub struct Value<'scope, 'data>(_, _, _);

See the [module-level documentation] for more information.

A Value is a wrapper around a non-null pointer to some data owned by the Julia garbage collector, it has two lifetimes: 'scope and 'data. The first of these ensures that a Value can only be used while it’s rooted, the second accounts for data borrowed from Rust. The only way to borrow data from Rust is to create an Julia array that borrows its contents by calling Array::from_slice; if a Julia function is called with such an array as an argument the result will inherit the second lifetime of the borrowed data to ensure that such a Value can only be used while the borrow is active.

Implementations

impl Value<'_, '_>

Create new Values

Several methods are available to create new values. The simplest of these is Value::new, which can be used to convert relatively simple data from Rust to Julia. Data that can be converted this way must implement IntoJulia, which is the case for types like the primitive number types. This trait is also automatically derived by JlrsReflect.jl for types that are trivially guaranteed to be bits-types: the type must have no type parameters, no unions, and all fields must be immutable bits-types themselves.

pub fn new<'target, V, S>(
    scope: S,
    value: V
) -> JlrsResult<Value<'target, 'static>> where
    V: IntoJulia,
    S: PartialScope<'target>, 

Create a new Julia value, any type that implements IntoJulia can be converted using this function.

pub fn new_unrooted<'global, V>(
    global: Global<'global>,
    value: V
) -> ValueRef<'global, 'static> where
    V: IntoJulia, 

Create a new Julia value, any type that implements IntoJulia can be converted using this function. Unlike Value::new this method doesn’t root the allocated value.

pub fn new_named_tuple<'target, 'current, 'value, 'data, S, F, N, T, V>(
    scope: S,
    field_names: N,
    values: V
) -> JlrsResult<Value<'target, 'data>> where
    S: Scope<'target, 'current, F>,
    F: Frame<'current>,
    N: AsRef<[T]>,
    T: ToSymbol,
    V: AsRef<[Value<'value, 'data>]>, 

Create a new named tuple, you should use the named_tuple macro rather than this method.

pub fn apply_type<'target, 'value, 'data, V, S>(
    self,
    scope: S,
    types: V
) -> JlrsResult<JuliaResult<'target, 'data>> where
    S: PartialScope<'target>,
    V: AsRef<[Value<'value, 'data>]>, 

Apply the given types to self.

If self is the DataType anytuple_type, calling this method will return a new tuple type with the given types as its field types. If it is the DataType uniontype_type, calling this method is equivalent to calling Union::new. If the value is a UnionAll, the given types will be applied and the resulting type is returned.

If the types can’t be applied to self this methods catches and returns the exception.

pub unsafe fn apply_type_unchecked<'target, 'value, 'data, S, V>(
    self,
    scope: S,
    types: V
) -> JlrsResult<Value<'target, 'data>> where
    S: PartialScope<'target>,
    V: AsRef<[Value<'value, 'data>]>, 

Apply the given types to self.

If self is the DataType anytuple_type, calling this method will return a new tuple type with the given types as its field types. If it is the DataType uniontype_type, calling this method is equivalent to calling Union::new. If the value is a UnionAll, the given types will be applied and the resulting type is returned.

If an exception is thrown it isn’t caught

Safety: an exception must not be thrown if this method is called from a ccalled function.

impl<'scope, 'data> Value<'scope, 'data>

Type information

Every value is guaranteed to have a DataType. This contains all of the value’s type information.

pub fn datatype(self) -> DataType<'scope>

Returns the DataType of this value.

pub fn datatype_name(self) -> JlrsResult<&'scope str>

Returns the name of this value’s DataType as a string slice.

impl Value<'_, '_>

Type checking

Many properties of Julia types can be checked, including whether instances of the type are mutable, if the value is an array, and so on. The method Value::is can be used to perform these checks. All these checks implement the Typecheck trait. If the type that implements this trait also implements ValidLayout, the typecheck indicates whether or not the value can be cast to or unboxed as that type.

pub fn is<T: Typecheck>(self) -> bool

Performs the given typecheck:

julia.scope(|_global, mut frame| {
    let i = Value::new(&mut frame, 2u64)?;
    assert!(i.is::<u64>());
    Ok(())
}).unwrap();

A full list of supported checks can be found here.

pub fn is_array_of<T: ValidLayout>(self) -> bool

Returns true if the value is an array with elements of type T.

pub fn subtype(self, sup: Value<'_, '_>) -> bool

Returns true if self is a subtype of sup.

pub fn is_kind(self) -> bool

Returns true if self is the type of a DataType, UnionAll, Union, or Union{} (the bottom type).

pub fn is_type(self) -> bool

Returns true if the value is a type, ie a DataType, UnionAll, Union, or Union{} (the bottom type).

pub fn isa(self, ty: Value<'_, '_>) -> bool

Returns true if self is of type ty.

impl<'scope, 'data> Value<'scope, 'data>

Lifetime management

Values have two lifetimes, 'scope and 'data. The first ensures that a value can only be used while it’s rooted, the second ensures that values that (might) borrow array data from Rust are also restricted by the lifetime of that borrow. This second restriction can be relaxed with Value::assume_owned if it doesn’t borrow any data from Rust.

pub unsafe fn assume_owned(self) -> Value<'scope, 'static>

If you call a Julia function with one or more borrowed arrays as arguments, its result can only be used when all the borrows are active. If this result doesn’t contain any borrowed data this function can be used to relax its second lifetime to 'static.

Safety: The value must not contain any data borrowed from Rust.

pub fn root<'target>(self, output: Output<'target>) -> Value<'target, 'data>

Use the Output to extend the lifetime of this data.

impl<'scope, 'data> Value<'scope, 'data>

Conversions

There are two ways to convert a Value to some other type. The first is casting, which is used to convert a Value to the appropriate pointer wrapper type. For example, if the Value is a Julia array it can be cast to Array. Because this only involves a pointer cast it’s always possible to convert a wrapper to a Value by calling Wrapper::as_value. The second way is unboxing, which is used to copy the data the Value points to to Rust. If a Value is a UInt8, it can be unboxed as a u8. By default, jlrs can unbox the default primitive types and Julia strings, but the Unbox trait can be implemented for other types. It’s recommended that you use JlrsReflect.jl to do so. Unlike casting, unboxing dereferences the pointer. As a result it loses its header, so an unboxed value can’t be used as a Value again without reallocating it.

pub fn cast<T: Wrapper<'scope, 'data> + Typecheck>(self) -> JlrsResult<T>

Cast the value to a pointer wrapper type T. Returns an error if the conversion is invalid.

pub unsafe fn cast_unchecked<T: Wrapper<'scope, 'data>>(self) -> T

Cast the value to a pointer wrapper type T without checking if this conversion is valid.

Safety: You must guarantee self.is::<T>() would have returned true.

pub fn unbox<T: Unbox + Typecheck>(self) -> JlrsResult<T::Output>

Unbox the contents of the value as the output type associated with T. Returns an error if the layout of T::Output is incompatible with the layout of the type in Julia.

pub unsafe fn unbox_unchecked<T: Unbox>(self) -> T::Output

Unbox the contents of the value as the output type associated with T without checking if the layout of T::Output is compatible with the layout of the type in Julia.

Safety: You must guarantee self.is::<T>() would have returned true.

pub fn data_ptr(self) -> NonNull<c_void>

Returns a pointer to the data, this is useful when the output type of Unbox is different than the implementation type and you have to write a custom unboxing function. It’s your responsibility this pointer is used correctly.

impl<'scope, 'data> Value<'scope, 'data>

Fields

Most Julia values have fields. For example, if the value is an instance of this struct:

struct Example
   fielda
   fieldb::UInt32
end

it will have two fields, fielda and fieldb. The first field is a pointer field, the second is stored inline as a u32. It’s possible to safely access the raw contents of these fields with the method Value::field_accessor. The first field can be accessed as a ValueRef, the second as a u32.

pub fn field_names(self) -> &'scope [Symbol<'scope>]

Returns the field names of this value as a slice of Symbols.

pub fn n_fields(self) -> usize

Returns the number of fields the underlying Julia value has.

pub fn field_accessor<'current, 'borrow, F: Frame<'current>>(
    self,
    _frame: &'borrow F
) -> FieldAccessor<'scope, 'data, 'borrow>

Returns an accessor to access the contents of this value without allocating temporary Julia data.

pub fn get_nth_field<'target, S>(
    self,
    scope: S,
    idx: usize
) -> JlrsResult<Value<'target, 'data>> where
    S: PartialScope<'target>, 

Roots the field at index idx if it exists and returns it, or a JlrsError::AccessError if the index is out of bounds.

pub fn get_nth_field_ref(self, idx: usize) -> JlrsResult<ValueRef<'scope, 'data>>

Returns the field at index idx if it’s a pointer field.

If the field doesn’t exist or if the field can’t be referenced because its data is stored inline, a JlrsError::AccessError is returned.

pub fn get_nth_field_unrooted(
    self,
    idx: usize
) -> JlrsResult<ValueRef<'scope, 'data>>

Returns the field at index idx if it exists as a ValueRef. If the field is an inline field a new value is allocated which is left unrooted.

If the field doesn’t exist JlrsError::OutOfBoundsField is returned.

pub fn get_field<'target, N, S>(
    self,
    scope: S,
    field_name: N
) -> JlrsResult<Value<'target, 'data>> where
    N: ToSymbol,
    S: PartialScope<'target>, 

Roots the field with the name field_name if it exists and returns it, or a JlrsError::AccessError if there’s no field with that name.

pub fn get_field_ref<N>(
    self,
    field_name: N
) -> JlrsResult<ValueRef<'scope, 'data>> where
    N: ToSymbol, 

Returns the field with the name field_name if it’s a pointer field.

If the field doesn’t exist or if the field can’t be referenced because its data is stored inline, a JlrsError::AccessError is returned.

pub fn get_field_unrooted<N>(
    self,
    field_name: N
) -> JlrsResult<ValueRef<'scope, 'data>> where
    N: ToSymbol, 

Returns the field with the name field_name if it exists. If the field is an inline field a new value is allocated which is left unrooted.

If the field doesn’t exist a JlrsError::AccessError is returned.

pub unsafe fn set_nth_field<'frame, F>(
    self,
    frame: &mut F,
    idx: usize,
    value: Value<'_, 'data>
) -> JlrsResult<JuliaResult<'frame, 'data, ()>> where
    F: Frame<'frame>, 

Set the value of the field at idx. If Julia throws an exception it’s caught, rooted in the frame, and returned. If the index is out of bounds or the value is not a subtype of the field an error is returned,

Safety: Mutating things that should absolutely not be mutated, like the fields of a DataType, is not prevented.

pub unsafe fn set_nth_field_unrooted(
    self,
    idx: usize,
    value: Value<'_, 'data>
) -> JlrsResult<JuliaResultRef<'scope, 'data, ()>>

Set the value of the field at idx. If Julia throws an exception it’s caught and returned but not rooted. If the index is out of bounds or the value is not a subtype of the field an error is returned,

Safety: Mutating things that should absolutely not be mutated, like the fields of a DataType, is not prevented.

pub unsafe fn set_nth_field_unchecked(self, idx: usize, value: Value<'_, 'data>)

Set the value of the field at idx. If Julia throws an exception the process aborts.

Safety: this method doesn’t check if the type of the value is a subtype of the field’s type. Mutating things that should absolutely not be mutated, like the fields of a DataType, is also not prevented.

pub unsafe fn set_field<'frame, F, N>(
    self,
    frame: &mut F,
    field_name: N,
    value: Value<'_, 'data>
) -> JlrsResult<JuliaResult<'frame, 'data, ()>> where
    F: Frame<'frame>,
    N: ToSymbol, 

Set the value of the field with the name field_name. If Julia throws an exception it’s caught, rooted in the frame, and returned. If there’s no field with the given name or the value is not a subtype of the field an error is returned.

Safety: Mutating things that should absolutely not be mutated, like the fields of a DataType, is not prevented.

pub unsafe fn set_field_unrooted<N>(
    self,
    field_name: N,
    value: Value<'_, 'data>
) -> JlrsResult<JuliaResultRef<'scope, 'data, ()>> where
    N: ToSymbol, 

Set the value of the field with the name field_name. If Julia throws an exception it’s caught, and returned but not rooted. If there’s no field with the given name or the value is not a subtype of the field an error is returned.

Safety: Mutating things that should absolutely not be mutated, like the fields of a DataType, is not prevented.

pub unsafe fn set_field_unchecked<N>(
    self,
    field_name: N,
    value: Value<'_, 'data>
) -> JlrsResult<()> where
    N: ToSymbol, 

Set the value of the field with the name field_name. If Julia throws an exception the process aborts. If there’s no field with the given name an error is returned.

Safety: this method doesn’t check if the type of the value is a subtype of the field’s type. Mutating things that should absolutely not be mutated, like the fields of a DataType, is also not prevented.

impl Value<'_, '_>

Evaluate Julia code

The easiest way to call Julia from Rust is by evaluating some Julia code directly. This can be used to call simple functions without any arguments provided from Rust and to execute using-statements.

pub unsafe fn eval_string<'target, C, S>(
    scope: S,
    cmd: C
) -> JlrsResult<JuliaResult<'target, 'static>> where
    C: AsRef<str>,
    S: PartialScope<'target>, 

Execute a Julia command cmd, for example Value::eval_string(&mut *frame, "sqrt(2)") or Value::eval_string(&mut *frame, "using LinearAlgebra").

Safety: The command can’t be checked for correctness, nothing prevents you from causing a segmentation fault with a command like unsafe_load(Ptr{Float64}(C_NULL)).

pub unsafe fn eval_cstring<'target, C, S>(
    scope: S,
    cmd: C
) -> JlrsResult<JuliaResult<'target, 'static>> where
    C: AsRef<CStr>,
    S: PartialScope<'target>, 

Execute a Julia command cmd. This is equivalent to Value::eval_string, but uses a null-terminated string.

Safety: The command can’t be checked for correctness, nothing prevents you from causing a segmentation fault with a command like unsafe_load(Ptr{Float64}(C_NULL)).

pub unsafe fn include<'target, 'current, P, S, F>(
    scope: S,
    path: P
) -> JlrsResult<JuliaResult<'target, 'static>> where
    P: AsRef<Path>,
    S: Scope<'target, 'current, F>,
    F: Frame<'current>, 

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

Safety: The content of the file can’t be checked for correctness, nothing prevents you from causing a segmentation fault with code like unsafe_load(Ptr{Float64}(C_NULL)).

impl Value<'_, '_>

Equality

pub fn object_id(self) -> usize

Returns the object id of this value.

pub fn egal(self, other: Value<'_, '_>) -> bool

Returns true if self and other are equal.

impl Value<'_, '_>

Finalization

pub unsafe fn add_finalizer(self, f: Value<'_, 'static>)

Add a finalizer f to this value. The finalizer must be a Julia function, it will be called when this value is about to be freed by the garbage collector.

Safety: the finalizer must be compatible with the data.

pub unsafe fn add_ptr_finalizer(self, f: unsafe extern "C" fn(_: *mut c_void))

Add a finalizer f to this value. The finalizer must be an extern "C" function that takes one argument, the value as a void pointer.

Safety: the finalizer must be compatible with the data.

impl<'scope> Value<'scope, 'static>

Constant values.

pub fn bottom_type(_: Global<'scope>) -> Self

Union{}.

pub fn stackovf_exception(_: Global<'scope>) -> Self

StackOverflowError.

pub fn memory_exception(_: Global<'scope>) -> Self

OutOfMemoryError.

pub fn readonlymemory_exception(_: Global<'scope>) -> Self

ReadOnlyMemoryError.

pub fn diverror_exception(_: Global<'scope>) -> Self

DivideError.

pub fn undefref_exception(_: Global<'scope>) -> Self

UndefRefError.

pub fn interrupt_exception(_: Global<'scope>) -> Self

InterruptException.

pub fn an_empty_vec_any(_: Global<'scope>) -> Self

An empty `Array{Any, 1}.

pub fn an_empty_string(_: Global<'scope>) -> Self

An empty immutable String, “”.

pub fn array_uint8_type(_: Global<'scope>) -> Self

Array{UInt8, 1}

pub fn array_any_type(_: Global<'scope>) -> Self

Array{Any, 1}

pub fn array_symbol_type(_: Global<'scope>) -> Self

Array{Symbol, 1}

pub fn array_int32_type(_: Global<'scope>) -> Self

Array{Int32, 1}

pub fn emptytuple(_: Global<'scope>) -> Self

The empty tuple, ().

pub fn true_v(_: Global<'scope>) -> Self

The instance of true.

pub fn false_v(_: Global<'scope>) -> Self

The instance of false.

pub fn nothing(_: Global<'scope>) -> Self

The instance of Nothing, nothing.

pub fn stdout(_: Global<'scope>) -> Self

The handle to stdout as a Julia value.

pub fn stderr(_: Global<'scope>) -> Self

The handle to stderr as a Julia value.

Trait Implementations

impl<'data> Call<'data> for Value<'_, 'data>

unsafe fn call0<'target, S>(
    self,
    scope: S
) -> JlrsResult<JuliaResult<'target, 'data>> where
    S: PartialScope<'target>, 

Call a function with no arguments and root the result in scope.

unsafe fn call1<'target, S>(
    self,
    scope: S,
    arg0: Value<'_, 'data>
) -> JlrsResult<JuliaResult<'target, 'data>> where
    S: PartialScope<'target>, 

Call a function with one argument and root the result in scope.

unsafe fn call2<'target, S>(
    self,
    scope: S,
    arg0: Value<'_, 'data>,
    arg1: Value<'_, 'data>
) -> JlrsResult<JuliaResult<'target, 'data>> where
    S: PartialScope<'target>, 

Call a function with two arguments and root the result in scope.

unsafe fn call3<'target, S>(
    self,
    scope: S,
    arg0: Value<'_, 'data>,
    arg1: Value<'_, 'data>,
    arg2: Value<'_, 'data>
) -> JlrsResult<JuliaResult<'target, 'data>> where
    S: PartialScope<'target>, 

Call a function with three arguments and root the result in scope.

unsafe fn call<'target, 'value, V, S>(
    self,
    scope: S,
    args: V
) -> JlrsResult<JuliaResult<'target, 'data>> where
    V: AsRef<[Value<'value, 'data>]>,
    S: PartialScope<'target>, 

Call a function with an arbitrary number arguments and root the result in scope.

unsafe fn call0_unrooted<'target>(
    self,
    _: Global<'target>
) -> JuliaResultRef<'target, 'data>

Call a function with no arguments without rooting the result.

unsafe fn call1_unrooted<'target>(
    self,
    _: Global<'target>,
    arg0: Value<'_, 'data>
) -> JuliaResultRef<'target, 'data>

Call a function with one argument without rooting the result.

unsafe fn call2_unrooted<'target>(
    self,
    _: Global<'target>,
    arg0: Value<'_, 'data>,
    arg1: Value<'_, 'data>
) -> JuliaResultRef<'target, 'data>

Call a function with two arguments without rooting the result.

unsafe fn call3_unrooted<'target>(
    self,
    _: Global<'target>,
    arg0: Value<'_, 'data>,
    arg1: Value<'_, 'data>,
    arg2: Value<'_, 'data>
) -> JuliaResultRef<'target, 'data>

Call a function with three arguments without rooting the result.

unsafe fn call_unrooted<'target, 'value, V>(
    self,
    _: Global<'target>,
    args: V
) -> JuliaResultRef<'target, 'data> where
    V: AsRef<[Value<'value, 'data>]>, 

Call a function with an abitrary number of arguments without rooting the result.

impl<'impl0, 'data> CallAsync<'data> for Value<'impl0, 'data>

unsafe fn call_async<'frame, 'value, 'life0, 'async_trait, V>(
    self,
    frame: &'life0 mut AsyncGcFrame<'frame>,
    args: V
) -> Pin<Box<dyn Future<Output = JlrsResult<JuliaResult<'frame, 'data>>> + 'async_trait>> where
    V: AsRef<[Value<'value, 'data>]>,
    'frame: 'async_trait,
    'value: 'async_trait,
    V: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 

Call a function on another thread with the given arguments. This method uses Base.Threads.@spawn to call the given function on another thread but return immediately. While awaiting the result the async runtime can work on other tasks, the current task resumes after the function call on the other thread completes.

unsafe fn schedule_async<'frame, 'value, V>(
    self,
    frame: &mut AsyncGcFrame<'frame>,
    args: V
) -> JlrsResult<JuliaResult<'frame, 'data, Task<'frame>>> where
    V: AsRef<[Value<'value, 'data>]>, 

Does the same thing as CallAsync::call_async, but the task is returned rather than an awaitable Future. This method should only be called in PersistentTask::init, otherwise it’s not guaranteed this task can make progress.

unsafe fn call_async_local<'frame, 'value, 'life0, 'async_trait, V>(
    self,
    frame: &'life0 mut AsyncGcFrame<'frame>,
    args: V
) -> Pin<Box<dyn Future<Output = JlrsResult<JuliaResult<'frame, 'data>>> + 'async_trait>> where
    V: AsRef<[Value<'value, 'data>]>,
    'frame: 'async_trait,
    'value: 'async_trait,
    V: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 

Call a function with the given arguments in an @async block. Like call_async, the function is not called on the main thread, but on a separate thread that handles all tasks created by this method. This method should only be used with functions that do very little computational work but mostly spend their time waiting on IO.

unsafe fn schedule_async_local<'frame, 'value, V>(
    self,
    frame: &mut AsyncGcFrame<'frame>,
    args: V
) -> JlrsResult<JuliaResult<'frame, 'data, Task<'frame>>> where
    V: AsRef<[Value<'value, 'data>]>, 

Does the same thing as CallAsync::call_async_local, but the task is returned rather than an awaitable Future. This method should only be called in PersistentTask::init, otherwise it’s not guaranteed this task can make progress.

unsafe fn call_async_main<'frame, 'value, 'life0, 'async_trait, V>(
    self,
    frame: &'life0 mut AsyncGcFrame<'frame>,
    args: V
) -> Pin<Box<dyn Future<Output = JlrsResult<JuliaResult<'frame, 'data>>> + 'async_trait>> where
    V: AsRef<[Value<'value, 'data>]>,
    'frame: 'async_trait,
    'value: 'async_trait,
    V: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 

Call a function with the given arguments in an @async block. The task is scheduled on the main thread. This method should only be used with functions that must run on the main thread. The runtime is blocked while this task is active.

unsafe fn schedule_async_main<'frame, 'value, V>(
    self,
    frame: &mut AsyncGcFrame<'frame>,
    args: V
) -> JlrsResult<JuliaResult<'frame, 'data, Task<'frame>>> where
    V: AsRef<[Value<'value, 'data>]>, 

Does the same thing as CallAsync::call_async_main, but the task is returned rather than an awaitable Future. This method should only be called in PersistentTask::init, otherwise it’s not guaranteed this task can make progress.

impl<'scope, 'data> Clone for Value<'scope, 'data>

fn clone(&self) -> Value<'scope, 'data>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Value<'_, '_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq<Value<'_, '_>> for Value<'_, '_>

fn eq(&self, other: &Value<'_, '_>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'scope, 'data> PartialEq<Value<'scope, 'data>> for DataType<'scope>

fn eq(&self, other: &Value<'scope, 'data>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'value, 'data> ProvideKeywords<'value, 'data> for Value<'value, 'data>

fn provide_keywords(
    self,
    kws: Value<'value, 'data>
) -> JlrsResult<WithKeywords<'value, 'data>>

Provide keyword arguments to the function. The keyword arguments must be a NamedTuple.

impl<'scope, 'data> Copy for Value<'scope, 'data>

impl<'scope, 'data> Eq for Value<'scope, 'data>

impl<'scope, 'data> StructuralEq for Value<'scope, 'data>