rustdoc the table

crates/wasi-common/src/table.rs

@@ -3,12 +3,20 @@ use std::any::Any;
 use std::cell::{Ref, RefCell, RefMut};
 use std::collections::HashMap;
 
+/// The `Table` type is designed to map u32 handles to resources. The table is now part of the
+/// public interface to a `WasiCtx` - it is reference counted so that it can be shared beyond a
+/// `WasiCtx` with other WASI proposals (e.g. `wasi-crypto` and `wasi-nn`) to manage their
+/// resources. Elements in the `Table` are `Any` typed.
+///
+/// The `Table` type is intended to model how the Interface Types concept of Resources is shaping
+/// up. Right now it is just an approximation.
 pub struct Table {
     map: HashMap<u32, RefCell<Box<dyn Any>>>,
     next_key: u32,
 }
 
 impl Table {
+    /// Create an empty table. New insertions will begin at 3, above stdio.
     pub fn new() -> Self {
         Table {
             map: HashMap::new(),
@@ -16,10 +24,12 @@ impl Table {
         }
     }
 
+    /// Insert a resource at a certain index.
     pub fn insert_at(&mut self, key: u32, a: Box<dyn Any>) {
         self.map.insert(key, RefCell::new(a));
     }
 
+    /// Insert a resource at the next available index.
     pub fn push(&mut self, a: Box<dyn Any>) -> Result<u32, Error> {
         loop {
             let key = self.next_key;
@@ -37,10 +47,13 @@ impl Table {
         }
     }
 
+    /// Check if the table has a resource at the given index.
     pub fn contains_key(&self, key: u32) -> bool {
         self.map.contains_key(&key)
     }
 
+    /// Check if the resource at a given index can be downcast to a given type.
+    /// Note: this will always fail if the resource is already borrowed.
     pub fn is<T: Any + Sized>(&self, key: u32) -> bool {
         if let Some(refcell) = self.map.get(&key) {
             if let Ok(refmut) = refcell.try_borrow_mut() {
@@ -53,6 +66,9 @@ impl Table {
         }
     }
 
+    /// Get an immutable reference to a resource of a given type at a given index. Multiple
+    /// immutable references can be borrowed at any given time. Borrow failure
+    /// results in a trapping error.
     pub fn get<T: Any + Sized>(&self, key: u32) -> Result<Ref<T>, Error> {
         if let Some(refcell) = self.map.get(&key) {
             if let Ok(r) = refcell.try_borrow() {
@@ -69,6 +85,8 @@ impl Table {
         }
     }
 
+    /// Get a mutable reference to a resource of a given type at a given index. Only one mutable
+    /// reference can be borrowed at any given time. Borrow failure results in a trapping error.
     pub fn get_mut<T: Any + Sized>(&self, key: u32) -> Result<RefMut<T>, Error> {
         if let Some(refcell) = self.map.get(&key) {
             if let Ok(r) = refcell.try_borrow_mut() {
@@ -85,21 +103,9 @@ impl Table {
         }
     }
 
+    /// Remove a resource at a given index from the table. Returns the resource
+    /// if it was present.
     pub fn delete(&mut self, key: u32) -> Option<Box<dyn Any>> {
         self.map.remove(&key).map(|rc| RefCell::into_inner(rc))
     }
-
-    pub fn update_in_place<T, F>(&mut self, key: u32, f: F) -> Result<(), Error>
-    where
-        T: Any + Sized,
-        F: FnOnce(T) -> Result<T, Error>,
-    {
-        let entry = self.delete(key).ok_or(Error::badf())?;
-        let downcast = entry
-            .downcast::<T>()
-            .map_err(|_| Error::exist().context("element is a different type"))?;
-        let new = f(*downcast)?;
-        self.insert_at(key, Box::new(new));
-        Ok(())
-    }
 }