Implemented WeakRetained, WeakRef

https://github.com/couchbase/fleece/wiki/Weak-References-Proposal

Author: snej

API/fleece/RefCounted.hh

@@ -24,16 +24,23 @@ namespace fleece {
 
     enum Nullability {NonNull, MaybeNull};
 
-    /** Simple thread-safe ref-counting implementation.
+    /** Thread-safe ref-counting implementation.
         `RefCounted` objects should be managed by \ref Retained smart-pointers:
         `Retained<Foo> foo = new Foo(...)` or `auto foo = make_retained<Foo>(...)`.
         \note The ref-count starts at 0, so you must call retain() on an instance, or assign it
         to a Retained, right after constructing it. */
     class RefCounted {
     public:
         RefCounted()                            =default;
-        
-        int refCount() const FLPURE             {return _refCount;}
+
+        /// The number of (strong) references to this object.
+        int refCount() const FLPURE;
+
+        /// Returns the strong and the weak reference count.
+        std::pair<int,int> refCounts() const FLPURE;
+
+        /// The global number of objects with weak references but no strong references.
+        static size_t zombieCount();
 
     protected:
         RefCounted(const RefCounted &)          { } // must not copy the refCount!
@@ -44,28 +51,25 @@ namespace fleece {
 
     private:
         template <typename T, Nullability N> friend class Retained;
+        template <typename T, Nullability N> friend class WeakRetained;
         template <typename T> friend T* FL_NULLABLE retain(T* FL_NULLABLE) noexcept;
         friend void release(const RefCounted* FL_NULLABLE) noexcept;
         friend void assignRef(RefCounted* FL_NULLABLE &dst, RefCounted* FL_NULLABLE src) noexcept;
 
 #if DEBUG
-        void _retain() const noexcept           {_careful_retain();}
-        void _release() const noexcept          {_careful_release();}
+        void _retain() const noexcept;
+        static constexpr uint64_t kInitialRefCount = 0x66666666;
 #else
-        ALWAYS_INLINE void _retain() const noexcept   { ++_refCount; }
-        void _release() const noexcept;
+        ALWAYS_INLINE void _retain() const noexcept   { ++_bothRefCounts; }
+        static constexpr uint64_t kInitialRefCount = 1;
 #endif
+        void _release() const noexcept;
 
-        static constexpr int32_t kCarefulInitialRefCount = -6666666;
-        void _careful_retain() const noexcept;
-        void _careful_release() const noexcept;
+        void _weakRetain() const noexcept;
+        void _weakRelease() const noexcept;
+        bool _weakToStrong() const noexcept;
 
-        mutable std::atomic<int32_t> _refCount
-#if DEBUG
-                                               {kCarefulInitialRefCount};
-#else
-                                               {0};
-#endif
+        mutable std::atomic<uint64_t> _bothRefCounts {kInitialRefCount};
     };
 
     template <class T> concept RefCountedType = std::derived_from<T, RefCounted>;

API/fleece/WeakRef.hh

@@ -0,0 +1,192 @@
+//
+// WeakRef.hh
+//
+// Copyright 2026-Present Couchbase, Inc.
+//
+// Use of this software is governed by the Business Source License included
+// in the file licenses/BSL-Couchbase.txt.  As of the Change Date specified
+// in that file, in accordance with the Business Source License, use of this
+// software will be governed by the Apache License, Version 2.0, included in
+// the file licenses/APL2.txt.
+//
+
+#pragma once
+#include "RefCounted.hh"
+
+namespace fleece {
+
+    /** A smart pointer very much like \ref Retained except that it holds a _weak_ reference.
+     *  The existence of the weak reference does not keep the referred-to object alive on its own;
+     *  once no strong references exist, the object is freed and any weak references cleared.
+     *
+     *  `WeakRetained` is useful for breaking reference cycles that could otherwise cause leaks.
+     *  If one object in the cycle holds a weak reference to the other, the objects will be freed
+     *  properly once there are no external references to them.
+     *
+     *  Because the pointer is cleared when the last strong reference goes away, which could happen
+     *  on another thread, you have to dereference a `WeakRetained` carefully. You cannot get a
+     *  plain pointer, because the object could be freed at any moment. You must use \ref tryGet,
+     *  which returns a strong reference, i.e. a `Retained` object. If the object has already been
+     *  freed, \ref tryGet returns nullptr (wrapped in a `Retained`), so you have to test for that
+     *  before dereferencing it. */
+    template <class T, Nullability N = MaybeNull>
+    class WeakRetained {
+    public:
+        #if __has_feature(nullability)
+        template <typename X, Nullability> struct nullable_if;
+        template <typename X> struct nullable_if<X,MaybeNull>   {using ptr = X* _Nullable;};
+        template <typename X> struct nullable_if<X,NonNull>     {using ptr = X* _Nonnull;};
+        #else
+        template <typename X, Nullability> struct nullable_if {using ptr = X*;};
+        #endif
+
+        using T_ptr = typename nullable_if<T,N>::ptr; // This is `T*` with appropriate nullability
+
+        WeakRetained() noexcept requires (N==MaybeNull)                 :_ref(nullptr) { }
+        WeakRetained(std::nullptr_t) noexcept requires (N==MaybeNull)   :WeakRetained() { } // optimization
+
+        WeakRetained(T* _Nullable t) noexcept                                  :_ref(_weakRetain(t)) { }
+        WeakRetained(T* _Nonnull t) noexcept requires(N==MaybeNull)     :_ref(_weakRetain(t)) { }
+
+        WeakRetained(const WeakRetained &r) noexcept                    :_ref(_weakRetain(r._ref)) { }
+        WeakRetained(WeakRetained &&r) noexcept                         :_ref(std::move(r).detach()) { }
+
+        template <typename U, Nullability UN> requires (std::derived_from<U,T> && N >= UN)
+        WeakRetained(const WeakRetained<U,UN> &r) noexcept              :_ref(_weakRetain(r._ref)) { }
+        template <typename U, Nullability UN> requires (std::derived_from<U,T> && N >= UN)
+        WeakRetained(WeakRetained<U,UN> &&r) noexcept                   :_ref(std::move(r).detach()) { }
+
+        ~WeakRetained() noexcept                                        {if (_ref) _ref->_weakRelease();}
+
+        WeakRetained& operator=(T_ptr t) & noexcept {
+            _weakRetain(t);
+            std::swap(_ref, t);
+            if (t) t->_weakRelease();
+            return *this;
+        }
+
+        WeakRetained& operator=(std::nullptr_t) & noexcept requires(N==MaybeNull) { // optimized assignment
+            auto oldRef = _ref;
+            _ref = nullptr;
+            if (oldRef) oldRef->_weakRelease();
+            return *this;
+        }
+
+        WeakRetained& operator=(const WeakRetained &r) & noexcept       {*this = r._ref; return *this;}
+
+        template <typename U, Nullability UN> requires(std::derived_from<U,T> && N >= UN)
+        WeakRetained& operator=(const WeakRetained<U,UN> &r) & noexcept {*this = r._ref; return *this;}
+
+        WeakRetained& operator= (WeakRetained &&r) & noexcept {
+            std::swap(_ref, r._ref);   // old _ref will be released by r's destructor
+            return *this;
+        }
+
+        template <typename U, Nullability UN> requires(std::derived_from<U,T> && N >= UN)
+        WeakRetained& operator= (WeakRetained<U,UN> &&r) & noexcept {
+            if ((void*)&r != this) {
+                auto oldRef = _ref;
+                _ref = std::move(r).detach();
+                _weakRelease(oldRef);
+            }
+            return *this;
+        }
+
+        /// Returns true if I hold a non-null pointer.
+        /// Does _not_ check if the pointed-to object still exists.
+        /// @warning  Do not use this to preflight \ref asRetained.
+        explicit operator bool () const FLPURE          {return N==NonNull || (_ref != nullptr);}
+
+        /// Converts any WeakRetained to non-nullable form (WeakRef), or throws if its value is nullptr.
+        WeakRetained<T,NonNull> asWeakRef() const & noexcept(!N) {return WeakRetained<T,NonNull>(_ref);}
+        WeakRetained<T,NonNull> asWeakRef() && noexcept(!N) {
+            WeakRetained<T,NonNull> result(_ref, false);
+            _ref = nullptr;
+            return result;
+        }
+
+        /// True if the object no longer exists.
+        bool invalidated() const FLPURE {return !_ref || _ref->refCount() == 0;}
+
+        /// If this holds a non-null pointer, and the object pointed to still exists,
+        /// returns a `Retained` instance holding a new strong reference to it.
+        /// Otherwise returns an empty (nullptr) `Retained`.
+        /// @warning You **must** check the `Retained` for null before dereferencing it!
+        Retained<T> tryGet() const {
+            if (_ref->_weakToStrong())
+                return Retained<T>::adopt(_ref);
+            else
+                return nullptr;
+        }
+
+        /// An alternative to \ref tryGet. If the object pointed to still exists,
+        /// calls the function `fn` with a pointer to it, then returns true.
+        /// Otherwise just returns false.
+        template <std::invocable<T*> FN>
+        [[nodiscard]] bool use(FN&& fn) requires(std::is_void_v<std::invoke_result_t<FN,T*>>) {
+            if (auto ref = tryGet()) {
+                fn(ref.get());
+                return true;
+            } else {
+                return false;
+            }
+        }
+
+        /// An alternative to \ref tryGet. If the object pointed to still exists,
+        /// calls the function `fn` with a pointer to it, returning whatever it returned.
+        /// Otherwise calls `elsefn` with no arguments, returning whatever it returned.
+        template <std::invocable<T*> FN, std::invocable<> ELSEFN>
+        auto use(FN&& fn, ELSEFN&& elsefn) {
+            if (auto ref = tryGet()) {
+                return fn(ref.get());
+            } else {
+                return elsefn();
+            }
+        }
+
+    private:
+        template <class U, Nullability UN> friend class WeakRetained;
+
+        WeakRetained(T_ptr t, bool) noexcept(N==MaybeNull) // private no-retain ctor
+        :_ref(t) {
+            if constexpr (N == NonNull) {
+                if (t == nullptr) [[unlikely]]
+                    _failNullRef();
+            }
+        }
+
+        static T_ptr _weakRetain(T_ptr t) noexcept {
+            if constexpr (N == NonNull) {
+                t->_weakRetain(); // this is faster, and it detects illegal null (by signal)
+            } else {
+                if (t) t->_weakRetain();
+            }
+            return t;
+        }
+
+        static void _weakRelease(T_ptr t) noexcept {
+            if constexpr (N == NonNull) {
+                t->_weakRelease(); // this is faster, and it detects illegal null (by signal)
+            } else {
+                if (t) t->_weakRelease();
+            }
+        }
+
+        // _ref has to be declared nullable, even when N==NonNull, because a move assignment
+        // sets the moved-from _ref to nullptr. The WeakRetained may not used any more in this state,
+        // but it will be destructed, which is why the destructor also checks for nullptr.
+        T* FL_NULLABLE _ref;
+    };
+
+    template <class T> WeakRetained(T* FL_NULLABLE) -> WeakRetained<T>; // deduction guide
+
+    /// WeakRef<T> is an alias for a non-nullable WeakRetained<T>.
+    template <class T> using WeakRef = WeakRetained<T, NonNull>;
+
+    /// NullableWeakRef<T> is an alias for a (default) nullable WeakRetained<T>.
+    template <class T> using NullableWeakRef = WeakRetained<T, MaybeNull>;
+
+    /// WeakRetainedConst is an alias for a WeakRetained that holds a const pointer.
+    template <class T> using WeakRetainedConst = WeakRetained<const T>;
+
+}