pub struct Program { /* private fields */ }Expand description
A compiled candela program with resident interpreter state.
Registers and heap pools persist between Program::call invocations, so
state established by one call (including anything a host function mutates on
the Rust side) is visible to the next.
Program is single-threaded (!Send/!Sync): it holds Rc dispatchers
and reflects candela’s single-threaded VM.
Implementations§
Source§impl Program
impl Program
Sourcepub fn warnings(&self) -> &[Diagnostic]
pub fn warnings(&self) -> &[Diagnostic]
The warnings compiling this program raised, in the order they were raised. A warning does not stop the compile; see the warnings section of the error reference for what each one means.
Sourcepub fn call(
&mut self,
fn_name: &str,
args: &[Value],
) -> Result<Value, Diagnostic>
pub fn call( &mut self, fn_name: &str, args: &[Value], ) -> Result<Value, Diagnostic>
Invokes the script-defined function fn_name with args, returning its
value (or Value::Null for a void function).
The first call with a given set of argument types compiles a small
trampoline (which specializes fn_name for those types if it hasn’t
been already) onto the resident instruction stream; later calls with
the same types run it again. It runs against the persistent
register/heap state, so globals mutated by a previous call remain
visible.
A diagnostic raised while compiling the trampoline leaves the resident
tables exactly as they stood before this call began, and the Program
stays callable afterward.
§Errors
Returns a Diagnostic if fn_name is unknown, if the arguments don’t
type-check against its signature, or if the call raises a runtime error.
Sourcepub fn call_in_out(
&mut self,
fn_name: &str,
args: &mut [Value],
) -> Result<Value, Diagnostic>
pub fn call_in_out( &mut self, fn_name: &str, args: &mut [Value], ) -> Result<Value, Diagnostic>
Self::call, handing back what the function left in each argument it
was passed by reference.
A list, a map and a struct reach a script function by reference, so what the function writes into one is written into the value the call passed. Once the call returns, every argument that is one of those is replaced with its final value; every other argument is left as it was.
§Errors
As Self::call. An argument is only replaced once the call has run
without an error.
Sourcepub fn attributes(&self) -> AttributeTable
pub fn attributes(&self) -> AttributeTable
Every attribute the program’s scripts wrote, with the struct and enum tables the types in it refer to.
Sourcepub fn dispatch_events(&mut self, budget: u32) -> Result<usize, Diagnostic>
pub fn dispatch_events(&mut self, budget: u32) -> Result<usize, Diagnostic>
Runs the handlers of events that have arrived for this program, at
most budget of them, and answers how many ran. Never waits.
A host that runs its own loop calls this from it, on the thread the
program runs on, after the waker it set with
set_event_waker said something arrived. A
program that does not import std/event has no handlers, and the
answer is always 0.
§Errors
Returns a Diagnostic when a handler raised an error no try
caught. The events behind it stay queued for the next call.
Sourcepub fn collect(&mut self, budget: u32) -> bool
pub fn collect(&mut self, budget: u32) -> bool
Does up to about budget units of garbage collection while the
program is idle, and answers whether no collection work is left.
Call it between calls into the program, where the host would otherwise
wait, such as between frames. It carries on a collection already under
way, or begins one when the heap has grown enough since the last; on a
heap that has not, it does nothing and answers true. A unit is about
one object traced or one freed slot, never a length of time, so the
same calls do the same work on every machine. collect(u32::MAX) runs
a whole collection. Beginning a collection reads every root at once
whatever the budget.
Once a host has called this, allocations leave more of the work to it and begin a collection themselves only when the heap has grown further.
Auto Trait Implementations§
impl !Freeze for Program
impl !RefUnwindSafe for Program
impl !Send for Program
impl !Sync for Program
impl !UnwindSafe for Program
impl Forget for Program
impl Unpin for Program
impl UnsafeUnpin for Program
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere
T: ?Sized,
Source§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self with the foreground set to
value.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red() and
green(), which have the same functionality but are
pithier.
§Example
Set foreground color to white using fg():
use yansi::{Paint, Color};
painted.fg(Color::White);Set foreground color to white using white().
use yansi::Paint;
painted.white();Source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
Source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
Source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
Source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
Source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
Source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
Source§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self with the background set to
value.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red() and
on_green(), which have the same functionality but
are pithier.
§Example
Set background color to red using fg():
use yansi::{Paint, Color};
painted.bg(Color::Red);Set background color to red using on_red().
use yansi::Paint;
painted.on_red();Source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
Source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
Source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
Source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Source§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling Attribute value.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold() and
underline(), which have the same functionality
but are pithier.
§Example
Make text bold using attr():
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);Make text bold using using bold().
use yansi::Paint;
painted.bold();Source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Source§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi Quirk value.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask() and
wrap(), which have the same functionality but are
pithier.
§Example
Enable wrapping using .quirk():
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);Enable wrapping using wrap().
use yansi::Paint;
painted.wrap();Source§fn clear(&self) -> Painted<&T>
👎Deprecated since 1.0.1: renamed to resetting() due to conflicts with Vec::clear().
The clear() method will be removed in a future release.
fn clear(&self) -> Painted<&T>
renamed to resetting() due to conflicts with Vec::clear().
The clear() method will be removed in a future release.
Source§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the Condition value
applies. Replaces any previous condition.
See the crate level docs for more details.
§Example
Enable styling painted only when both stdout and stderr are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);