From 686cb1748f1fe72035eafc56d0340c100b95ab7b Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sat, 16 Nov 2024 19:00:36 +0000 Subject: [PATCH] docs --- src/lib.rs | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 2873b65..3545f96 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -85,14 +85,14 @@ use std::ptr::NonNull; /// /// To mutably access the data of more than one node at once, /// use -/// [`IsTokenMut::multi_static`], +/// [`IsTokenMut::multi_static`] +/// or /// [`IsTokenMut::multi_dynamic`]. -/// /// To avoid runtime aliasing checks, and take manual control of aliasing, /// you can /// [`.borrow_mut()`](Ptr::borrow_mut()) with -/// [`TokenMut::new_unchecked()`]. -/// Or, +/// [`TokenMut::new_unchecked()`]; +/// or, /// `p`[`.as_ptr()`](Ptr::as_ptr)[`.as_ref()`](NonNull::as_ref()) /// / /// `p`[`.as_ptr()`](Ptr::as_ptr)[`.as_mut()`](NonNull::as_mut()). @@ -442,6 +442,7 @@ impl NoAliasSingleton { //---------- stack ---------- +/// A `Ptr` borrowed from stack data pub struct Borrowed<'t, T: ?Sized> { ptr: Ptr, /// Variance and borrowing: @@ -469,6 +470,21 @@ impl<'t, T: ?Sized> Borrowed<'t, T> { /// /// Using `retained` is recommended: /// it will ensure that `Ptr`s are still live at that point. + /// + /// ## Unwinding + /// + /// Not that `Borrowed` comes with exciting hazards + /// in the presence of panics: + /// a typical use is to take a stack item, + /// link it temporarily into a data structure. + /// + /// If an unwind occurs before the item is unlinked again, + /// the data structure can be corrupted. + /// It is the responsibility of the user to avoid this situation. + /// + /// (Note that use of `Ptr` without `Borrowed` does also come with + /// hazards in the face of unwinding, + /// but those are typically just memory leaks.) pub unsafe fn new(t: &mut T) -> Self { Borrowed { ptr: Ptr::from_raw(NonNull::from(t)), -- 2.30.2