Updated docs

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<T>` and `Sticky<T>` 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<T>`, `Sticky<T>` and `SemiSticky<T>` types which are
+similar in nature but have different behaviors with regards to how destructors
+are executed.  The `Fragile<T>` will panic if the destructor is called in another
+thread, `Sticky<T>` will temporarily leak the object until the thread shuts down.
+`SemiSticky<T>` is a compromise of the two.  It behaves like `Sticky<T>` but it
+avoids the use of thread local storage if the type does not need `Drop`.
 
 ## Example
 

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