From 57063ad386b512c48cec11abf991e4dda7c4c55a Mon Sep 17 00:00:00 2001
From: Anthony Ramine <n.oxyde@gmail.com>
Date: Mon, 27 Jun 2016 12:28:08 +0200
Subject: [PATCH] Introduce non-panicking borrow methods on `RefCell<T>`

---
 text/0000-try-borrow.md | 64 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 text/0000-try-borrow.md

diff --git a/text/0000-try-borrow.md b/text/0000-try-borrow.md
new file mode 100644
index 00000000000..b92f400b996
--- /dev/null
+++ b/text/0000-try-borrow.md
@@ -0,0 +1,64 @@
+- 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<T>`.
+
+# Motivation
+[motivation]: #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
+[design]: #detailed-design
+
+```rust
+impl RefCell<T> {
+    /// Tries to immutably borrows the value. This returns `None` if the cell
+    /// was already borrowed mutably.
+    pub fn try_borrow(&self) -> Option<Ref<T>> { ... }
+
+    /// Tries to mutably borrows the value. This returns `None` if the cell
+    /// was already borrowed.
+    pub fn try_borrow_mut(&self) -> Option<RefMut<T>> { ... }
+}
+```
+
+# 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` methods returning the state
+of the borrow flag of the cell, i.e:
+
+```rust
+pub enum BorrowState {
+    Reading,
+    Writing,
+    Unused,
+}
+
+impl<T> RefCell<T> {
+    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.