Struct forth3::AsyncForth

source ·
pub struct AsyncForth<T: 'static, A> {
    vm: Forth<T>,
    builtins: A,
}
Available on crate feature async only.
Expand description

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§

source§

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

source

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

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

source

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

source

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.

source

pub fn output(&self) -> &OutputBuf

Borrows this VM’s OutputBuf.

source

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

Mutably borrows this VM’s OutputBuf.

source

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

Mutably borrows this VM’s input WordStrBuf.

source

pub fn host_ctxt(&self) -> &T

Borrows this VM’s host context.

source

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

Mutably borrows this VM’s host context.

source

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

source

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

source

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

source

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

source

pub fn release(self) -> T

Auto Trait Implementations§

§

impl<T, A> Freeze for AsyncForth<T, A>
where A: Freeze, T: Freeze,

§

impl<T, A> RefUnwindSafe for AsyncForth<T, A>

§

impl<T, A> Send for AsyncForth<T, A>
where A: Send, T: Send,

§

impl<T, A> Sync for AsyncForth<T, A>
where A: Sync, T: Sync,

§

impl<T, A> Unpin for AsyncForth<T, A>
where A: Unpin, T: Unpin,

§

impl<T, A> UnwindSafe for AsyncForth<T, A>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.