Skip to content

Latest commit

 

History

History
67 lines (41 loc) · 2.4 KB

README.md

File metadata and controls

67 lines (41 loc) · 2.4 KB
Raw

StaticRc is a safe reference-counted pointer, similar to Rc or Arc, though performing its reference-counting at compile-time rather than run-time, and therefore avoiding most run-time overhead.

Motivating Example

A number of collections, such as linked-lists, binary-trees, or B-Trees are most easily implemented with aliasing pointers.

Traditionally, this requires either unsafe raw pointers, or using Rc or Arc depending on the scenario. A key observation, however, is that in those collections the exact number of aliases is known at compile-time:

  • A doubly linked-list has 2 pointers to each node.
  • A binary-tree has 3 pointers to each node: one from the parent, and one from each child.
  • A B-Tree of cardinality N has N+1 pointers to each node.

In this type of scenario, static-rc offers the safety of Rc and Arc, with the performance of unsafe raw pointers.

Goals

Provide safe and efficient reference-counting:

  • Efficiency: most associated functions boil down to copying a NonNull<T>, a trivial operation.
    • One key exception are join functions: a run-time check must be performed to ensure the instances being joined refer to the same pointer. Unsafe unchecked variants are available if their overhead is too high.
  • Safety: most associated functions are safe to use.
    • The few unsafe functions are strictly optional.

Maturity

This crate is still very much experimental.

Review:

  • Minimally reviewed.
  • Not audited.
  • Not formally proven.

Documentation:

  • All StaticRc associated functions are documented, with example.
  • All StaticRcRef associated functions are documented, with example.

Testing:

  • All compile-time assertions are tested with compile-fail tests.
  • All panics are tested with panic tests.
  • Miri runs the test-suite without any complain.

Debug checks

This library contains a number of additional checks when building with debug_assertions, in particular the Drop implementation of StaticRc will catch any attempt at destroying a StaticRc<T, N, D> where N <> D, as this would typically result in a leak.

Those checks are not strictly necessary for safety, they are included to help point out logic errors.

From experience, the Drop check on top of an extensive test-suite will help catch all those instances where one path accidentally let a pointer drop.

That's all folks!

And thanks for reading.