✓ Uses Rust 2018 edition
|new 0.1.6||Jan 15, 2019|
|0.1.5||Jan 1, 2019|
|0.1.3||Dec 31, 2018|
#5 in #rcu
36 downloads per month
This crate provides easy to use smart-pointers with interior
mutability. These smart pointers use
RCU to allow
simultaneous reads and updates. They implement
Deref for reads,
which makes them both convenient (ergonomic) and fast on reads,
particularly for the
Arc version that would otherwise require taking
RwLock in order to read the pointer. The downside is
that old versions of the data are only freed when you have called the
clean method on each copy of the pointer.
This crate provides a set (eventually) of smart pointer types that allow read access with no guards (and minimal to no overhead) and no need to call [std::borrow::Borrow]. These smart pointers each allow internal mutability (obtaining mutable references) by a Read-Copy-Update approach, so you get a mutable reference to a private copy of the data, which you can mutate at will. When the mutation is complete the pointer is atomically updated. Old references to the data may still exist, and will still be a valid reference to the old data.
Basically, these smart pointers allow internal mutability through
a slow and painful process, while keeping read-only access both
fast and easy (in particular, no need to call
everywhere). Write access is guarded, but read access is not.
The names of the types are based on the standard smart pointer types.
[BoxRcu]is an owned pointer similar to [std::box::Box]. If you like, it is actually closer to
Box<RefCell<T>>, or even
Box<Mutex<T>>, but without the nuisance of having to call borrow when reading.
[RcRcu]is a reference counted pointer similar to [std::rc::Rc]. If you like, it is actually closer to
Rc<RefCell<T>>, but without the nuisance of having to call borrow when reading.
ArcRcuis planned to be a thread-safe reference counted pointer similar to [std::sync::Arc]. It is actually closer to
Arc<RwLock<T>>, but without the nuisance of having to call
Due to this crate's read-copy-update semantics, old copies of your
data are kept until we are confident that there are no longer any
references to them. Because we do not have any guards on the read
references, this must be done manually. This is the cost we pay
for extra convenience (and much improved read speed in the case of
ArcRcu) on the read operations. You have two options for how to
One option is to simply store those extra copies until then entire
smart pointer itself is freed. That is what happens if you do
nothing, and for small data that is only mutated once, it's a fine
option. However, for
[RcRcu] there will be a
slowdown on reading until you do call clean, since an extra level
of pointer redirection will be required.
The other option is to call
clean() when convenient.
&mut self, so when it is called, the compiler will prove
to us that there are no other references out there via this
smart pointer. For
BoxCell that is sufficient to prove that we
can free the data. In the case of the reference counted data
pointers, we keep track of a count of how many copies have been
dereferenced since the last time
clean was called. We could
probably be more accurate with "epoch" tracking, but I don't know
that the complexity will be worthwhile.