Skip to main content

Crate pointers

Crate pointers 

Source
Expand description

§pointers

This crate provide two traits for generic coding:

  • Pointer trait:

    • raw pointers: *const T, *mut T, NonNull<T>,
    • owned: Box<T>,
    • multiple-ownership:

  • CloneablePointer trait: like Rc<T>, Arc<T>, that allow increase strong count of raw pointer.

  • SmartPointer: type that has new() method

§PointerSpinLock

lock module

A spinlock packed with atomic pointer, low cost for writer side, for certain scenarios:

  • One writer thread and few reader threads. Writer can bypass the lock to read and clone.
  • Many objects, the contention on a single object is low.

§Irc (Intrusive Reference Counter)

irc module

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

§Feature Flags

  • default: only the traits.
  • irc: Enables the irc (intrusive ref count) module.
  • lock: Enables the lock (spinlock pointer storage) module.

Modules§

ircirc
Intrusive Reference Counter (Irc)
locklock
Spinlock packed inside AtomicPointer

Traits§

CloneablePointer
Pointer
Abstract pointer trait to support various pointer types in collections.
SmartPointer