[zcpointer.git] /
1 # zcpointer: Zero-Cost Poisoning Unique Pointers
3 The zcpointer library is a specialization of
4 [std::unique\_ptr]( that tracks and poisons weak
5 references. The goal is to allow C++ developers to write programs without _ever_ having a pointer
6 that is not automatically managed by a smart scoper.
8 The library provides two types to do this:
10 - `zc::owned<T>` provides an identical interface to `std::unique_ptr<T>`, but which can track outstanding
11 weak references.
12 - `zc::ref<T>` is the return value of `zc::owned<T>::get()`. It stands for a `T*` but is used to
13 ensure use-after-free does not occur.
15 To achieve zero-cost, the zcpointer library can be compiled with or without the
16 `ZCPOINTER_TRACK_REFS` option. When disabled, `zc::owned` is just a type alias for `std::unique_ptr`
17 and `zc::ref` is a type alias for a raw pointer. With the option turned on, however, it becomes
18 impossible to unwrap a `zc::owned` into a raw pointer. All object access has to be indirected via a
19 `ref` object. When an `owned` object is deleted, it notifies all the outstanding `ref`s so that they
20 can be poisoned against future use.
22 When the tracking option is disabled and compiler optimization is turned up, the cost of using
23 zcpointer is none, compared to using a normal `unique_ptr`.