From 1c0ad538410b61f8011c7d8facd136a85138be61 Mon Sep 17 00:00:00 2001 From: Dario Nieuwenhuis Date: Wed, 19 May 2021 23:38:29 +0200 Subject: [PATCH] Unborrow docs --- embassy/src/util/mod.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/embassy/src/util/mod.rs b/embassy/src/util/mod.rs index 9dd96b90..88ae5c28 100644 --- a/embassy/src/util/mod.rs +++ b/embassy/src/util/mod.rs @@ -17,8 +17,27 @@ pub use portal::*; pub use signal::*; pub use waker::*; +/// Unsafely unborrow an owned singleton out of a `&mut`. +/// +/// It is intended to be implemented for owned peripheral singletons, such as `USART3` or `AnyPin`. +/// Unborrowing an owned `T` yields the same `T`. Unborrowing a `&mut T` yields a copy of the T. +/// +/// This allows writing HAL drivers that either own or borrow their peripherals, but that don't have +/// to store pointers in the borrowed case. +/// +/// Safety: this trait can be used to copy non-Copy types. Implementors must not cause +/// immediate UB when copied, and must not cause UB when copies are later used, provided they +/// are only used according the [`Self::unborrow`] safety contract. +/// pub unsafe trait Unborrow { + /// Unborrow result type type Target; + + /// Unborrow a value. + /// + /// Safety: This returns a copy of a singleton that's normally not + /// copiable. The returned copy must ONLY be used while the lifetime of `self` is + /// valid, as if it were accessed through `self` every time. unsafe fn unborrow(self) -> Self::Target; }