diff --git a/README.md b/README.md index 4c150dd..5e93fae 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,12 @@ This library provides wrapper types that permit sending non Send types to other threads and use runtime checks to ensure safety. -It provides two types: `Fragile` and `Sticky` which are similar in nature but -have different behaviors with regards to how destructors are executed. The former -will panic if the destructor is called in another thread, the latter will temporarily -leak the object until the thread shuts down. +It provides the `Fragile`, `Sticky` and `SemiSticky` types which are +similar in nature but have different behaviors with regards to how destructors +are executed. The `Fragile` will panic if the destructor is called in another +thread, `Sticky` will temporarily leak the object until the thread shuts down. +`SemiSticky` is a compromise of the two. It behaves like `Sticky` but it +avoids the use of thread local storage if the type does not need `Drop`. ## Example diff --git a/src/lib.rs b/src/lib.rs index 0b66f43..2c68042 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -6,9 +6,9 @@ //! the extra [`SemiSticky`] type which uses [`Sticky`] if the value has a //! destructor and [`Fragile`] if it does not. //! -//! Both types wrap a value and provide a `Send` bound. Neither of the types permit +//! All three types wrap a value and provide a `Send` bound. Neither of the types permit //! access to the enclosed value unless the thread that wrapped the value is attempting -//! to access it. The difference between the two types starts playing a role once +//! to access it. The difference between the types starts playing a role once //! destructors are involved. //! //! A [`Fragile`] will actually send the `T` from thread to thread but will only @@ -18,11 +18,14 @@ //! A [`Sticky`] on the other hand does not actually send the `T` around but keeps //! it stored in the original thread's thread local storage. If it gets dropped //! in the originating thread it gets cleaned up immediately, otherwise it leaks -//! until the thread shuts down naturally. [`Sticky`] (and by extension -//! [`SemiSticky`]) because it borrows into the TLS also requires you to -//! "prove" that you are not doing any funny business with the borrowed value -//! that lives for longer than the current stack frame which results in a slightly -//! more complex API. +//! until the thread shuts down naturally. [`Sticky`] because it borrows into the +//! TLS also requires you to "prove" that you are not doing any funny business with +//! the borrowed value that lives for longer than the current stack frame which +//! results in a slightly more complex API. +//! +//! There is a third typed called [`SemiSticky`] which shares the API with [`Sticky`] +//! but internally uses a boxed [`Fragile`] if the type does not actually need a dtor +//! in which case [`Fragile`] is preferred. //! //! # Fragile Usage //! @@ -78,6 +81,16 @@ //! sendable extra information can be contained within the error and in cases where the //! error did not cross a thread boundary yet extra information can be obtained. //! +//! # Drop / Cleanup Behavior +//! +//! All types will try to eagerly drop a value if they are dropped on the right thread. +//! [`Sticky`] and [`SemiSticky`] will however temporarily leak memory until a thread +//! shuts down if the value is dropped on the wrong thread. The benefit however is that +//! if you have that type of situation, and you can live with the consequences, the +//! type is not panicking. A [`Fragile`] dropped in the wrong thread will not just panic, +//! it will effectively also tear down the process because panicking in destructors is +//! non recoverable. +//! //! # Features //! //! By default the crate has no dependencies. Optionally the `slab` feature can