Frames ensure Julia’s garbage collector is properly managed.
Julia data is freed by the GC when it’s not in use. You will need to use frames to do things
like calling Julia functions and creating new values, this ensures the values created with a
specific frame are protected from garbage collection until that frame goes out of scope.
Four different kinds of frames exist; StaticFrame, DynamicFrame, NullFrame, and
AsyncFrame. The first two of them can be nested and freely mixed. The main difference
between those two is that a StaticFrame is created with a definite capacity, while a
DynamicFrame will dynamically grow its capacity whenever a value is created or a function
is called. A StaticFrame is more efficient, a DynamicFrame is easier to use. Creating
a nested frame takes no space in the current frame.
The third type, NullFrame can only be used if you call Rust from Julia. They don’t
allocate at all and can only be used to borrow array data.
The final type, AsyncFrame is only available when you use the async runtime. Structs that
implement JuliaTask can use this kind of frame in the run-method. It’s essentially a
DynamicFrame with the additional feature that it can be used to call
Value::call_async.
Frames have a lifetime, 'frame. This lifetime ensures that a Value can only be used as
long as the frame that protects it has not been dropped.
Most functionality that frames implement is defined by the Frame trait.
| AsyncFrame | An AsyncFrame is a special kind of DynamicFrame that’s available when you implement
JuliaTask. In addition to the capabilities of a DynamicFrame it can be used to call
Value::call_async which lets you call a function in a new thread in Julia. This feature is
only available by using AsyncJulia.
|
| DynamicFrame | A DynamicFrame is a frame that has a dynamic number of slots on the GC stack. With some
exceptions, creating new Values and calling them require one slot each. A DynamicFrame
acquires a new slot every time one is needed. See the documentation in the value module
for more information about the costs. You get access to a DynamicFrame by calling
Julia::dynamic_frame or Frame::dynamic_frame, most of
their functionality is defined in the Frame trait.
|
| FrameIdx | |
| NullFrame | A NullFrame can be used if you call Rust from Julia through ccall and want to borrow array
data but not perform any allocations. It can’t be nested or be used for functions that
allocate (like creating new values or calling functions). Functions that depend on allocation
will return JlrsError::NullFrame if you call them with a NullFrame.
|
| Output | An Output is a slot of a frame that has been reserved for later use. It can be used to
extend the lifetime of the result of a function call to the Output’s lifetime. You can
create an output by calling Frame::output.
|
| StaticFrame | A StaticFrame is a frame that has a definite number of slots on the GC stack. With some
exceptions, creating new Values and calling them require one slot each. Rather than using
new slots on the GC stack when a slot is needed, a StaticFrame uses the slots it acquired on
creation. See the documentation in the value module for more information about the costs.
You get access to a StaticFrame by calling Julia::frame or Frame::frame, most of
their functionality is defined in the Frame trait.
|