Struct TokenRefCell

pub struct TokenRefCell<T: ?Sized, Tk: Token + ?Sized = BoxToken> { /* private fields */ }

Interior mutability cell using an external Token reference to synchronize accesses.

Contrary to other standard cells like RefCell, TokenRefCell is Sync as long as its token is Send + Sync.

Memory layout

TokenRefCell<T> has the same in-memory representation as its inner type T when Token::Id is ().

Implementations

impl<T, Tk: Token + ?Sized> TokenRefCell<T, Tk>

pub fn new(value: T, token: &Tk) -> Self

where <<<Tk as Token>::Id as TokenId>::CellRepr as CellRepr<Tk::Id>>::Cell<T>: Sized,

Creates a new TokenRefCell containing a value, synchronized by the given token.

Examples found in repository

examples/graph.rs (line 98)

    fn new_cell(id: NodeId, token: &BoxToken) -> Arc<TokenRefCell<Node>> {
        let edges = HashMap::new();
        Arc::new(TokenRefCell::new(Node { id, edges }, token))
    }

pub fn new_const(value: T) -> Self

where Tk: Token<Id = ()>,

Creates a new TokenRefCell containing a value, synchronized by a const token.

pub fn with_token_id(value: T, token_id: Tk::Id) -> Self

where <<<Tk as Token>::Id as TokenId>::CellRepr as CellRepr<Tk::Id>>::Cell<T>: Sized,

Creates a new TokenRefCell containing a value, synchronized by a token with the given id.

It allows creating TokenRefCell when token is already borrowed.

pub fn into_inner(self) -> T

where <<<Tk as Token>::Id as TokenId>::CellRepr as CellRepr<Tk::Id>>::Cell<T>: Sized,

Consumes the TokenRefCell, returning the wrapped value.

impl<T: ?Sized, Tk: Token + ?Sized> TokenRefCell<T, Tk>

pub fn borrow<'a>(&'a self, token: &'a Tk) -> Ref<'a, T, Tk>

Immutably borrows the wrapped value using a shared reference to the token.

The token reference is reborrowed in the returned Ref, preventing any aliasing mutable borrow. Multiple immutable borrows can be taken out at the same time.

The check runtime cost is only a token id comparison (when the token is not a singleton_token!); there is no write, contrary to RefCell or locks.

Panics

Panics if the token doesn’t match the one used at cell initialization (or set with set_token). For a non-panicking variant, use try_borrow.

Examples found in repository

examples/graph.rs (line 30)

    pub fn get_node(&self, id: NodeId) -> Option<&Node> {
        Some(self.nodes.get(&id)?.borrow(&self.token).into_ref())
    }

pub fn try_borrow<'a>( &'a self, token: &'a Tk, ) -> Result<Ref<'a, T, Tk>, BorrowError>

Tries to immutably borrow the wrapped value using a shared reference to the token.

Returns an error if the token doesn’t match the one used at cell initialization (or set with set_token). This is the non-panicking variant of borrow.

The token reference is reborrowed in the returned Ref, preventing any aliasing mutable borrow. Multiple immutable borrows can be taken out at the same time.

The check runtime cost is only a token id comparison (when the token is not a singleton_token!); there is no write, contrary to RefCell or locks.

pub fn borrow_mut<'a>(&'a self, token: &'a mut Tk) -> RefMut<'a, T, Tk>

Mutably borrows the wrapped value using an exclusive reference to the token.

The token reference is reborrowed in the returned RefMut, preventing any aliasing mutable/immutable borrow.

The check runtime cost is only a token id comparison (when the token is not a singleton_token!), as well as a token unicity check (mostly a noop for most of the token implementations); there is no write, contrary to RefCell or locks.

Panics

Panics if the token doesn’t match the one used at cell initialization (or set with set_token), or if the token is not unique. For a non-panicking variant, use try_borrow.

Examples found in repository

