In OwnedPtrDeleter<T>, store a vptr for a behavior function.
[zcpointer.git] / README.md
1 # zcpointer: Zero-Cost Poisoning Unique Pointers
2
3 The zcpointer library is a specialization of
4 [std::unique\_ptr](http://en.cppreference.com/w/cpp/memory/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.
7
8 The library provides three types to do this:
9
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.
14 - `zc::member<T>` is used to wrap member or local variables that should be constructed in-place, but
15   which may have pointers-to vended out to other objects. This overloads `zc::member<T>::operator&`
16   to return a `zc::ref<T>` when taking the address.
17
18 To achieve zero-cost, the zcpointer library can be compiled with or without the
19 `ZCPOINTER_TRACK_REFS` option. When disabled, `zc::owned` is just a type alias for `std::unique_ptr`
20 and `zc::ref` is a type alias for a raw pointer. With the option turned on, however, it becomes
21 impossible to unwrap a `zc::owned` into a raw pointer. All object access has to be indirected via a
22 `ref` object. When an `owned` object is deleted, it notifies all the outstanding `ref`s so that they
23 can be poisoned against future use.
24
25 When the tracking option is disabled and compiler optimization is turned up, the cost of using
26 zcpointer is none, compared to using a normal `unique_ptr`.
27
28 ## Suggested Usage
29
30 When using zcpointer, it is recommended to compile with `ZCPOINTER_TRACK_REFS` for debug builds, or
31 if your project provides a hardened compilation mode (such as `_FORTIFY_SOURCE`). For production
32 builds, turn off reference tracking to eliminate the overhead of zcpointer. Tests should be run
33 using `ZCPOINTER_TRACK_REFS=1` to catch errors during development.