rcx 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a820a4875675677ecd561fdabdd91571147cba6e85942e763156f8456bbfd07d
-  data.tar.gz: 20e63a83133047933f216487125292e919f76bcff9bd4c10ff917ff151651729
+  metadata.gz: 67bf53ccbe670ee75a0faa064fed2c9cedb0f91042c52a61f75d2fa2948f36b7
+  data.tar.gz: cc83c45e03bd7cb72bf8856385c74c061e3995c50f409ff9fbc9beb9a62c12c2
 SHA512:
-  metadata.gz: 828a90a3dc8fc8c79aa13ec72812df58f74e3c7dd4645b7ef25c6e58ac7fd76a831e29e2a6f3a6ef56717ceeb1ee89577eefa6436bc85b1a6343fdeb5d9e348b
-  data.tar.gz: 6dcda5bb8368a7387c92ca9e1a36c5747be753c69a56805100b1017493bbc6c4c3d7bf62f9d382c42f274974ae5f7a50617c5dd54fc5a1b5f411b392857433a7
+  metadata.gz: '08a0a98e5eade9330c4cd599b25264a3ea792ff5fc7067a122176bbf0a95e766cb6b7d0e6bc583e1bdb8535d49f5ac36624453bfa6455b381564b413e73ee5bb'
+  data.tar.gz: 19d7231302d29d691af29fd21696e43ed9f31be3b293f48c87fc7cd6b73e58e23307a558693cdb60da49d7d8a2a6c553c35bdbb6def1e0efd4ccf847cc07e2da

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 ## UNRELEASED
 
+## v0.3.0 (2025-08-22)
+- Added `rcx::gvl::without_gvl`
+
 ## v0.2.1 (2025-07-10)
 
 ## v0.2.0 (2025-07-09)

data/include/rcx/internal/rcx.hpp

@@ -14,11 +14,11 @@
 #include <string>
 #include <string_view>
 #include <type_traits>
-#include <vector>
 
 #include <ruby.h>
 #include <ruby/encoding.h>
 #include <ruby/io/buffer.h>
+#include <ruby/thread.h>
 
 #define rcx_assert(expr) assert((expr))
 #define rcx_delete(reason) delete
@@ -1520,6 +1520,82 @@ namespace rcx {
     /// @return Reference to the Ruby environment instance.
     static Ruby &get();
   };
+
+  /// Global VM Lock (GVL) management.
+  ///
+  namespace gvl {
+    /// Flags for controlling GVL release behavior.
+    ///
+    enum class ReleaseFlags : int {
+      /// Default behavior - allow interrupts and no special handling.
+      None = 0,
+      /// Prevent interrupt checking during execution.
+      /// Use this when interrupts could cause problems with your function's execution.
+      IntrFail = 1,
+      /// The unblock function (if provided) is async-signal-safe.
+      UbfAsyncSafe = 2,
+      /// The function is safe to offload to a background thread or work pool.
+      Offloadable = 4
+    };
+
+    /// Bitwise OR operator for ReleaseFlags.
+    constexpr ReleaseFlags operator|(ReleaseFlags lhs, ReleaseFlags rhs) noexcept {
+      return static_cast<ReleaseFlags>(static_cast<int>(lhs) | static_cast<int>(rhs));
+    }
+
+    /// Bitwise AND operator for ReleaseFlags.
+    constexpr ReleaseFlags operator&(ReleaseFlags lhs, ReleaseFlags rhs) noexcept {
+      return static_cast<ReleaseFlags>(static_cast<int>(lhs) & static_cast<int>(rhs));
+    }
+
+    /// Releases the GVL and executes a function.
+    ///
+    /// This function releases the Global VM Lock (GVL) before executing the
+    /// callback, allowing other Ruby threads to run concurrently.
+    ///
+    /// @warning The callback must not call any Ruby C API functions that may touch Ruby
+    /// objects.
+    ///
+    /// @tparam F The type of the callback function.
+    /// @tparam U The type of the unblock function.
+    /// @param callback The function to execute without the GVL.
+    /// @param ubf An optional unblock function to interrupt the callback
+    ///   execution. This function can be called from another thread.
+    /// @param flags Control flags for the GVL release behavior.
+    /// @return When the callback returns `void`, this function returns `true` if the callback
+    ///   was executed completely, or `false` if it was interrupted by `ubf`.
+    ///   When the callback returns a value, this function returns an `std::optional` containing
+    ///   the result if the callback was executed completely, or `std::nullopt`
+    ///   if it was interrupted.
+    template <std::invocable<> F, std::invocable U>
+    auto without_gvl(F callback, std::optional<U> ubf, ReleaseFlags flags) noexcept(noexcept(
+        callback(), (*ubf)())) -> std::conditional_t<std::is_void_v<std::invoke_result_t<F>>, bool,
+        std::optional<std::invoke_result_t<F>>>;
+
+    /// Releases the GVL and executes a function.
+    ///
+    /// This is an overload of `without_gvl` that does not take an unblock
+    /// function.
+    ///
+    /// @warning The callback must not call any Ruby C API functions that may touch Ruby
+    /// objects.
+    ///
+    /// @tparam F The type of the callback function.
+    /// @param callback The function to execute without the GVL.
+    /// @param flags Control flags for the GVL release behavior.
+    /// @return When the callback returns `void`, this function returns `true` if the callback
+    ///   was executed completely, or `false` if it was interrupted.
+    ///   When the callback returns a value, this function returns an `std::optional` containing
+    ///   the result if the callback was executed completely, or `std::nullopt`
+    ///   if it was interrupted.
+    template <std::invocable<> F>
+    auto without_gvl(F &&callback, ReleaseFlags flags) noexcept(noexcept(callback()))
+        -> std::conditional_t<std::is_void_v<std::invoke_result_t<F>>, bool,
+            std::optional<std::invoke_result_t<F>>>;
+
+    /// Checks for pending interrupts.
+    void check_interrupts();
+  }
 }
 
 namespace std {

data/include/rcx/internal/rcx_impl.hpp

@@ -3,6 +3,7 @@
 
 #include <concepts>
 #include <memory>
+#include <optional>
 #include <ranges>
 #include <stdexcept>
 #include <string_view>
@@ -10,6 +11,7 @@
 #include <type_traits>
 #include <typeinfo>
 #include <utility>
+#include <variant>
 
 #include <ffi.h>
 #include <rcx/internal/rcx.hpp>
@@ -1414,4 +1416,108 @@ namespace rcx {
       }
     }
   }
