Struct forth3::AsyncForth

pub struct AsyncForth<T: 'static, A> {
    vm: Forth<T>,
    builtins: A,
}

Available on crate feature async only.

A Forth VM in which some builtin words are implemented by async fns (or Futures).

Asynchronous Forth VMs

Asynchronous builtins are asynchronous relative to the host context (i.e., the Rust program in which the Forth VM is embedded), rather than the Forth program that executes within the VM. This means that, unlike a synchronous Forth VM, the AsyncForth::process_line method is an async fn. When the Forth program executes a builtin word that is implemented by an async fn on the host, the AsyncForth::process_line will .await the Future that implements the builtin word, and will yield if the Future is not ready. This allows multiple AsyncForth VMs to run asynchronously in an async context on the host, yielding when the Forth programs in those VMs sleep or perform asynchronous I/O operations.

Providing Async Builtins

Unlike synchronous builtins, which are provided to the VM as a slice of BuiltinEntrys, asynchronous builtins require an implementation of the AsyncBuiltins trait, which provides both a slice of AsyncBuiltinEntrys and a method to dispatch builtin names to Futures. See the documentation for the AsyncBuiltins trait for details on providing async builtins.

Synchronous Builtins

An AsyncForth VM may also have synchronous builtin words. These behave identically to the synchronous builtins in a non-async Forth VM. Synchronous builtins should be used for any builtin word that does not require performing an asynchronous operation on the host, such as those which perform mathematical operations.

Synchronous builtins can be provided when the VM is constructed as a static slice of BuiltinEntrys. They may also be added at runtime using the AsyncForth::add_sync_builtin and AsyncForth::add_sync_builtin_static_name method. These methods are identical to the Forth::add_builtin and Forth::add_builtin_static_name methods.

Fields

vm: Forth<T>

builtins: A

Implementations

impl<T, A> AsyncForth<T, A>

where T: 'static, A: for<'forth> AsyncBuiltins<'forth, T>,

pub fn from_forth(vm: Forth<T>, builtins: A) -> Self

Construct a new AsyncForth from the provided synchronous VM and async builtins.

pub unsafe fn new( bufs: Buffers<T>, dict: OwnedDict<T>, host_ctxt: T, sync_builtins: &'static [BuiltinEntry<T>], async_builtins: A, ) -> Result<Self, Error>

pub unsafe fn fork( &mut self, bufs: Buffers<T>, new_dict: OwnedDict<T>, my_dict: OwnedDict<T>, host_ctxt: T, ) -> Result<Self, Error>

where A: Clone,

Constructs a new VM whose dictionary is a fork of this VM’s dictionary.

The current dictionary owned by this VM is frozen (made immutable), and a reference to it is shared with this VM and the new child VM. When both this VM and the child are dropped, the frozen dictionary is deallocated.

This function takes two OwnedDicts as arguments: new_dict is the dictionary allocation for the forked child VM, while my_dict is a new allocation for this VM’s mutable dictionary (which replaces the current dictionary, as it will become frozen).

The child VM is created with empty stacks, and the provided input and output buffers.

Safety

This method requires the same invariants be upheld as AsyncForth::new.

pub fn output(&self) -> &OutputBuf

Borrows this VM’s OutputBuf.

pub fn output_mut(&mut self) -> &mut OutputBuf

Mutably borrows this VM’s OutputBuf.

pub fn input_mut(&mut self) -> &mut WordStrBuf

Mutably borrows this VM’s input WordStrBuf.

pub fn host_ctxt(&self) -> &T

Borrows this VM’s host context.

pub fn host_ctxt_mut(&mut self) -> &mut T

Mutably borrows this VM’s host context.

pub fn add_sync_builtin_static_name( &mut self, name: &'static str, bi: fn(_: &mut Forth<T>) -> Result<(), Error>, ) -> Result<(), Error>

pub fn add_sync_builtin( &mut self, name: &str, bi: fn(_: &mut Forth<T>) -> Result<(), Error>, ) -> Result<(), Error>

pub async fn process_line(&mut self) -> Result<(), Error>

async fn async_pig(&mut self) -> Result<Step, Error>

pub fn release(self) -> T