1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
//! [![github]](https://github.com/dtolnay/threadbound) [![crates-io]](https://crates.io/crates/threadbound) [![docs-rs]](https://docs.rs/threadbound)
//!
//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
//!
//! <br>
//!
//! [`ThreadBound<T>`] is a wrapper that binds a value to its original thread.
//! The wrapper gets to be [`Sync`] and [`Send`] but only the original thread on
//! which the ThreadBound was constructed can retrieve the underlying value.
//!
//! [`ThreadBound<T>`]: struct.ThreadBound.html
//! [`Sync`]: https://doc.rust-lang.org/std/marker/trait.Sync.html
//! [`Send`]: https://doc.rust-lang.org/std/marker/trait.Send.html
//!
//! # Example
//!
//! ```
//! use std::marker::PhantomData;
//! use std::rc::Rc;
//! use std::sync::Arc;
//! use threadbound::ThreadBound;
//!
//! // Neither Send nor Sync. Maybe the index points into a
//! // thread-local interner.
//! #[derive(Copy, Clone)]
//! struct Span {
//! index: u32,
//! marker: PhantomData<Rc<()>>,
//! }
//!
//! // Error types are always supposed to be Send and Sync.
//! // We can use ThreadBound to make it so.
//! struct Error {
//! span: ThreadBound<Span>,
//! message: String,
//! }
//!
//! fn main() {
//! let err = Error {
//! span: ThreadBound::new(Span {
//! index: 99,
//! marker: PhantomData,
//! }),
//! message: "fearless concurrency".to_owned(),
//! };
//!
//! // Original thread can see the contents.
//! assert_eq!(err.span.get_ref().unwrap().index, 99);
//!
//! let err = Arc::new(err);
//! let err2 = err.clone();
//! std::thread::spawn(move || {
//! // Other threads cannot get access. Maybe they use
//! // a default value or a different codepath.
//! assert!(err2.span.get_ref().is_none());
//! });
//!
//! // Original thread can still see the contents.
//! assert_eq!(err.span.get_ref().unwrap().index, 99);
//! }
//! ```
#![doc(html_root_url = "https://docs.rs/threadbound/0.1.7")]
#![allow(clippy::doc_markdown)]
use std::fmt::{self, Debug};
use std::thread::{self, ThreadId};
/// ThreadBound is a Sync-maker and Send-maker that allows accessing a value
/// of type T only from the original thread on which the ThreadBound was
/// constructed.
///
/// Refer to the [crate-level documentation] for a usage example.
///
/// [crate-level documentation]: index.html
pub struct ThreadBound<T> {
value: T,
thread_id: ThreadId,
}
unsafe impl<T> Sync for ThreadBound<T> {}
// Send bound requires Copy, as otherwise Drop could run in the wrong place.
//
// Today Copy and Drop are mutually exclusive so `T: Copy` implies `T: !Drop`.
// This impl needs to be revisited if that restriction is relaxed in the future.
unsafe impl<T: Copy> Send for ThreadBound<T> {}
impl<T> ThreadBound<T> {
/// Binds a value to the current thread. The wrapper can be sent around to
/// other threads, but no other threads will be able to access the
/// underlying value.
pub fn new(value: T) -> Self {
ThreadBound {
value,
thread_id: thread::current().id(),
}
}
/// Accesses a reference to the underlying value if this is its original
/// thread, otherwise `None`.
pub fn get_ref(&self) -> Option<&T> {
if thread::current().id() == self.thread_id {
Some(&self.value)
} else {
None
}
}
/// Accesses a mutable reference to the underlying value if this is its
/// original thread, otherwise `None`.
pub fn get_mut(&mut self) -> Option<&mut T> {
if thread::current().id() == self.thread_id {
Some(&mut self.value)
} else {
None
}
}
/// Extracts ownership of the underlying value if this is its original
/// thread, otherwise `None`.
pub fn into_inner(self) -> Option<T> {
if thread::current().id() == self.thread_id {
Some(self.value)
} else {
None
}
}
}
impl<T: Default> Default for ThreadBound<T> {
fn default() -> Self {
ThreadBound::new(Default::default())
}
}
impl<T: Debug> Debug for ThreadBound<T> {
fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
match self.get_ref() {
Some(value) => Debug::fmt(value, formatter),
None => formatter.write_str("unknown"),
}
}
}