+
+  namespace gvl {
+    template <std::invocable<> F, std::invocable<> U>
+    auto without_gvl(F callback, std::optional<U> ubf, ReleaseFlags flags) noexcept(noexcept(
+        callback(), (*ubf)())) -> std::conditional_t<std::is_void_v<std::invoke_result_t<F>>, bool,
+        std::optional<std::invoke_result_t<F>>> {
+
+      using ResultType = std::conditional_t<std::is_void_v<std::invoke_result_t<F>>, std::monostate,
+          std::optional<std::invoke_result_t<F>>>;
+
+      struct CallbackData {
+        F callback;
+        [[no_unique_address]] ResultType result;
+        std::exception_ptr exception;
+      };
+
+      struct UbfData {
+        U ubf;
+        std::exception_ptr exception;
+      };
+
+      CallbackData data{std::move(callback), ResultType{}, nullptr};
+      std::optional<UbfData> ubf_data;
+      if(ubf) {
+        ubf_data.emplace(std::move(*ubf), nullptr);
+      }
+
+      auto callback_wrapper = [](void *RCX_Nonnull arg) -> void * {
+        auto &data = *static_cast<CallbackData * RCX_Nonnull>(arg);
+        try {
+          if constexpr(std::is_void_v<std::invoke_result_t<F>>) {
+            data.callback();
+          } else {
+            data.result = data.callback();
+          }
+        } catch(...) {
+          data.exception = std::current_exception();
+        }
+        return reinterpret_cast<void *>(1);  // Non-null to indicate execution
+      };
+
+      using Ubf = void (*RCX_Nullable)(void *RCX_Nonnull);
+      Ubf ubf_wrapper = nullptr;
+      if(ubf_data) {
+        ubf_wrapper = [](void *RCX_Nonnull arg) -> void {
+          auto &data = *static_cast<UbfData * RCX_Nonnull>(arg);
+          try {
+            data.ubf();
+          } catch(...) {
+            data.exception = std::current_exception();
+          }
+        };
+      }
+
+      void *result = rb_nogvl(callback_wrapper, &data, ubf_wrapper,
+          ubf_data ? std::addressof(*ubf_data) : nullptr, static_cast<int>(flags));
+
+      // Check for UBF exceptions first. The callback was cancelled with UBF, which then raised.
+      if(ubf_data && ubf_data->exception) {
+        std::rethrow_exception(ubf_data->exception);
+      }
+
+      // If rb_nogvl returned nullptr, the callback was cancelled.
+      if(result == nullptr) {
+        if constexpr(std::is_void_v<std::invoke_result_t<F>>) {
+          return false;
+        } else {
+          return std::nullopt;
+        }
+      }
+
+      // Re-throw any exception that occurred in the callback.
+      if(data.exception) {
+        std::rethrow_exception(data.exception);
+      }
+
+      // Return the callback result.
+      if constexpr(std::is_void_v<std::invoke_result_t<F>>) {
+        return true;
+      } else {
+        return std::move(data.result);
+      }
+    }
+
+    template <std::invocable<> F, std::invocable<> U>
+    auto without_gvl(F &&callback, U ubf, ReleaseFlags flags) noexcept(noexcept(callback(), ubf()))
+        -> std::conditional_t<std::is_void_v<std::invoke_result_t<F>>, bool,
+            std::optional<std::invoke_result_t<F>>> {
+      return without_gvl(
+          std::forward<F>(callback), std::optional<std::remove_cvref_t<U>>(std::move(ubf)), flags);
+    }
+
+    template <std::invocable<> F>
+    auto without_gvl(F &&callback, ReleaseFlags flags) noexcept(noexcept(callback()))
+        -> std::conditional_t<std::is_void_v<std::invoke_result_t<F>>, bool,
+            std::optional<std::invoke_result_t<F>>> {
+      using DefaultUbf = void (*)();
+      return without_gvl(std::forward<F>(callback), std::optional<DefaultUbf>(std::nullopt), flags);
+    }
+
+    inline void check_interrupts() {
+      detail::protect([]() noexcept { ::rb_thread_check_ints(); });
+    }
+  }
 }

data/lib/rcx/version.rb

@@ -1,3 +1,3 @@
 module RCX
-  VERSION = -'0.2.1'
+  VERSION = -'0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rcx
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kasumi Hanazuki