react-native-nitro-modules 0.21.0 → 0.22.1

package/cpp/registry/HybridObjectRegistry.cpp

@@ -8,6 +8,7 @@
 #include "HybridObjectRegistry.hpp"
 #include "NitroDefines.hpp"
 #include "NitroLogger.hpp"
+#include <numeric>
 
 namespace margelo::nitro {
 
@@ -29,17 +30,25 @@ std::vector<std::string> HybridObjectRegistry::getAllHybridObjectNames() {
   return keys;
 }
 
+std::string HybridObjectRegistry::getAllRegisteredHybridObjectNamesToString() {
+  std::vector<std::string> names = getAllHybridObjectNames();
+  return std::accumulate(std::next(names.begin()), names.end(), names[0], [](std::string a, std::string b) { return a + ", " + b; });
+}
+
 void HybridObjectRegistry::registerHybridObjectConstructor(const std::string& hybridObjectName, HybridObjectConstructorFn&& constructorFn) {
   Logger::log(LogLevel::Info, TAG, "Registering HybridObject \"%s\"...", hybridObjectName.c_str());
   auto& map = HybridObjectRegistry::getRegistry();
 #ifdef NITRO_DEBUG
   if (map.contains(hybridObjectName)) [[unlikely]] {
+    auto allObjectNames = getAllRegisteredHybridObjectNamesToString();
     auto message =
-        "HybridObject \"" + std::string(hybridObjectName) +
+        "HybridObject \"" + hybridObjectName +
         "\" has already been "
         "registered in the Nitro Modules HybridObjectRegistry! Suggestions:\n"
         "- If you just installed another library, maybe both libraries are using the same name?\n"
-        "- If you just registered your own HybridObject, maybe you accidentally called `registerHybridObjectConstructor(...)` twice?";
+        "- If you just registered your own HybridObject, maybe you accidentally called `registerHybridObjectConstructor(...)` twice?\n"
+        "- All registered HybridObjects: [" +
+        allObjectNames + "]";
     throw std::runtime_error(message);
   }
 #endif
@@ -57,16 +66,20 @@ std::shared_ptr<HybridObject> HybridObjectRegistry::createHybridObject(const std
   auto& map = HybridObjectRegistry::getRegistry();
   auto fn = map.find(hybridObjectName);
   if (fn == map.end()) [[unlikely]] {
-    auto message = "Cannot create an instance of HybridObject \"" + std::string(hybridObjectName) +
-                   "\" - It has not yet been registered in the Nitro Modules HybridObjectRegistry! Suggestions:\n"
-                   "- If you use Nitrogen, make sure your `nitro.json` contains `" +
-                   std::string(hybridObjectName) +
-                   "` on this platform.\n"
-                   "- If you use Nitrogen, make sure your library (*Package.java)/app (MainApplication.java) calls "
-                   "`System.loadLibrary(\"$$androidCxxLibName$$\")` somewhere on app-startup.\n"
-                   "- If you use Nitrogen, make sure your cpp-adapter.cpp calls `margelo::nitro::$$cxxNamespace$$::initialize(vm)`.\n"
-                   "- If you use Nitrogen, inspect the generated `$$androidCxxLibName$$OnLoad.cpp` file.\n"
-                   "- If you don't use Nitrogen, make sure you called `HybridObjectRegistry.registerHybridObject(...)`.";
+    auto allObjectNames = getAllRegisteredHybridObjectNamesToString();
+    auto message =
+        "Cannot create an instance of HybridObject \"" + hybridObjectName +
+        "\" - It has not yet been registered in the Nitro Modules HybridObjectRegistry! Suggestions:\n"
+        "- If you use Nitrogen, make sure your `nitro.json` contains `" +
+        hybridObjectName +
+        "` on this platform.\n"
+        "- If you use Nitrogen, make sure your library (*Package.java)/app (MainApplication.java) calls "
+        "`$$androidCxxLibName$$OnLoad.initializeNative()` somewhere on app-startup.\n"
+        "- If you use Nitrogen, make sure your `cpp-adapter.cpp`/`OnLoad.cpp` calls `margelo::nitro::$$cxxNamespace$$::initialize(vm)`.\n"
+        "- If you use Nitrogen, inspect the generated `$$androidCxxLibName$$OnLoad.cpp` file.\n"
+        "- If you don't use Nitrogen, make sure you called `HybridObjectRegistry.registerHybridObject(...)`."
+        "- All registered HybridObjects: [" +
+        allObjectNames + "]";
     throw std::runtime_error(message);
   }
   std::shared_ptr<HybridObject> instance = fn->second();

package/cpp/registry/HybridObjectRegistry.hpp

@@ -44,6 +44,7 @@ public:
 
 private:
   static std::unordered_map<std::string, HybridObjectConstructorFn>& getRegistry();
+  static std::string getAllRegisteredHybridObjectNamesToString();
 
 private:
   static constexpr auto TAG = "HybridObjectRegistry";

package/cpp/utils/AssertPromiseState.hpp

@@ -12,8 +12,8 @@ template <typename TResult>
 class Promise;
 } // namespace margelo::nitro
 
+#include "NitroTypeInfo.hpp"
 #include "Promise.hpp"
-#include "TypeInfo.hpp"
 #include <exception>
 #include <string>
 

package/cpp/utils/BorrowingReference.hpp

@@ -1,117 +1,226 @@
 //
 //  BorrowingReference.hpp
-//  NitroModules
+//  react-native-nitro
 //
-//  Created by Marc Rousavy on 21.06.24.
+//  Created by Marc Rousavy on 23.06.24.
 //
 
 #pragma once
 
+#include "NitroDefines.hpp"
+#include "OwningLock.hpp"
+#include "ReferenceState.hpp"
+#include "WeakReference.hpp"
 #include <atomic>
 #include <cstddef>
 #include <mutex>
 
 namespace margelo::nitro {
 
-// forward-declaration to avoid duplicate symbols
-template <typename T>
-class OwningReference;
-
 /**
- A `BorrowingReference<T>` is a weak reference to a pointer created by `OwningReference<T>`.
- It can be locked to gain a strong `OwningReference<T>` again if it has not been deleted yet.
+ An `BorrowingReference<T>` is a smart-pointer that holds a strong reference to a pointer.
+ You can have multiple `BorrowingReference<T>` instances point to the same pointer, as they internally keep a ref-count.
+ As opposed to a `shared_ptr<T>`, an `BorrowingReference<T>` can also be imperatively manually deleted, even if there
+ are multiple strong references still holding onto the pointer.
+ This is useful in cases where the `BorrowingReference` might keep a reference alive, but an external value holder
+ is actually responsible for truly deleting the underlying value - like a `jsi::Runtime` for a `jsi::Value`.
+
+ An `BorrowingReference<T>` can be weakified, which gives the user a `WeakReference<T>`.
+ A `WeakReference<T>` can be locked to get an `BorrowingReference<T>` again, assuming it has not been deleted yet.
+
+ A `BorrowingReference<T>` can also be locked using `lock()`, which gives the user an `OwningLock<T>`.
+ Only an `OwningLock<T>` guarantees safe access to the underlying value reference, as any external value holders
+ that might try to delete the value will have to wait until the lock is freed again.
  */
 template <typename T>
 class BorrowingReference final {
-private:
-  explicit BorrowingReference(const OwningReference<T>& ref);
-
 public:
-  BorrowingReference() : _value(nullptr), _isDeleted(nullptr), _strongRefCount(nullptr), _weakRefCount(nullptr), _mutex(nullptr) {}
+  BorrowingReference() : _value(nullptr), _state(nullptr) {}
 
-  BorrowingReference(const BorrowingReference& ref)
-      : _value(ref._value), _isDeleted(ref._isDeleted), _strongRefCount(ref._strongRefCount), _weakRefCount(ref._weakRefCount),
-        _mutex(ref._mutex) {
-    // increment ref count after copy
-    (*_weakRefCount)++;
+  explicit BorrowingReference(T* value) : _value(value), _state(new ReferenceState()) {}
+
+  BorrowingReference(const BorrowingReference& ref) : _value(ref._value), _state(ref._state) {
+    if (_state != nullptr) {
+      // increment ref count after copy
+      _state->strongRefCount++;
+    }
   }
 
-  BorrowingReference(BorrowingReference&& ref)
-      : _value(ref._value), _isDeleted(ref._isDeleted), _strongRefCount(ref._strongRefCount), _weakRefCount(ref._weakRefCount),
-        _mutex(ref._mutex) {
+  BorrowingReference(BorrowingReference&& ref) : _value(ref._value), _state(ref._state) {
     ref._value = nullptr;
-    ref._isDeleted = nullptr;
-    ref._strongRefCount = nullptr;
-    ref._weakRefCount = nullptr;
+    ref._state = nullptr;
   }
 
   BorrowingReference& operator=(const BorrowingReference& ref) {
     if (this == &ref)
       return *this;
 
-    if (_weakRefCount != nullptr) {
+    if (_state != nullptr) {
       // destroy previous pointer
-      (*_weakRefCount)--;
-      maybeDestroy();
+      bool shouldDestroy = _state->decrementStrongRefCount();
+      if (shouldDestroy) {
+        forceDestroyValue();
+      }
+      maybeDestroyState();
     }
 
     _value = ref._value;
-    _isDeleted = ref._isDeleted;
-    _strongRefCount = ref._strongRefCount;
-    _weakRefCount = ref._weakRefCount;
-    _mutex = ref._mutex;
-    if (_weakRefCount != nullptr) {
+    _state = ref._state;
+    if (_state != nullptr) {
       // increment new pointer
-      (*_weakRefCount)++;
+      _state->strongRefCount++;
     }
 
     return *this;
   }
 
+private:
+  // WeakReference<T> -> BorrowingReference<T> Lock-constructor
+  BorrowingReference(const WeakReference<T>& ref) : _value(ref._value), _state(ref._state) {
+    _state->strongRefCount++;
+  }
+
+private:
+  // BorrowingReference<C> -> BorrowingReference<T> Cast-constructor
+  template <typename OldT>
+  BorrowingReference(T* value, const BorrowingReference<OldT>& originalRef) : _value(value), _state(originalRef._state) {
+    _state->strongRefCount++;
+  }
+
+  template <typename C>
+  friend class BorrowingReference;
+
+public:
   ~BorrowingReference() {
-    if (_weakRefCount == nullptr) {
+    if (_state == nullptr) {
       // we are just a dangling nullptr.
       return;
     }
 
-    (*_weakRefCount)--;
-    maybeDestroy();
+    // decrement strong ref count on destroy
+    bool shouldDestroy = _state->decrementStrongRefCount();
+    if (shouldDestroy) {
+      forceDestroyValue();
+    }
+    maybeDestroyState();
   }
 
+public:
+  /**
+   Casts this `BorrowingReference<T>` to a `BorrowingReference<C>`.
+   */
+  template <typename C>
+  BorrowingReference<C> as() {
+    return BorrowingReference<C>(static_cast<C*>(_value), *this);
+  }
+
+public:
   /**
-   Try to lock the borrowing reference to an owning reference, or `nullptr` if it has already been deleted.
+   Creates an `OwningLock<T>` for the given `BorrowingReference<T>` to guarantee safe
+   safe access to `BorrowingReference<T>`.
+   Other threads (e.g. the Hermes garbage collector) cannot delete the `BorrowingReference<T>`
+   as long as the `OwningLock<T>` is still alive.
    */
   [[nodiscard]]
-  OwningReference<T> lock() const;
+  OwningLock<T> lock() const {
+    return OwningLock<T>(*this);
+  }
+
+  /**
+   Get whether the `BorrowingReference<T>` is still pointing to a valid value, or not.
+   */
+  inline bool hasValue() const {
+    return _value != nullptr && !_state->isDeleted;
+  }
+
+  /**
+   Get a borrowing (or "weak") reference to this owning reference
+   */
+  [[nodiscard]]
+  WeakReference<T> weak() const {
+    return WeakReference(*this);
+  }
+
+  /**
+   Delete and destroy the value this BorrowingReference is pointing to.
+   This can even be called if there are still multiple strong references to the value.
+
+   This will block as long as one or more `OwningLock<T>`s of this `BorrowingReference<T>` are still alive.
+   */
+  void destroy() {
+    std::unique_lock lock(_state->mutex);
+
+    forceDestroyValue();
+  }
 
 public:
-  friend class OwningReference<T>;
+  explicit inline operator bool() const {
+    return hasValue();
+  }
 
-private:
-  void maybeDestroy() {
-    _mutex->lock();
+  inline T& operator*() const {
+#ifdef NITRO_DEBUG
+    if (!hasValue()) [[unlikely]] {
+      throw std::runtime_error("Tried to dereference (*) nullptr BorrowingReference<T>!");
+    }
+#endif
+    return *_value;
+  }
+
+  inline T* operator->() const {
+#ifdef NITRO_DEBUG
+    if (!hasValue()) [[unlikely]] {
+      throw std::runtime_error("Tried to dereference (->) nullptr BorrowingReference<T>!");
+    }
+#endif
+    return _value;
+  }
+
+  inline bool operator==(T* other) const {
+    return _value == other;
+  }
+
+  inline bool operator!=(T* other) const {
+    return _value != other;
+  }
+
+  inline bool operator==(const BorrowingReference<T>& other) const {
+    return _value == other._value;
+  }
+
+  inline bool operator!=(const BorrowingReference<T>& other) const {
+    return _value != other._value;
+  }
 
-    if (*_strongRefCount == 0 && *_weakRefCount == 0) {
+private:
+  void maybeDestroyState() {
+    if (_state->strongRefCount == 0 && _state->weakRefCount == 0) {
       // free the full memory if there are no more references at all
-      if (!(*_isDeleted)) {
-        delete _value;
-      }
-      delete _isDeleted;
-      delete _strongRefCount;
-      delete _weakRefCount;
-      _mutex->unlock();
+      delete _state;
+      _state = nullptr;
       return;
     }
+  }
 
-    _mutex->unlock();
+  void forceDestroyValue() {
+    if (_state->isDeleted) [[unlikely]] {
+      // it has already been destroyed.
+      return;
+    }
+    delete _value;
+    _value = nullptr;
+    _state->isDeleted = true;
   }
 
+public:
+  friend class WeakReference<T>;
+  friend class OwningLock<T>;
+
 private:
   T* _value;
-  bool* _isDeleted;
-  std::atomic_size_t* _strongRefCount;
-  std::atomic_size_t* _weakRefCount;
-  std::recursive_mutex* _mutex;
+  ReferenceState* _state;
 };
 
 } // namespace margelo::nitro
+
+#include "WeakReference+Owning.hpp"

package/cpp/utils/NitroDefines.hpp

@@ -9,7 +9,7 @@
 #define NitroDefines_h
 
 // Sets the version of the native Nitro core library
-#define NITRO_VERSION "0.21.0"
+#define NITRO_VERSION "0.22.1"
 
 // Sets whether to use debug or optimized production build flags
 #ifdef DEBUG
@@ -31,6 +31,7 @@
 #define _CXX_INTEROP_HAS_ATTRIBUTE(x) 0
 #endif
 
+// Closed/Final Enums
 #if _CXX_INTEROP_HAS_ATTRIBUTE(enum_extensibility)
 // Enum is marked as closed/not extensible
 #define CLOSED_ENUM __attribute__((enum_extensibility(closed)))
@@ -38,6 +39,7 @@
 #define CLOSED_ENUM
 #endif
 
+// Swift Support
 #if __has_include(<swift/bridging>)
 // Swift's bridging header defines those things
 #include <swift/bridging>
@@ -50,4 +52,11 @@
 #define SWIFT_NONCOPYABLE
 #endif
 
+// React Native Support (right now it's only stubbed out)
+#ifndef REACT_NATIVE_VERSION_MINOR
+#define REACT_NATIVE_VERSION_MAJOR 0
+#define REACT_NATIVE_VERSION_MINOR 0
+#define REACT_NATIVE_VERSION_PATCH 0
+#endif
+
 #endif /* NitroDefines_h */

package/cpp/utils/NitroHash.hpp

@@ -9,6 +9,7 @@
 
 #include <cstddef>
 #include <cstdint>
+#include <string>
 
 namespace margelo::nitro {
 
@@ -40,4 +41,20 @@ constexpr uint64_t hashString(const char (&str)[N]) {
   return hashString(str, N - 1); // N includes the null terminator, so subtract 1
 }
 
+/**
+ * Hashes the given `string_view` using the FNV-1a hashing algorithm.
+ * This can be constexpr.
+ */
+constexpr uint64_t hashString(const std::string_view& string) {
+  return hashString(string.data(), string.length());
+}
+
+/**
+ * Hashes the given `string` using the FNV-1a hashing algorithm.
+ * This happens at runtime.
+ */
+inline uint64_t hashString(const std::string& string) {
+  return hashString(string.c_str(), string.length());
+}
+
 } // namespace margelo::nitro

package/cpp/utils/{TypeInfo.hpp → NitroTypeInfo.hpp}

@@ -1,5 +1,5 @@
 //
-//  TypeInfo.hpp
+//  NitroTypeInfo.hpp
 //  Nitro
 //
 //  Created by Marc Rousavy on 17.07.24.

package/cpp/utils/OwningLock.hpp

@@ -9,10 +9,10 @@
 
 namespace margelo::nitro {
 template <typename T>
-class OwningReference;
+class BorrowingReference;
 }
 
-#include "OwningReference.hpp"
+#include "BorrowingReference.hpp"
 #include <cstddef>
 #include <mutex>
 
@@ -20,21 +20,26 @@ namespace margelo::nitro {
 
 /**
  * An `OwningLock<T>` is a RAII instance that locks the given caller thread guaranteed safe access
- * to a `OwningReference<T>`.
- * The `OwningReference<T>` cannot be deleted while an `OwningLock<T>` of it is alive.
+ * to a `BorrowingReference<T>`.
+ * The `BorrowingReference<T>` cannot be deleted while an `OwningLock<T>` of it is alive.
  *
  * This is useful in JSI, because Hermes runs garbage collection on a separate Thread,
- * and the separate Thread can delete an `OwningReference<T>` while it's still in use.
+ * and the separate Thread can delete an `BorrowingReference<T>` while it's still in use.
  * The `OwningLock<T>` prevents exactly this problem by blocking the GC destructor until
  * the `OwningLock<T>` is released.
  *
- * To create an `OwningLock<T>`, simply call `lock()` on an `OwningReference<T>`.
+ * To create an `OwningLock<T>`, simply call `lock()` on an `BorrowingReference<T>`.
  */
 template <typename T>
 class OwningLock final {
+private:
+  explicit OwningLock(const BorrowingReference<T>& reference) : _reference(reference) {
+    _reference._state->mutex.lock();
+  }
+
 public:
   ~OwningLock() {
-    _reference._mutex->unlock();
+    _reference._state->mutex.unlock();
   }
 
   OwningLock() = delete;
@@ -42,15 +47,10 @@ public:
   OwningLock(OwningLock&&) = delete;
 
 private:
-  explicit OwningLock(const OwningReference<T>& reference) : _reference(reference) {
-    _reference._mutex->lock();
-  }
-
-private:
-  OwningReference<T> _reference;
+  BorrowingReference<T> _reference;
 
 private:
-  friend class OwningReference<T>;
+  friend class BorrowingReference<T>;
 };
 
 } // namespace margelo::nitro

package/cpp/utils/ReferenceState.hpp

@@ -0,0 +1,40 @@
+//
+//  ReferenceState.hpp
+//  react-native-nitro
+//
+//  Created by Marc Rousavy on 03.02.24.
+//
+
+#pragma once
+
+#include <atomic>
+#include <mutex>
+
+namespace margelo::nitro {
+
+/**
+ * Holds state for an `BorrowingReference` (or `WeakReference`).
+ *
+ * The state tracks the amount of strong- and weak- references to any kind of value,
+ * including an extra `isDeleted` flag that specifies whether the value has been force-deleted.
+ *
+ * Also, a `mutex` allows for thread-safe access of the `isDeleted` flag.
+ */
+struct ReferenceState {
+  std::atomic_size_t strongRefCount;
+  std::atomic_size_t weakRefCount;
+  bool isDeleted;
+  std::mutex mutex;
+
+  /**
+   * Decrements the strong ref count by one, and returns whether the value should be deleted.
+   */
+  inline bool decrementStrongRefCount() {
+    size_t oldRefCount = strongRefCount.fetch_sub(1);
+    return oldRefCount <= 1;
+  }
+
+  explicit ReferenceState() : strongRefCount(1), weakRefCount(0), isDeleted(false) {}
+};
+
+} // namespace margelo::nitro

package/cpp/utils/WeakReference+Owning.hpp

@@ -0,0 +1,33 @@
+//
+//  WeakReference+Owning.hpp
+//  react-native-nitro
+//
+//  Created by Marc Rousavy on 23.06.24.
+//
+
+#pragma once
+
+#include "BorrowingReference.hpp"
+
+namespace margelo::nitro {
+
+template <typename T>
+WeakReference<T>::WeakReference(const BorrowingReference<T>& ref) {
+  _value = ref._value;
+  _state = ref._state;
+  _state->weakRefCount++;
+}
+
+template <typename T>
+BorrowingReference<T> WeakReference<T>::lock() const {
+  std::unique_lock lock(_state->mutex);
+
+  if (_state->isDeleted) {
+    // return nullptr
+    return BorrowingReference<T>();
+  }
+
+  return BorrowingReference(*this);
+}
+
+} // namespace margelo::nitro

package/cpp/utils/WeakReference.hpp

@@ -0,0 +1,102 @@
+//
+//  WeakReference.hpp
+//  NitroModules
+//
+//  Created by Marc Rousavy on 21.06.24.
+//
+
+#pragma once
+
+#include "ReferenceState.hpp"
+#include <atomic>
+#include <cstddef>
+#include <mutex>
+
+namespace margelo::nitro {
+
+// forward-declaration to avoid duplicate symbols
+template <typename T>
+class BorrowingReference;
+
+/**
+ A `WeakReference<T>` is a weak reference to a pointer created by `BorrowingReference<T>`.
+ It can be locked to gain a strong `BorrowingReference<T>` again if it has not been deleted yet.
+ */
+template <typename T>
+class WeakReference final {
+private:
+  explicit WeakReference(const BorrowingReference<T>& ref);
+
+public:
+  WeakReference() : _value(nullptr), _state(nullptr) {}
+
+  WeakReference(const WeakReference& ref) : _value(ref._value), _state(ref._state) {
+    if (_state != nullptr) {
+      // increment ref count after copy
+      _state->weakRefCount++;
+    }
+  }
+
+  WeakReference(WeakReference&& ref) : _value(ref._value), _state(ref._state) {
+    // Remove state from other WeakReference after moving since it's now stale data
+    ref._value = nullptr;
+    ref._state = nullptr;
+  }
+
+  WeakReference& operator=(const WeakReference& ref) {
+    if (this == &ref)
+      return *this;
+
+    if (_state != nullptr) {
+      // destroy previous pointer
+      _state->weakRefCount--;
+      maybeDestroy();
+    }
+
+    _value = ref._value;
+    _state = ref._state;
+    if (_state != nullptr) {
+      // increment new pointer
+      _state->weakRefCount++;
+    }
+
+    return *this;
+  }
+
+  ~WeakReference() {
+    if (_state == nullptr) {
+      // we are just a dangling nullptr.
+      return;
+    }
+
+    _state->weakRefCount--;
+    maybeDestroy();
+  }
+
+  /**
+   Try to lock the borrowing reference to an owning reference, or `nullptr` if it has already been deleted.
+   */
+  [[nodiscard]]
+  BorrowingReference<T> lock() const;
+
+public:
+  friend class BorrowingReference<T>;
+
+private:
+  void maybeDestroy() {
+    if (_state->strongRefCount == 0 && _state->weakRefCount == 0) {
+      // free the full memory if there are no more references at all
+      if (!_state->isDeleted) [[unlikely]] {
+        throw std::runtime_error("WeakReference<T> encountered a stale _value - BorrowingReference<T> should've already deleted this!");
+      }
+      delete _state;
+      _state = nullptr;
+    }
+  }
+
+private:
+  T* _value;
+  ReferenceState* _state;
+};
+
+} // namespace margelo::nitro