From a3ff79eb391843b6a6eb144992bd6782bf080019 Mon Sep 17 00:00:00 2001 From: Botahamec Date: Wed, 26 Oct 2022 22:51:31 -0400 Subject: Docs for ThreadKey --- src/lib.rs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index be3d05b..614820f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -8,6 +8,10 @@ thread_local! { pub static KEY: Mutex> = Mutex::new(Some(unsafe { ThreadKey::new() })); } +/// The key for the current thread. +/// +/// Only one of these exist per thread. To get the current thread's key, call +/// [`ThreadKey::lock`]. pub struct ThreadKey { _priv: *const (), // this isn't Send or Sync } @@ -19,16 +23,30 @@ impl Debug for ThreadKey { } impl ThreadKey { + /// Create a new `ThreadKey`. + /// + /// # Safety + /// + /// There should only be one `ThreadKey` per thread. unsafe fn new() -> Self { Self { _priv: std::ptr::null(), } } + /// Get the current thread's `ThreadKey, if it's not already taken. + /// + /// The first time this is called, it will successfully return a + /// `ThreadKey`. However, future calls to this function will return + /// [`None`], unless the key is unlocked first. pub fn lock() -> Option { KEY.with(|thread_lock| thread_lock.lock().take()) } + /// Unlocks the `ThreadKey`. + /// + /// After this method is called, a call to [`ThreadKey::lock`] will return + /// this `ThreadKey`. pub fn unlock(lock: ThreadKey) { KEY.with(|thread_lock| { let mut thread_lock = thread_lock.lock(); -- cgit v1.2.3