From 9952632a2f6fc0d5c41976070ba39f57be5ede0c Mon Sep 17 00:00:00 2001
From: Olivier Goffart <ogoffart@sixtyfps.io>
Date: Sat, 16 Jan 2021 10:29:21 +0100
Subject: [PATCH] Add sample code for Rc::new_cyclic

---
 library/alloc/src/rc.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/library/alloc/src/rc.rs b/library/alloc/src/rc.rs
index 0973a6e362b..d6f48238900 100644
--- a/library/alloc/src/rc.rs
+++ b/library/alloc/src/rc.rs
@@ -353,6 +353,26 @@ pub fn new(value: T) -> Rc<T> {
     /// to upgrade the weak reference before this function returns will result
     /// in a `None` value. However, the weak reference may be cloned freely and
     /// stored for use at a later time.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(arc_new_cyclic)]
+    /// #![allow(dead_code)]
+    /// use std::rc::{Rc, Weak};
+    ///
+    /// struct Gadget {
+    ///     self_weak: Weak<Self>,
+    ///     // ... more fields
+    /// }
+    /// impl Gadget {
+    ///     pub fn new() -> Rc<Self> {
+    ///         Rc::new_cyclic(|self_weak| {
+    ///             Gadget { self_weak: self_weak.clone(), /* ... */ }
+    ///         })
+    ///     }
+    /// }
+    /// ```
     #[unstable(feature = "arc_new_cyclic", issue = "75861")]
     pub fn new_cyclic(data_fn: impl FnOnce(&Weak<T>) -> T) -> Rc<T> {
         // Construct the inner in the "uninitialized" state with a single