Add synchronization primitives (#7)

Co-authored-by: Jonatan Kłosko <[email protected]>

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,62 @@ 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::SharedMutex`. Those are compatible with the
+standard mutex wrappers, such as `std::unique_lock` and `std::shared_lock`.
+For example:
+
+```c++
+#include <fine/sync.hpp>
+
+fine::Mutex mutex;
+
+{
+  auto lock = std::unique_lock(mutex);
+  ...
+}
+
+fine::SharedMutex mutex;
+
+{
+  auto lock = std::shared_lock(mutex);
+  ...
+}
+```
+
+While `fine::Mutex` and `fine::SharedMutex` 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::SharedMutex rwlock("app_name", "type_name");
+fine::SharedMutex 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::SharedMutex my_object_rwlock("my_lib", "my_object", my_object__name(my_object));
+```
+
 <!-- Docs -->
 
 ## Prior work

include/fine/sync.hpp

@@ -0,0 +1,199 @@
+#ifndef FINE_SYNC_HPP
+#define FINE_SYNC_HPP
+#pragma once
+
+#include <cstddef>
+#include <memory>
+#include <mutex> // IWYU pragma: keep
+#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 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.
+  Mutex() : m_handle(enif_mutex_create(nullptr)) {
+    if (!m_handle) {
+      throw std::runtime_error("failed to create mutex");
+    }
+  }
+
+  // Creates a Mutex from a ErlNifMutex handle.
+  explicit Mutex(ErlNifMutex *handle) noexcept : m_handle(handle) {}
+
+  // Creates a Mutex with the given debug information.
+  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.
+  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))
+  // ```
+  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.
+  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.
+  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.
+  bool try_lock() noexcept { return enif_mutex_trylock(m_handle.get()) == 0; }
+
+private:
+  struct Deleter {
+    void operator()(ErlNifMutex *handle) const noexcept {
+      enif_mutex_destroy(handle);
+    }
+  };
+  std::unique_ptr<ErlNifMutex, Deleter> m_handle;
+};
+
+// 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 SharedMutex final {
+public:
+  // Creates an unnamed SharedMutex.
+  SharedMutex() : m_handle(enif_rwlock_create(nullptr)) {
+    if (!m_handle) {
+      throw std::runtime_error("failed to create rwlock");
+    }
+  }
+
+  // Creates a SharedMutex from a ErlNifRWLock handle.
+  explicit SharedMutex(ErlNifRWLock *handle) noexcept : m_handle(handle) {}
+
+  // Creates a SharedMutex with the given name.
+  SharedMutex(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 SharedMutex to a ErlNifSharedMutex handle.
+  //
+  // Ownership still belongs to this instance.
+  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))
+  // ```
+  explicit operator ErlNifRWLock *() && noexcept { return m_handle.release(); }
+
+  // Read locks a SharedMutex. The calling thread is blocked until the
+  // SharedMutex has been read locked. A thread that currently has read or
+  // read/write locked the SharedMutex cannot lock the same SharedMutex again.
+  //
+  // This function is thread-safe.
+  void lock_shared() noexcept { enif_rwlock_rlock(m_handle.get()); }
+
+  // Read unlocks a SharedMutex. The SharedMutex currently must be read locked
+  // by the calling thread.
+  //
+  // This function is thread-safe.
+  void unlock_shared() noexcept { enif_rwlock_runlock(m_handle.get()); }
+
+  // Read/write locks a SharedMutex. The calling thread is blocked until the
+  // SharedMutex has been read/write locked. A thread that currently has read or
+  // read/write locked the SharedMutex cannot lock the same SharedMutex again.
+  //
+  // This function is thread-safe.
+  void lock() noexcept { enif_rwlock_rwlock(m_handle.get()); }
+
+  // Read/write unlocks a SharedMutex. The SharedMutex currently must be
+  // read/write locked by the calling thread.
+  //
+  // This function is thread-safe.
+  void unlock() noexcept { enif_rwlock_rwunlock(m_handle.get()); }
+
+  // Tries to read lock a SharedMutex.
+  //
+  // This function is thread-safe.
+  bool try_lock_shared() noexcept {
+    return enif_rwlock_tryrlock(m_handle.get()) == 0;
+  }
+
+  // Tries to read/write lock a SharedMutex. A thread that currently has read
+  // or read/write locked the SharedMutex cannot try to lock the same
+  // SharedMutex again.
+  //
+  // This function is thread-safe.
+  bool try_lock() noexcept {
+    return enif_rwlock_tryrwlock(m_handle.get()) == 0;
+  }
+
+private:
+  struct Deleter {
+    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,13 @@
 #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/sync.hpp>
+
 namespace finest {
 
 namespace atoms {
@@ -234,6 +236,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 shared_mutex_unique_lock_test(ErlNifEnv *) {
+  fine::SharedMutex mutex;
+
+  mutex.lock_shared();
+
+  std::thread thread([&mutex] { auto lock = std::unique_lock(mutex); });
+
+  mutex.unlock_shared();
+  thread.join();
+
+  return std::nullopt;
+}
+FINE_NIF(shared_mutex_unique_lock_test, 0);
+
+std::nullopt_t shared_mutex_shared_lock_test(ErlNifEnv *) {
+  fine::SharedMutex mutex("finest", "shared_mutex_shared_lock_test", "mutex");
+
+  mutex.lock();
+
+  std::thread thread([&mutex] { auto lock = std::shared_lock(mutex); });
+
+  mutex.unlock();
+  thread.join();
+
+  return std::nullopt;
+}
+FINE_NIF(shared_mutex_shared_lock_test, 0);
+
 } // namespace finest
 
 FINE_INIT("Elixir.Finest.NIF");

test/lib/finest/nif.ex

@@ -50,5 +50,11 @@ defmodule Finest.NIF do
   def raise_elixir_exception(), do: err!()
   def raise_erlang_error(), do: err!()
 
+  def mutex_unique_lock_test(), do: err!()
+  def mutex_scoped_lock_test(), do: err!()
+
+  def shared_mutex_unique_lock_test(), do: err!()
+  def shared_mutex_shared_lock_test(), do: err!()
+
   defp err!(), do: :erlang.nif_error(:not_loaded)
 end

test/test/finest_test.exs

@@ -287,4 +287,24 @@ defmodule FinestTest do
       end
     end
   end
+
+  describe "mutex" do
+    test "unique_lock" do
+      NIF.mutex_unique_lock_test()
+    end
+
+    test "scoped_lock" do
+      NIF.mutex_scoped_lock_test()
+    end
+  end
+
+  describe "shared_mutex" do
+    test "unique_lock" do
+      NIF.shared_mutex_unique_lock_test()
+    end
+
+    test "shared_lock" do
+      NIF.shared_mutex_shared_lock_test()
+    end
+  end
 end