CombArc

CombArc stands for "clone-on-mutable-borrow automatic reference counter", but it is essentially a copy-on-write that transparently wraps Arc::as_ref and Arc::make_mut around the Deref and DerefMut traits, respectively.

As such, it has the same effects when borrowed mutably as Arc::make_mut when called:

• If there are no other references, it borrows normally.
• If there are strong references, it gets cloned.
• If there are no strong references but there are weak references, then all weak references get dissociated and can no longer upgrade.

Note that interior mutability (e.g. Cell::set) won't trigger a clone.

This crate uses no unsafe code directly and only uses the alloc crate. It provides both a [CombArc] and [CombRc], the difference being that [CombArc] is atomic and thread-safe, where [CombRc] is not thread-safe and cannot be moved across threads.

Examples

In this example, [CombArc] is used, but [CombRc] can be used interchangeably here.

use combarc::CombArc;
use std::cell::Cell;

// Both of these will be the same value.
let mut my_value = CombArc::new(Cell::new(false));
let another_value = my_value.clone();
assert_eq!(my_value, another_value);

// Cell::set uses interior mutability and does not mutably borrow, so
// they still point to the same memory address.
my_value.set(true);
assert_eq!(my_value, another_value);
assert_eq!(my_value.as_ptr(), another_value.as_ptr());

// get_mut does mutably borrow, thus `my_value` is cloned.
*my_value.get_mut() = false;
assert_ne!(my_value, another_value);

// Also, if there is only one reference, `my_value` is not cloned.
let address_before = my_value.as_ptr();
*my_value.get_mut() = true;
let address_after = my_value.as_ptr();
assert_eq!(address_before, address_after);

// Despite not pointing to the same thing, these are equal now.
assert_ne!(my_value.as_ptr(), another_value.as_ptr());
assert_eq!(my_value, another_value);