Struct Globals 

pub struct Globals { /* private fields */ }

Storage for the static items declared by a Unit.

A unit assigns every static item it declares a zero-indexed slot. The values living in those slots are not stored in the unit itself, they are stored here and handed to a virtual machine when it is called. This means a single compiled unit can back any number of independent states.

Every slot keeps track of whether it has been initialized. A slot which has an initializer is lazily initialized the first time a script reads it, but a caller can also assign a value up front, in which case the initializer is never evaluated.

The storage is a cheaply cloned handle. Cloning it does not copy the slots, it produces a second handle to the same storage, which is how a caller can keep reading and writing static items while a virtual machine using them is running.

Examples

use rune::{Context, Diagnostics, Source, Sources, Vm};
use rune::runtime::Globals;
use rune::sync::Arc;

let context = Context::with_default_modules()?;
let runtime = Arc::try_new(context.runtime()?)?;

let mut sources = Sources::new();
sources.insert(Source::memory(r#"
static COUNTER = 0;

pub fn main() {
    COUNTER += 1;
}
"#)?)?;

let mut diagnostics = Diagnostics::new();

let unit = rune::prepare(&mut sources)
    .with_context(&context)
    .with_diagnostics(&mut diagnostics)
    .build()?;

let unit = Arc::try_new(unit)?;
let globals = Globals::new(unit.clone())?;

let mut vm = Vm::new(runtime, unit).with_globals(globals.clone());
vm.call(["main"], ())?;
vm.call(["main"], ())?;

let counter = globals.get(["COUNTER"])?.expect("COUNTER to be initialized");
assert_eq!(rune::from_value::<i64>(counter)?, 2);

Implementations

impl Globals

pub const fn empty() -> Self

Construct an empty storage which has no slots.

This is what a Vm is constructed with. Reading or writing a static through it always errors, so a unit which declares statics needs real storage through Vm::with_globals.

pub fn new(unit: Arc<Unit>) -> Result<Self>

Construct storage for all the statics declared by the given unit, with every slot uninitialized.

pub fn is_configured(&self) -> bool

Test if this storage has been configured for a unit.

Note that this is not the same as is_empty, since a unit which declares no statics gets configured storage with no slots in it.

pub fn len(&self) -> usize

The number of slots in this storage.

pub fn is_empty(&self) -> bool

Test if this storage has no slots.

pub fn is_same(&self, other: &Self) -> bool

Test if two handles refer to the same storage.

pub fn is_same_unit(&self, unit: &Arc<Unit>) -> bool

Test if this storage was constructed for the given unit.

pub fn slot(&self, name: impl ToTypeHash) -> Result<usize, GlobalsError>

Look up the slot assigned to the given static item.

pub fn get(&self, name: impl ToTypeHash) -> Result<Option<Value>, GlobalsError>

Read the value of a static item, if it has been initialized.

Note that this does not evaluate the initializer of an uninitialized static, since doing so requires a runtime. A static which has an initializer but has never been read by a script therefore reads as None here.

pub fn set( &self, name: impl ToTypeHash, value: Value, ) -> Result<(), GlobalsError>

Write the value of a static item.

pub fn clear(&self, name: impl ToTypeHash) -> Result<(), GlobalsError>

Reset a static item back to being uninitialized.

The next script which reads it will evaluate its initializer again, if it has one.

pub fn get_at(&self, slot: usize) -> Option<Value>

Read the value in the given slot, if it has been initialized.

pub fn set_at(&self, slot: usize, value: Value) -> Result<(), GlobalsError>

Write the value in the given slot.

pub fn clear_at(&self, slot: usize) -> Result<(), GlobalsError>

Reset the given slot back to being uninitialized.

pub fn is_initialized(&self, slot: usize) -> bool

Test if the given slot has been initialized.

Trait Implementations

impl Clone for Globals

fn clone(&self) -> Globals

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Globals

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

Formats the value using the given formatter.

impl Default for Globals

fn default() -> Globals

Returns the “default value” for a type.

impl TryClone for Globals

fn try_clone(&self) -> Result<Self>

Try to clone the current value, raising an allocation error if it’s unsuccessful.

fn try_clone_from(&mut self, source: &Self) -> Result<(), Error>

Performs copy-assignment from source.