Merge pull request #1 from cschreib/no_shared_ptr

Do not use shared_ptr for implementation, rename weak_ptr to observer_ptr

Author: cschreib

README.md

@@ -4,16 +4,16 @@
 
 ## Introduction
 
-This is a small header-only library, providing a unique-ownership smart pointer that can be observed with weak pointers. It is a mixture of `std::unique_ptr` and `std::shared_ptr`: it borrows the unique-ownership semantic of `std::unique_ptr` (movable, non-copiable), but allows creating `std::weak_ptr` instances to monitor the lifetime of the pointed object.
+This is a small header-only library, providing a unique-ownership smart pointer `observable_unique_ptr` that can be observed with non-owning pointers `observer_ptr`. It is a mixture of `std::unique_ptr` and `std::shared_ptr`: it borrows the unique-ownership semantic of `std::unique_ptr` (movable, non-copiable), but allows creating `observer_ptr` to monitor the lifetime of the pointed object (like `std::weak_ptr` for `std::shared_ptr`).
 
-This is useful for cases where the shared-ownership of `std::shared_ptr` is not desirable, e.g., when lifetime must be carefully controlled and not be allowed to extend, yet non-owning "weak" references to the object may exist after the object has been deleted.
+This is useful for cases where the shared-ownership of `std::shared_ptr` is not desirable, e.g., when lifetime must be carefully controlled and not be allowed to extend, yet non-owning/weak/observer references to the object may exist after the object has been deleted.
 
-Note: Because of the unique ownership model, weak pointers locking cannot extend the lifetime of the pointed object, hence `observable_unique_ptr` provides less thread-safety compared to `std::shared_ptr`. This is also true of `std::unique_ptr`, and is a fundamental limitation of unique ownership. Do not use this library if the lifetime of your objects is not well understood.
+Note: Because of the unique ownership model, observer pointers cannot extend the lifetime of the pointed object, hence `observable_unique_ptr`/`observer_ptr` provides less thread-safety compared to `std::shared_ptr`/`std::weak_ptr`. This is also true of `std::unique_ptr`, and is a fundamental limitation of unique ownership. If this is an issue, you will need either to add your own explicit locking logic, or use `std::shared_ptr`/`std::weak_ptr`.
 
 
 ## Usage
 
-This is a header-only library. You have multiple ways to set it up:
+This is a header-only library requiring a C++17-compliant compiler. You have multiple ways to set it up:
  - just include this repository as a submodule in your own git repository and use CMake `add_subdirectory`,
  - use CMake `FetchContent`,
  - download the header and include it in your own sources.
@@ -28,35 +28,34 @@ From there, include the single header `<oup/observable_unique_ptr.hpp>`, and dir
 #include <cassert>
 
 int main() {
-    // Weak pointer that will outlive the object
-    oup::weak_ptr<std::string> wptr;
+    // Non-owning pointer that will outlive the object
+    oup::observer_ptr<std::string> obs_ptr;
 
     {
         // Unique pointer that owns the object
-        auto ptr = oup::make_observable_unique<std::string>("hello");
+        auto owner_ptr = oup::make_observable_unique<std::string>("hello");
 
-        // Make the weak pointer observe the object
-        wptr = ptr;
+        // Make the observer pointer point to the object
+        obs_ptr = owner_ptr;
 
-        // Weak pointer is valid
-        assert(!wptr.expired());
+        // Observer pointer is valid
+        assert(!obs_ptr.expired());
 
-        // It can be locked to get a (non-owning!) pointer to the object
-        std::string* s = wptr.lock();
-        assert(s != nullptr);
-        std::cout << *s << std::endl;
+        // It can be used like a regular raw pointer
+        assert(obs_ptr != nullptr);
+        std::cout << *obs_ptr << std::endl;
 
         // The unique pointer cannot be copied
-        auto tmp_copied = ptr; // error!
+        auto tmp_copied = owner_ptr; // error!
 
         // ... but it can be moved
-        auto tmp_moved = std::move(ptr); // OK
+        auto tmp_moved = std::move(owner_ptr); // OK
     }
 
     // The unique pointer has gone out of scope, the object is deleted,
-    // the weak pointer is now null.
-    assert(wptr.expired());
-    assert(wptr.lock() == nullptr);
+    // the observer pointer is now null.
+    assert(obs_ptr.expired());
+    assert(obs_ptr == nullptr);
 
     return 0;
 }
@@ -65,16 +64,12 @@ int main() {
 
 ## Limitations
 
-The follownig limitations are imposed by the current implementation (reusing the parts from `std::shared_ptr` and `std::weak_ptr`), or features that were not implemented simply because of lack of motivation. A higher quality implementation of this API could get rid of most (if not all) of them.
+The follownig limitations are features that were not implemented simply because of lack of motivation.
 
  - `observable_unique_ptr` does not support pointers to arrays, but `std::unique_ptr` and `std::shared_ptr` both do.
  - `observable_unique_ptr` does not support custom allocators, but `std::shared_ptr` does.
- - `observable_unique_ptr` does not have a `release()` function to let go of the ownership, which `std::unique_ptr` has.
- - `observable_unique_ptr` allows moving from other `observable_unique_ptr` only if the deleter type is exactly the same, while `std::unique_ptr` allows moving from a convertible deleter.
- - Contrary to `std::unique_ptr`, which stores the deleter in-place next to the pointer to the owned object, an `observable_unique_ptr` follows the model from `std::shared_ptr` where the deleter is type-erased and stored on the heap. Therefore, an `observable_unique_ptr` may or may not own a deleter instance; if in doubt, check `has_deleter()` before calling `get_deleter()`, or use `try_get_deleter()`.
- - A moved-from `observable_unique_ptr` will not own a deleter instance.
 
 
 ## Notes
 
-An alternative implementation of an "observable unique pointer" can be found [here](https://www.codeproject.com/articles/1011134/smart-observers-to-use-with-unique-ptr). It does not compile out of the box with gcc unfortunately, but it does contain more features (like creating an observer pointer from a raw `this`) and a lower-overhead implementation (not based on `std::shared_ptr`/`std::weak_ptr`). Have a look to check if this better suits your needs.
+An alternative implementation of an "observable unique pointer" can be found [here](https://www.codeproject.com/articles/1011134/smart-observers-to-use-with-unique-ptr). It does not compile out of the box with gcc unfortunately, but it does contain more features (like creating an observer pointer from a raw `this`). Have a look to check if this better suits your needs.