Summary

Introduce non-panicking borrow methods on RefCell<T>.

Motivation

Whenever something is built from user input, for example a graph in which nodes are RefCell<T> values, it is primordial to avoid panicking on bad input. The only way to avoid panics on cyclic input in this case is a way to conditionally-borrow the cell contents.

Detailed design

/// Returned when `RefCell::try_borrow` fails.
pub struct BorrowError { _inner: () }

/// Returned when `RefCell::try_borrow_mut` fails.
pub struct BorrowMutError { _inner: () }

impl RefCell<T> {
    /// Tries to immutably borrows the value. This returns `Err(_)` if the cell
    /// was already borrowed mutably.
    pub fn try_borrow(&self) -> Result<Ref<T>, BorrowError> { ... }

    /// Tries to mutably borrows the value. This returns `Err(_)` if the cell
    /// was already borrowed.
    pub fn try_borrow_mut(&self) -> Result<RefMut<T>, BorrowMutError> { ... }
}

Drawbacks

This departs from the fallible/infallible convention where we avoid providing both panicking and non-panicking methods for the same operation.

Alternatives

The alternative is to provide a borrow_state method returning the state of the borrow flag of the cell, i.e:

pub enum BorrowState {
    Reading,
    Writing,
    Unused,
}

impl<T> RefCell<T> {
    pub fn borrow_state(&self) -> BorrowState { ... }
}

See the Rust tracking issue for this feature.

Unresolved questions

There are no unresolved questions.