From e499e5e13b23f945a6961eb92ff2b919d5c3777f Mon Sep 17 00:00:00 2001 From: Robert Sesek Date: Sat, 8 Oct 2016 16:14:29 -0400 Subject: [PATCH] Add a README. --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..52f6893 --- /dev/null +++ b/README.md @@ -0,0 +1,23 @@ +# zcpointer: Zero-Cost Poisoning Unique Pointers + +The zcpointer library is a specialization of +[std::unique\_ptr](http://en.cppreference.com/w/cpp/memory/unique_ptr) that tracks and poisons weak +references. The goal is to allow C++ developers to write programs without _ever_ having a pointer +that is not automatically managed by a smart scoper. + +The library provides two types to do this: + +- `zc::owned` provides an identical interface to `std::unique_ptr`, but which can track outstanding + weak references. +- `zc::ref` is the return value of `zc::owned::get()`. It stands for a `T*` but is used to + ensure use-after-free does not occur. + +To achieve zero-cost, the zcpointer library can be compiled with or without the +`ZCPOINTER_TRACK_REFS` option. When disabled, `zc::owned` is just a type alias for `std::unique_ptr` +and `zc::ref` is a type alias for a raw pointer. With the option turned on, however, it becomes +impossible to unwrap a `zc::owned` into a raw pointer. All object access has to be indirected via a +`ref` object. When an `owned` object is deleted, it notifies all the outstanding `ref`s so that they +can be poisoned against future use. + +When the tracking option is disabled and compiler optimization is turned up, the cost of using +zcpointer is none, compared to using a normal `unique_ptr`. -- 2.22.5