pointers

This crate provide two traits for generic coding:

• Pointer trait:

  • raw pointers: *const T, *mut T, NonNull<T>,
  • owned: Box<T>,
  • multiple-ownership:
    • Rc<T>, Arc<T>
    • WaitGroupZeroGuard: see the doc in crossfire crate

• SmartPointer: type that has new() method

Irc (Intrusive Reference Counter)

Irc is an intrusive reference counting smart pointer, similar to Arc but without weak reference support. It requires the inner type to implement IrcItem trait to provide a counter field.

The underlayer of Irc can be any types implementing Pointer (default to be Box), unlike Arc which wrap a hidden ArcInner on your inner types, Irc use the pointer of your inner types by Pointer::into_raw

The atomic ordering is mostly the same with std Arc (miri test cases verified)

Benefits

• No need to manual implementing the inc / dec on counter.

• No enforced weak counter if you don't need it (every atomic op has cost).

• Customized counter type (not limited to AtomicUsize)

• IrcItem::on_drop in the trait allow you to have the ownship of underlying inner memory after the reference count of Irc is dropped. And you only need to define the drop behavior once, instead of write the same logic Arc::into_inner in every possible places (If forgetting so make your code block and hard to debug).

• Using Irc to wrap a Box, no additional memory allocation and memory fragmentation, no additional dereference cost (than using Arc<Box<T>>)

• You can allocate a box from the time of its birth and wrap it will Irc for temporary usage, don't need to move bytes from / to stack. (especially when the inner object is large)

• Advanced usage, multiple layer customized counter, on the same heap object, while preserving the safe boundary

See module document for more.

Feature Flags

• default: only the traits.
• irc: Enables the irc (intrusive ref count) module.