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.