Add synchronization primitives

Allows the use of `fine::Mutex` and `fine::RwLock` as drop-in
replacements for `std::mutex` and `std::shared_mutex` respectively.

Additional functionality is provided to enable usage of tooling like
*lock checker* and *lcnt*.

Author: brodeuralexis

README.md

@@ -30,6 +30,8 @@ NIFs in C++.
 
 - Creating all static atoms at load time.
 
+- STL compatible Erlang-backend mutex and rwlock.
+
 ## Motivation
 
 Some projects make extensive use of NIFs, where using the C API results
@@ -500,6 +502,75 @@ std::variant<fine::Ok<int64_t>, fine::Error<std::string>> find_meaning(ErlNifEnv
 Note that if you use a particular union frequently, it may be convenient
 to define a type alias with `using`/`typedef` to keep signatures brief.
 
+## Synchronization
+
+Erlang is a multi-process environment where each process is guaranteed to be
+isolated from other processes.  When dealing with NIFs, the same C++ function
+can be called from multiple Erlang processes simultaneously, leading to race
+conditions. While C++ provides synchronization mechanisms, these are unknown to
+Erlang and cannot take advantage of tools like *lock checker* or *lcnt*.
+
+Fine provides analogues to `std::mutex` and `std::shared_mutex`, respectively
+called `fine::Mutex` and `fine::RwLock`:
+
+```c++
+#include <fine/mutex.hpp>
+#include <fine/rwlock.hpp>
+
+fine::Mutex mutex;
+
+mutex.lock();
+mutex.unlock();
+bool locked = mutex.try_lock();
+
+{
+  auto lock = std::unique_lock(mutex);
+}
+
+fine::RwLock rwlock;
+
+rwlock.lock();
+rwlock.unlock();
+bool locked = rwlock.try_lock();
+
+rwlock.lock_shared();
+rwlock.unlock_shared();
+bool locked = rwlock.try_lock_shared();
+
+{
+  auto lock = std::shared_lock(rwlock);
+}
+
+{
+  auto lock = std::unique_lock(rwlock);
+}
+```
+
+While `fine::Mutex` and `fine::RwLock` can be created using their default
+constructors, users might want to explore their constructors accepting debug
+information:
+```c++
+fine::Mutex mutex("app_name", "type_name");
+fine::Mutex mutex("app_name", "type_name", "instance_name");
+fine::RwLock rwlock("app_name", "type_name");
+fine::RwLock rwlock("app_name", "type_name", "instance_name");
+```
+
+Conventionnally, `"app_name"` is a string representation of the application
+associated with the loaded NIFs, `"type_name"` is the type wrapped by the
+synchronization primitive, and `"instance_name"` identifies and instance of the
+type indivually.  The `"instance_name"` is normally omitted if
+the synchronization primitive is global.
+
+Say we were making a wrapper for *libmy_lib* in a app named *my_lib*, we
+would create a read/write lock for an object of type *my_object* like so:
+```c++
+struct my_object;
+const char* my_object__name(struct my_object*);
+
+fine::RwLock my_object_rwlock("my_lib", "my_object", my_object__name(my_object));
+```
+
 <!-- Docs -->
 
 ## Prior work

include/fine/mutex.hpp

@@ -0,0 +1,103 @@
+#ifndef FINE_MUTEX_HPP
+#define FINE_MUTEX_HPP
+#pragma once
+
+#include <cstddef>
+#include <memory>
+#include <mutex> // IWYU pragma: keep
+#include <optional>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+
+#include <erl_nif.h>
+
+namespace fine {
+// Creates a mutually exclusive lock backed by Erlang.
+//
+// This mutex type implements the Lockable requirement, ensuring it can be used
+// with `std::unique_lock` and family.
+class Mutex final {
+public:
+  // Creates an unnamed Mutex.
+  inline Mutex() noexcept : Mutex(nullptr) {}
+
+  // Creates an unnamed Mutex.
+  inline explicit Mutex(std::nullptr_t) : m_handle(enif_mutex_create(nullptr)) {
+    if (!m_handle) {
+      throw std::runtime_error("failed to create mutex");
+    }
+  }
+
+  // Creates a Mutex from a ErlNifMutex handle.
+  inline explicit Mutex(ErlNifMutex *handle) noexcept : m_handle(handle) {}
+
+  // Creates a Mutex with the given debug information.
+  inline Mutex(std::string_view app, std::string_view type,
+               std::optional<std::string_view> instance = std::nullopt) {
+    std::stringstream stream;
+    stream << app << "." << type;
+
+    if (instance) {
+      stream << "[" << *instance << "]";
+    }
+
+    std::string str = std::move(stream).str();
+
+    // We make use of `const_cast` to create the mutex, but this exceptional
+    // situation is acceptable, as `enif_mutex_create` doesn't modify the name:
+    //   https://github.com/erlang/otp/blob/a87183f1eb847119b6ecc83054bf13c26b8ccfaa/erts/emulator/beam/erl_drv_thread.c#L166-L169
+    auto *handle = enif_mutex_create(const_cast<char *>(str.c_str()));
+    if (handle == nullptr) {
+      throw std::runtime_error("failed to create mutex");
+    }
+    m_handle.reset(handle);
+  }
+
+  // Converts this Mutex to a ErlNifMutex handle.
+  //
+  // Ownership still belongs to this instance.
+  inline operator ErlNifMutex *() const & noexcept { return m_handle.get(); }
+
+  // Releases ownership of the ErlNifMutex handle to the caller.
+  //
+  // This operation is only possible by:
+  // ```
+  // static_cast<ErlNifMutex*>(std::move(mutex))
+  // ```
+  inline explicit operator ErlNifMutex *() && noexcept {
+    return m_handle.release();
+  }
+
+  // Locks the Mutex. The calling thread is blocked until the Mutex has been
+  // locked. A thread that has currently locked the Mutex cannot lock the same
+  // Mutex again.
+  //
+  // This function is thread-safe.
+  inline void lock() noexcept { enif_mutex_lock(m_handle.get()); }
+
+  // Unlocks a Mutex. The Mutex currently must be locked by the calling thread.
+  //
+  // This function is thread-safe.
+  inline void unlock() noexcept { enif_mutex_unlock(m_handle.get()); }
+
+  // Tries to lock a Mutex. A thread that has currently locked the Mutex cannot
+  // try to lock the same Mutex again.
+  //
+  // This function is thread-safe.
+  inline bool try_lock() noexcept {
+    return enif_mutex_trylock(m_handle.get()) == 0;
+  }
+
+private:
+  struct Deleter {
+    inline void operator()(ErlNifMutex *handle) const noexcept {
+      enif_mutex_destroy(handle);
+    }
+  };
+  std::unique_ptr<ErlNifMutex, Deleter> m_handle;
+};
+} // namespace fine
+
+#endif

include/fine/rwlock.hpp

@@ -0,0 +1,124 @@
+#ifndef FINE_RWLOCK_HPP
+#define FINE_RWLOCK_HPP
+
+#include <cstddef>
+#include <memory>
+#include <optional>
+#include <shared_mutex> // IWYU pragma: keep
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+
+#include <erl_nif.h>
+
+namespace fine {
+// Creates a read-write lock backed by Erlang.
+//
+// This lock type implements the Lockable and SharedLockable requirements,
+// ensuring it can be used with `std::unique_lock`, `std::shared_lock`, etc.
+class RwLock final {
+public:
+  // Creates an unnamed RwLock.
+  inline RwLock() noexcept : RwLock(nullptr) {}
+
+  // Creates an unnamed RwLock.
+  inline explicit RwLock(std::nullptr_t)
+      : m_handle(enif_rwlock_create(nullptr)) {
+    if (!m_handle) {
+      throw std::runtime_error("failed to create rwlock");
+    }
+  }
+
+  // Creates a RwLock from a ErlNifRWLock handle.
+  inline explicit RwLock(ErlNifRWLock *handle) noexcept : m_handle(handle) {}
+
+  // Creates a RwLock with the given name.
+  inline RwLock(std::string_view app, std::string_view type,
+                std::optional<std::string_view> instance = std::nullopt) {
+    std::stringstream stream;
+    stream << app << "." << type;
+
+    if (instance) {
+      stream << "[" << *instance << "]";
+    }
+
+    std::string str = std::move(stream).str();
+
+    // We make use of `const_cast` to create the rwlock, but this exceptional
+    // situation is acceptable, as `enif_rwlock_create` doesn't modify the name:
+    //   https://github.com/erlang/otp/blob/a87183f1eb847119b6ecc83054bf13c26b8ccfaa/ert/emulator/beam/erl_drv_thread.c#L337-L340
+    auto *handle = enif_rwlock_create(const_cast<char *>(str.c_str()));
+    if (handle == nullptr) {
+      throw std::runtime_error("failed to create rwlock");
+    }
+    m_handle.reset(handle);
+  }
+
+  // Converts this RwLock to a ErlNifRwLock handle.
+  //
+  // Ownership still belongs to this instance.
+  inline operator ErlNifRWLock *() const & noexcept { return m_handle.get(); }
+
+  // Releases ownership of the ErlNifRWLock handle to the caller.
+  //
+  // This operation is only possible by:
+  // ```
+  // static_cast<ErlNifRWLock*>(std::move(rwlock))
+  // ```
+  inline explicit operator ErlNifRWLock *() && noexcept {
+    return m_handle.release();
+  }
+
+  // Read locks an RwLock. The calling thread is blocked until the RwLock has
+  // been read locked. A thread that currently has read or read/write locked the
+  // RwLock cannot lock the same RwLock again.
+  //
+  // This function is thread-safe.
+  inline void lock_shared() noexcept { enif_rwlock_rlock(m_handle.get()); }
+
+  // Read unlocks an RwLock. The RwLock currently must be read locked by the
+  // calling thread.
+  //
+  // This function is thread-safe.
+  inline void unlock_shared() noexcept { enif_rwlock_runlock(m_handle.get()); }
+
+  // Read/write locks an RwLock. The calling thread is blocked until the RwLock
+  // has been read/write locked. A thread that currently has read or read/write
+  // locked the RwLock cannot lock the same RwLock again.
+  //
+  // This function is thread-safe.
+  inline void lock() noexcept { enif_rwlock_rwlock(m_handle.get()); }
+
+  // Read/write unlocks an RwLock. The RwLock currently must be read/write
+  // locked by the calling thread.
+  //
+  // This function is thread-safe.
+  inline void unlock() noexcept { enif_rwlock_rwunlock(m_handle.get()); }
+
+  // Tries to read lock an RwLock.
+  //
+  // This function is thread-safe.
+  inline bool try_lock_shared() noexcept {
+    return enif_rwlock_tryrlock(m_handle.get()) == 0;
+  }
+
+  // Tries to read/write lock an RwLock. A thread that currently has read or
+  // read/write locked the RwLock cannot try to lock the same RwLock again.
+  //
+  // This function is thread-safe.
+  inline bool try_lock() noexcept {
+    return enif_rwlock_tryrwlock(m_handle.get()) == 0;
+  }
+
+private:
+  struct Deleter {
+    inline void operator()(ErlNifRWLock *handle) const noexcept {
+      enif_rwlock_destroy(handle);
+    }
+  };
+  std::unique_ptr<ErlNifRWLock, Deleter> m_handle;
+};
+} // namespace fine
+
+#endif

test/c_src/finest.cpp

@@ -1,11 +1,14 @@
 #include <cstring>
-#include <erl_nif.h>
 #include <exception>
-#include <fine.hpp>
 #include <optional>
 #include <stdexcept>
 #include <thread>
 
+#include <erl_nif.h>
+#include <fine.hpp>
+#include <fine/mutex.hpp>
+#include <fine/rwlock.hpp>
+
 namespace finest {
 
 namespace atoms {
@@ -234,6 +237,65 @@ int64_t raise_erlang_error(ErlNifEnv *env) {
 }
 FINE_NIF(raise_erlang_error, 0);
 
+std::nullopt_t mutex_unique_lock_test(ErlNifEnv *) {
+  fine::Mutex mutex;
+  mutex.lock();
+
+  std::thread thread([&mutex] { auto lock = std::unique_lock(mutex); });
+
+  mutex.unlock();
+  thread.join();
+
+  return std::nullopt;
+}
+FINE_NIF(mutex_unique_lock_test, 0);
+
+std::nullopt_t mutex_scoped_lock_test(ErlNifEnv *) {
+  fine::Mutex mutex1;
+  fine::Mutex mutex2("finest", "mutex_scoped_lock_test", "mutex2");
+
+  mutex1.lock();
+  mutex2.lock();
+
+  std::thread thread(
+      [&mutex1, &mutex2] { auto lock = std::scoped_lock(mutex1, mutex2); });
+
+  mutex2.unlock();
+  mutex1.unlock();
+  thread.join();
+
+  return std::nullopt;
+}
+FINE_NIF(mutex_scoped_lock_test, 0);
+
+std::nullopt_t rwlock_unique_lock_test(ErlNifEnv *) {
+  fine::RwLock rwlock;
+
+  rwlock.lock_shared();
+
+  std::thread thread([&rwlock] { auto lock = std::unique_lock(rwlock); });
+
+  rwlock.unlock_shared();
+  thread.join();
+
+  return std::nullopt;
+}
+FINE_NIF(rwlock_unique_lock_test, 0);
+
+std::nullopt_t rwlock_shared_lock_test(ErlNifEnv *) {
+  fine::RwLock rwlock("finest", "rwlock_shared_lock_test", "rwlock");
+
+  rwlock.lock();
+
+  std::thread thread([&rwlock] { auto lock = std::shared_lock(rwlock); });
+
+  rwlock.unlock();
+  thread.join();
+
+  return std::nullopt;
+}
+FINE_NIF(rwlock_shared_lock_test, 0);
+
 } // namespace finest
 
 FINE_INIT("Elixir.Finest.NIF");