doc: "mut" not needed for the examples

[rust.git] / src / libstd / panic.rs

diff --git a/src/libstd/panic.rs b/src/libstd/panic.rs
index 3677bd27b16194f90fe6b37f8439c9735331647b..5c2e36623cbed160badc10f127a70c3e76a213dd 100644 (file)
--- a/src/libstd/panic.rs
+++ b/src/libstd/panic.rs
@@ -84,7 +84,7 @@
 /// recover safe. The general idea is that any mutable state which can be shared
 /// across `recover` is not recover safe by default. This is because it is very
 /// easy to witness a broken invariant outside of `recover` as the data is
-/// simply accesed as usual.
+/// simply accessed as usual.
 ///
 /// Types like `&Mutex<T>`, however, are recover safe because they implement
 /// poisoning by default. They still allow witnessing a broken invariant, but
@@ -129,6 +129,9 @@ pub trait RefRecoverSafe {}
 ///
 /// # Examples
 ///
+/// One way to use `AssertRecoverSafe` is to assert that the entire closure
+/// itself is recover safe, bypassing all checks for all variables:
+///
 /// ```
 /// #![feature(recover, std_panic)]
 ///
@@ -144,10 +147,33 @@ pub trait RefRecoverSafe {}
 /// // });
 ///
 /// // This, however, will compile due to the `AssertRecoverSafe` wrapper
+/// let result = panic::recover(AssertRecoverSafe::new(|| {
+///     variable += 3;
+/// }));
+/// // ...
+/// ```
+///
+/// Wrapping the entire closure amounts to a blanket assertion that all captured
+/// variables are recover safe. This has the downside that if new captures are
+/// added in the future, they will also be considered recover safe. Therefore,
+/// you may prefer to just wrap individual captures, as shown below. This is
+/// more annotation, but it ensures that if a new capture is added which is not
+/// recover safe, you will get a compilation error at that time, which will
+/// allow you to consider whether that new capture in fact represent a bug or
+/// not.
+///
+/// ```
+/// #![feature(recover, std_panic)]
+///
+/// use std::panic::{self, AssertRecoverSafe};
+///
+/// let mut variable = 4;
+/// let other_capture = 3;
+///
 /// let result = {
 ///     let mut wrapper = AssertRecoverSafe::new(&mut variable);
 ///     panic::recover(move || {
-///         **wrapper += 3;
+///         **wrapper += other_capture;
 ///     })
 /// };
 /// // ...
@@ -193,6 +219,12 @@ impl<T> AssertRecoverSafe<T> {
     pub fn new(t: T) -> AssertRecoverSafe<T> {
         AssertRecoverSafe(t)
     }
+
+    /// Consumes the `AssertRecoverSafe`, returning the wrapped value.
+    #[unstable(feature = "recover", reason = "awaiting feedback", issue = "27719")]
+    pub fn into_inner(self) -> T {
+        self.0
+    }
 }
 
 impl<T> Deref for AssertRecoverSafe<T> {
@@ -209,6 +241,14 @@ fn deref_mut(&mut self) -> &mut T {
     }
 }
 
+impl<R, F: FnOnce() -> R> FnOnce<()> for AssertRecoverSafe<F> {
+    type Output = R;
+
+    extern "rust-call" fn call_once(self, _args: ()) -> R {
+        (self.0)()
+    }
+}
+
 /// Invokes a closure, capturing the cause of panic if one occurs.
 ///
 /// This function will return `Ok` with the closure's result if the closure