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 two 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
  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.
  21
  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`.
  24
  25 ## Suggested Usage
  26
  27 When using zcpointer, it is recommended to compile with `ZCPOINTER_TRACK_REFS` for debug builds, or
  28 if your project provides a hardened compilation mode (such as `_FORTIFY_SOURCE`). For production
  29 builds, turn off reference tracking to eliminate the overhead of zcpointer. Tests should be run
  30 using `ZCPOINTER_TRACK_REFS=1` to catch errors during development.