[Util] Close #190.

- Implement `unsharable_shared_ptr` as requested in #190.
- Provide factory function `make_unsharable_shared` in the spirit of
  `std::make_shared`.
- Add respective unit test.

Author: ImmanuelHaffner

include/mutable/util/unsharable_shared_ptr.hpp

@@ -0,0 +1,65 @@
+#pragma once
+
+#include <memory>
+#include <mutable/util/exception.hpp>
+#include <mutable/util/macro.hpp>
+
+
+namespace m {
+
+/**
+ * This class extends `std::shared_ptr` to allow for *unsharing* an *exclusively* held object and thereby converting to
+ * a `std::unique_ptr`.
+ *
+ * Beware, that this class relies on accurate
+ * [`use_count()`](https://en.cppreference.com/w/cpp/memory/shared_ptr/use_count).  The `use_count()` is inaccurate if
+ * the shared_ptr is shared across threads.  Therefore, this class must not be used in a shared environment.
+ *
+ * If support for multi-threading is needed, a *wrapper* around `unsharable_shared_ptr` may be used together with a
+ * mutex to guard operations and synchronize on the `use_count()`.
+ */
+template<typename T>
+struct unsharable_shared_ptr : public std::shared_ptr<T>
+{
+    using super = std::shared_ptr<T>;
+
+    private:
+    using deleter_func_type = std::reference_wrapper<void(T*)>;
+    static void default_deleter(T *ptr) { delete ptr; }
+    static void noop_deleter(T*) { }
+
+    public:
+    template<typename Y>
+    explicit unsharable_shared_ptr(Y *ptr) : super(ptr, std::ref(unsharable_shared_ptr::default_deleter)) { }
+
+    unsharable_shared_ptr() : super(nullptr) { }
+    explicit unsharable_shared_ptr(std::nullptr_t) : super(nullptr) { }
+
+    unsharable_shared_ptr(const unsharable_shared_ptr&) = default;
+    unsharable_shared_ptr(unsharable_shared_ptr&&) = default;
+
+    /**
+     * Converts (and thereby moves) the exclusively held object from this `unsharable_shared_ptr` to a
+     * `std::unique_ptr`.
+     *
+     * \return a `std::unique_ptr` owning the referenced object
+     * \throw `std::logic_error` if this `unsharable_shared_ptr` does not hold the referenced object *exclusively*
+     */
+    std::unique_ptr<T> exclusive_shared_to_unique() {
+        if (super::use_count() == 0) return nullptr;  // nothing to unshare
+        if (super::use_count() > 1) throw m::invalid_state{"not exclusive"};
+        *std::get_deleter<deleter_func_type>(*static_cast<super*>(this)) = std::ref(unsharable_shared_ptr::noop_deleter);
+        std::unique_ptr<T> uptr{super::get()};
+        super::reset();  // this will *not* delete the referenced object
+        M_insist(super::get() == nullptr);
+        return uptr;
+    }
+};
+
+template<typename T, typename... Args>
+unsharable_shared_ptr<T> make_unsharable_shared(Args&&... args)
+{
+    return unsharable_shared_ptr<T>{new T(std::forward<Args>(args)...)};
+}
+
+}

unittest/CMakeLists.txt

@@ -20,6 +20,7 @@ set(
     util/PositionTest.cpp
     util/SpnTest.cpp
     util/TimerTest.cpp
+    util/unsharable_shared_ptr_test.cpp
 
     # util/container
     util/container/RefCountingHashMapTest.cpp

unittest/util/unsharable_shared_ptr_test.cpp

@@ -0,0 +1,70 @@
+#include "catch2/catch.hpp"
+
+#include <mutable/util/unsharable_shared_ptr.hpp>
+#include <string>
+
+
+using namespace m;
+
+
+TEST_CASE("unsharable_shared_ptr", "[core][util]")
+{
+    unsharable_shared_ptr<int> sp1(new int(42));
+    CHECK(sp1.use_count() == 1);
+
+    {
+        auto sp2 = sp1;  // copy shared ptr
+        CHECK(sp1.use_count() == 2);
+        CHECK(sp2.use_count() == 2);
+
+        CHECK_THROWS_AS(sp1.exclusive_shared_to_unique(), m::invalid_state);
+        CHECK(*sp1 == 42);
+        CHECK(*sp2 == 42);
+        // sp2 goes out of scope
+    }
+
+    CHECK(sp1.use_count() == 1);
+    auto uptr = sp1.exclusive_shared_to_unique();
+    CHECK(*uptr == 42);
+    CHECK(sp1.use_count() == 0);
+    CHECK(sp1.get() == nullptr);
+
+    unsharable_shared_ptr<int> Null(nullptr);
+    CHECK(Null.use_count() == 0);
+    auto null_uptr = Null.exclusive_shared_to_unique();
+    CHECK(null_uptr.get() == nullptr);
+}
+
+TEST_CASE("make_unsharable_shared", "[core][util]")
+{
+    SECTION("int")
+    {
+        auto sp1 = make_unsharable_shared<int>(42);
+        CHECK(sp1.use_count() == 1);
+        CHECK(*sp1 == 42);
+
+        auto uptr = sp1.exclusive_shared_to_unique();
+        CHECK(*uptr == 42);
+        CHECK(sp1.use_count() == 0);
+        CHECK(sp1.get() == nullptr);
+    }
+
+    SECTION("POD")
+    {
+        using namespace std::string_literals;
+        struct POD { int i; float f; const char *str; };
+
+        auto sp1 = make_unsharable_shared<POD>(42, 3.14f, "Hello, World!");
+        CHECK(sp1.use_count() == 1);
+        CHECK(sp1->i == 42);
+        CHECK(sp1->f == 3.14f);
+        CHECK(sp1->str == "Hello, World!"s);
+
+        auto uptr = sp1.exclusive_shared_to_unique();
+        CHECK(uptr->i == 42);
+        CHECK(uptr->f == 3.14f);
+        CHECK(uptr->str == "Hello, World!"s);
+        CHECK(sp1.use_count() == 0);
+        CHECK(sp1.get() == nullptr);
+    }
+}