diff --git a/text/0000-try-borrow.md b/text/0000-try-borrow.md new file mode 100644 index 00000000000..8487204f0ff --- /dev/null +++ b/text/0000-try-borrow.md @@ -0,0 +1,70 @@ +- Feature Name: try_borrow +- Start Date: 2016-06-27 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +Introduce non-panicking borrow methods on `RefCell`. + +# Motivation +[motivation]: #motivation + +Whenever something is built from user input, for example a graph in which nodes +are `RefCell` 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 +[design]: #detailed-design + +```rust +/// Returned when `RefCell::try_borrow` fails. +pub struct BorrowError { _inner: () } + +/// Returned when `RefCell::try_borrow_mut` fails. +pub struct BorrowMutError { _inner: () } + +impl RefCell { + /// Tries to immutably borrows the value. This returns `Err(_)` if the cell + /// was already borrowed mutably. + pub fn try_borrow(&self) -> Result, BorrowError> { ... } + + /// Tries to mutably borrows the value. This returns `Err(_)` if the cell + /// was already borrowed. + pub fn try_borrow_mut(&self) -> Result, BorrowMutError> { ... } +} +``` + +# Drawbacks +[drawbacks]: #drawbacks + +This departs from the fallible/infallible convention where we avoid providing +both panicking and non-panicking methods for the same operation. + +# Alternatives +[alternatives]: #alternatives + +The alternative is to provide a `borrow_state` method returning the state +of the borrow flag of the cell, i.e: + +```rust +pub enum BorrowState { + Reading, + Writing, + Unused, +} + +impl RefCell { + pub fn borrow_state(&self) -> BorrowState { ... } +} +``` + +See [the Rust tracking issue](https://github.com/rust-lang/rust/issues/27733) +for this feature. + +# Unresolved questions +[unresolved]: #unresolved-questions + +There are no unresolved questions.