examples/graph.rs (line 44)

    pub fn remove_node(&mut self, id: NodeId) -> bool {
        let Some(node) = self.nodes.remove(&id) else {
            return false;
        };
        let mut node_mut = node.borrow_mut(&mut self.token);
        let mut reborrow_mut =
            node_mut.reborrow_stateful_mut(|node| node.edges.values().map(AsRef::as_ref));
        while let Some(mut other) = reborrow_mut.reborrow_opt_mut(|edges| edges.next()) {
            other.edges.remove(&id);
        }
        true
    }

    pub fn insert_edge(&mut self, node1: NodeId, node2: NodeId) {
        let mut node = |id| {
            let entry = self.nodes.entry(id);
            let node = entry.or_insert_with(|| Node::new_cell(node1, &self.token));
            node.clone()
        };
        let node_cell1 = node(node1);
        let node_cell2 = node(node2);
        node_cell1
            .borrow_mut(&mut self.token)
            .edges
            .insert(node2, node_cell2.clone());
        node_cell2
            .borrow_mut(&mut self.token)
            .edges
            .insert(node1, node_cell1);
    }

    pub fn remove_edge(&mut self, node1: NodeId, node2: NodeId) {
        let mut remove = |a, b| {
            let Some(node) = self.nodes.get(&a) else {
                return false;
            };
            node.borrow_mut(&mut self.token).edges.remove(&b);
            true
        };
        if remove(node1, node2) {
            remove(node2, node1);
        }
    }

pub fn try_borrow_mut<'a>( &'a self, token: &'a mut Tk, ) -> Result<RefMut<'a, T, Tk>, BorrowMutError>

Mutably borrows the wrapped value using an exclusive reference to the token.

Returns an error if the token doesn’t match the one used at cell initialization (or set with set_token), or if the token is not unique. For a non-panicking variant, use try_borrow.

The token reference is reborrowed in the returned RefMut, preventing any aliasing mutable/immutable borrow.

The check runtime cost is only a token id comparison (when the token is not a singleton_token!), as well as a token unicity check (mostly a noop for most of the token implementations); there is no write, contrary to RefCell or locks.

Examples found in repository

examples/graph.rs (line 87)

    pub fn clear(&mut self) {
        let mut nodes = mem::take(&mut self.nodes);
        for (_, node) in nodes.drain() {
            if let Ok(mut node) = node.try_borrow_mut(&mut self.token) {
                node.edges.clear();
            }
        }
        self.nodes = nodes;
    }

pub fn as_ptr(&self) -> *mut T

Gets a mutable pointer to the wrapped value.

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

Returns a mutable reference to the underlying data.

pub fn from_ref(t: &mut T) -> &Self

where Tk: Token<Id = ()>,

Returns a &TokenRefCell<T, Tk> from a &mut T

pub fn set_token(&mut self, token: &Tk)

Set a new token to synchronize the cell.

pub fn token_id(&self) -> Tk::Id

Get the id of the token by which the cell is synchronized.

pub fn set_token_id(&mut self, token_id: Tk::Id)

Set a new token_id to synchronize the cell.

impl<T, Tk: Token<Id = ()> + ?Sized> TokenRefCell<[T], Tk>

pub fn as_slice_of_cells(&self) -> &[TokenRefCell<T, Tk>]

where Tk: Token<Id = ()>,

Returns a &[TokenRefCell<T>] from a &TokenRefCell<[T]>

Trait Implementations

impl<T: ?Sized, Tk: Token + ?Sized> AsRef<TokenRefCell<T, Tk>> for &TokenRefCell<T, Tk>

fn as_ref(&self) -> &TokenRefCell<T, Tk>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: ?Sized + Debug, Tk: Token + ?Sized> Debug for TokenRefCell<T, Tk>

where Tk::Id: Debug,

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

Formats the value using the given formatter.

impl<T: ?Sized + Sync, Tk> Sync for TokenRefCell<T, Tk>

where Tk: Send + Sync + Token + ?Sized,