Struct kernel::forth::BagOfHolding

pub struct BagOfHolding {
    idx: i32,
    inner: FixedVec<(i32, BohValue)>,
}

The Bag of Holding

The Bag of Holding contains type-erased items that can be retrieved with a provided i32 token. A token is provided on calling BagOfHolding::register(). At the registration time, the TypeId of the item is also recorded, and the item is moved into Box<T>, which is leaked and type erased.

When retrieving items from the Bag of Holding, the same token and type parameter T must be used for access. This access is made by calling BagOfHolding::get().

The purpose of this structure is to allow the forth userspace to use an i32 token, which fits into a single stack value, to refer to specific instances of data. This allows for forth-bound builtin functions to retrieve the referred objects in a type safe way.

Fields

idx: i32

inner: FixedVec<(i32, BohValue)>

Implementations

impl BagOfHolding

pub async fn new(max: usize) -> Self

Create a new BagOfHolding with a given max size

The kernel parameter is used to allocate HeapBox elements to store the type-erased elements residing in the BagOfHolding.

fn next_idx(&mut self) -> i32

Generate a new, currently unused, Bag of Holding token.

This token will never be zero, and a given bag of holding will never contain two items with the same token.

pub async fn register<T>(&mut self, item: T) -> Option<i32>

where T: 'static,

Place an item into the bag of holding

The item will be allocated into a HeapBox, and a non-zero i32 token will be returned on success.

Returns an error if the Bag of Holding is full.

At the moment there is no way to “unregister” an item, it will exist until the BagOfHolding is dropped.

pub fn get<T>(&self, idx: i32) -> Option<&T>

where T: 'static,

Attempt to retrieve an item from the Bag of Holding

This will only succeed if the same T is used as was used when calling BagOfHolding::register(), and if the token matches the one returned by register().

If the token is unknown, or the T does not match, None will be returned

At the moment, no get_mut functionality is provided. It could be, as the Bag of Holding represents ownership of the contained items, however it would not be possible to retrieve multiple mutable items at the same time. This could be added in the future if desired.