diff --git a/README.md b/README.md index 8acd8c9..0ae9540 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ ![Tests status](https://github.com/EricLBuehler/trc/actions/workflows/tests.yml/badge.svg) `Trc` is a performant heap-allocated smart pointer for Rust that implements a version of biased reference counting. -`Trc` stands for: Thread Reference Counted. -`Trc` provides a shared ownership of the data similar to `Arc` and `Rc`. +`Trc` stands for: Thread Reference Counted. +`Trc` provides a shared ownership of the data similar to `Arc` and `Rc`. It implements a custom version of biased reference counting, which is based on the observation that most objects are only used by one thread. This means that two reference counts can be created: one for thread-local use, and one atomic one for sharing between threads. This implementation of biased reference counting sets the atomic reference count to the number of threads using the data. @@ -17,7 +17,7 @@ A `Weak` is a non-owning reference to the data held by a `Trc`. They break reference cycles by adding a layer of indirection and act as an observer. They cannot even access the data directly, and must be converted back into `Trc`. `Weak` does not keep the value alive (whcih can be dropped), and only keeps the backing allocation alive. -To soundly implement thread safety `Trc` does not itself implement `Send` or `Sync`. However, `SharedTrc` does, and it is the only way to safely send a `Trc` across threads. See `SharedTrc` for it's API, which is similar to that of `Weak`. +To soundly implement thread safety `Trc` does not implement `Send` or `Sync`. However, `SharedTrc` does, and it is the only way to safely send a `Trc` across threads. See `SharedTrc` for it's API, which is similar to that of `Weak`. ## Examples diff --git a/src/lib.rs b/src/lib.rs index ffbd905..bb1965d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,16 +1,18 @@ //! If you find any issues with `Trc`, I would greatly appreciate you submitting a pull request or issue to the [GitHub page](https://github.com/EricLBuehler/trc). //! -//! `Trc` is a heap-allocated smart pointer for sharing data across threads is a thread-safe and performant manner. -//! `Trc` stands for: Thread Reference Counted. -//! `Trc` provides shared ownership of the data similar to `Arc` and `Rc`. In addition, it also provides interior mutability. -//! It implements a custom version of biased reference counting, which is based on the observation that most objects are only used by one thread. -//! This means that two reference counts can be created: one for thread-local use, and one atomic one for sharing between threads. +//! `Trc` is a performant heap-allocated smart pointer for Rust that implements a version of biased reference counting. +//! `Trc` stands for: Thread Reference Counted. +//! `Trc` provides shared ownership of the data similar to `Arc` and `Rc`. +//! It implements biased reference counting, which is based on the observation that most objects are only used by one thread. +//! This means that two reference counts can be created: one for local thread use, and one atomic one for sharing between threads. //! This implementation of biased reference counting sets the atomic reference count to the number of threads using the data. //! +//! ## Breaking reference cycles with `Weak` //! A cycle between `Trc` pointers cannot be deallocated as the reference counts will never reach zero. The solution is a `Weak`. //! A `Weak` is a non-owning reference to the data held by a `Trc`. //! They break reference cycles by adding a layer of indirection and act as an observer. They cannot even access the data directly, and -//! must be converted back into `Trc`. `Weak` does not keep the value alive (which can be dropped), and only keeps the backing allocation alive. +//! must be converted back into `Trc`. `Weak` does not keep the value alive (whcih can be dropped), and only keeps the backing allocation alive. +//! See [`Weak`] for more information. extern crate alloc; diff --git a/src/trc.rs b/src/trc.rs index 2576f16..9f1e355 100644 --- a/src/trc.rs +++ b/src/trc.rs @@ -27,9 +27,9 @@ pub struct SharedTrcInternal { pub data: T, } -/// `Trc` is a performant heap-allocated smart pointer for Rust that implements a version of biased reference counting. -/// `Trc` stands for: Thread Reference Counted. -/// `Trc` provides shared ownership of the data similar to `Arc` and `Rc`. In addition, it also provides interior mutability. +/// `Trc` is a performant heap-allocated smart pointer for Rust that implements a version of biased reference counting. +/// `Trc` stands for: Thread Reference Counted. +/// `Trc` provides shared ownership of the data similar to `Arc` and `Rc`. /// It implements biased reference counting, which is based on the observation that most objects are only used by one thread. /// This means that two reference counts can be created: one for local thread use, and one atomic one for sharing between threads. /// This implementation of biased reference counting sets the atomic reference count to the number of threads using the data.