rcx 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a820a4875675677ecd561fdabdd91571147cba6e85942e763156f8456bbfd07d
-  data.tar.gz: 20e63a83133047933f216487125292e919f76bcff9bd4c10ff917ff151651729
+  metadata.gz: 4074c5868fd711ee67726acd364d4aa243c5aeaf9fad6232756e9c1fde7539e3
+  data.tar.gz: e38a49e450466554a5845189cf2ae51ba31665f18389bf9a8d1a052fe6858353
 SHA512:
-  metadata.gz: 828a90a3dc8fc8c79aa13ec72812df58f74e3c7dd4645b7ef25c6e58ac7fd76a831e29e2a6f3a6ef56717ceeb1ee89577eefa6436bc85b1a6343fdeb5d9e348b
-  data.tar.gz: 6dcda5bb8368a7387c92ca9e1a36c5747be753c69a56805100b1017493bbc6c4c3d7bf62f9d382c42f274974ae5f7a50617c5dd54fc5a1b5f411b392857433a7
+  metadata.gz: cb13a7ca26f4caf50b3ad8038044f6abf7f932e612e1047df7c54bc543af07a4400a5f68fc64f37406eedff1234de7e99a58583a073c0cf4cbae916c0b03cdd8
+  data.tar.gz: 918833acbc1d6d1bc2b5c9678533ccd6a8bbdd8f5a6b2b87e18e0baf12443eb3887cb2b8b7ca5349f897e37eb9d0a2c06381e4501870db5e00c25317cc76a9f0

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## UNRELEASED
 
+## v0.3.1 (2025-09-02)
+- Now `extconf.rb`'s can only `require 'rcx/mkmf/c++20'` to enable RCX.
+
+## v0.3.0 (2025-08-22)
+- Added `rcx::gvl::without_gvl`
+
 ## v0.2.1 (2025-07-10)
 
 ## v0.2.0 (2025-07-09)

data/README.md

@@ -6,9 +6,7 @@ Write Ruby extensions in C++20. Inspired by [rice](https://github.com/ruby-rice/
 ## Creating a new extension
 In your `extconf.rb` file, add the following:
 ```ruby
-require 'mkmf
-$CXXFLAGS += ' -std=c++20' # or newer
-require 'rcx/mkmf'
+require 'rcx/mkmf/c++20'
 
 create_header
 create_makefile('your_ext')

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>
@@ -262,7 +264,7 @@ namespace rcx {
       return arg;
     }
 
-    inline ArgSplat::ResultType ArgSplat::parse(Ruby &, Value self, std::span<Value> &args) {
+    inline ArgSplat::ResultType ArgSplat::parse(Ruby &, Value, std::span<Value> &args) {
       auto result = Array::new_from(args);
       args = {};
       return result;
@@ -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/mkmf/c++20.rb

@@ -0,0 +1,3 @@
+require_relative '../mkmf'
+include RCX::MakeMakefile
+setup_rcx(cxx_standard: 'c++20')

data/lib/rcx/mkmf.rb

@@ -1,56 +1,76 @@
 # SPDX-License-Identifier: BSL-1.0
 # SPDX-FileCopyrightText: Copyright 2024-2025 Kasumi Hanazuki <kasumi@rollingapple.net>
 require 'mkmf'
-include MakeMakefile['C++']
+require_relative '../rcx'
 
-root = File.join(__dir__, '../..')
+module RCX
+  CXX_STANDARD_FLAGS = {
+    'c++20' => %w[--std=c++20 --std=c++2a].freeze,
+    'c++23' => %w[--std=c++23 --std=c++2b].freeze,
+    'c++26' => %w[--std=c++26 --std=c++2c].freeze,
+  }.freeze
 
-$INCFLAGS << " -I#{File.join(root, 'include').shellescape}"
+  root = File.join(__dir__, '../..')
+  INCDIR = File.join(root, 'include').shellescape
+  HEADERS = Dir[File.join(root, 'include/**/*.hpp')]
 
-$rcx_headers = Dir[File.join(root, 'include/**/*.hpp')]
+  module MakeMakefile
+    include ::MakeMakefile['C++']
 
-include (Module.new do
-    def configuration(...)
-      super.tap do |mk|
-        mk << <<MAKEFILE
-rcx_headers = #{$rcx_headers.join(?\s)}
-ruby_headers := $(ruby_headers) $(rcx_headers)
-MAKEFILE
-      end
-    end
-  end)
+    def setup_rcx(cxx_standard: 'c++20')
+      CXX_STANDARD_FLAGS.fetch(cxx_standard).find do |flag|
+        if checking_for("whether #{flag} is accepted as CXXFLAGS") { try_cflags(flag) }
+          $CXXFLAGS << " " << flag
+          true
+        else
+          false
+        end
+      end or raise "C++ compiler does not support #{cxx_standard}"
 
-## libffi
+      $INCFLAGS << " -I#{INCDIR}"
 
-dir_config('libffi').any? || pkg_config('libffi')
-ffi_h = 'ffi.h'
-unless have_func('ffi_prep_cif', ffi_h)
-  raise "libffi was not found"
-end
-unless have_func('ffi_closure_alloc', ffi_h) && have_func('ffi_prep_closure_loc', ffi_h)
-  raise "libffi does not support closures"
-end
+      ## libffi
+      dir_config('libffi').any? || pkg_config('libffi')
+      ffi_h = 'ffi.h'
+      unless have_func('ffi_prep_cif', ffi_h)
+        raise "libffi was not found"
+      end
+      unless have_func('ffi_closure_alloc', ffi_h) && have_func('ffi_prep_closure_loc', ffi_h)
+        raise "libffi does not support closures"
+      end
 
-if have_header('cxxabi.h')
-  have_func('abi::__cxa_demangle', 'cxxabi.h')
-  have_func('abi::__cxa_current_exception_type', 'cxxabi.h')
-end
+      if have_header('cxxabi.h')
+        have_func('abi::__cxa_demangle', 'cxxabi.h')
+        have_func('abi::__cxa_current_exception_type', 'cxxabi.h')
+      end
 
-if checking_for("std::is_layout_compatible<>")  {
-    try_compile(<<'CXX')
+      if checking_for("std::is_layout_compatible<>")  {
+          try_compile(<<'CXX')
 #include <type_traits>
 struct A { int a; };
 struct B { int b; };
 static_assert(std::is_layout_compatible<A, B>::value);
 CXX
-  }
-  $defs.push("-DHAVE_STD_IS_LAYOUT_COMPATIBLE=1")
-end
+        }
+        $defs.push("-DHAVE_STD_IS_LAYOUT_COMPATIBLE=1")
+      end
 
-if checking_for("nullability extension")  {
-    try_compile("void *_Nullable p, *_Nonnull q;")
-  }
-  $defs.push("-DHAVE_FEATURE_NULLABILITY=1")
-end
+      if checking_for("nullability extension")  {
+          try_compile("void *_Nullable p, *_Nonnull q;")
+        }
+        $defs.push("-DHAVE_FEATURE_NULLABILITY=1")
+      end
 
-have_func('ruby_thread_has_gvl_p', 'ruby/thread.h')
+      have_func('ruby_thread_has_gvl_p', 'ruby/thread.h')
+    end
+
+    def configuration(...)
+      super.tap do |mk|
+        mk << <<MAKEFILE
+rcx_headers = #{RCX::HEADERS.join(?\s)}
+ruby_headers := $(ruby_headers) $(rcx_headers)
+MAKEFILE
+      end
+    end
+  end
+end

data/lib/rcx/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rcx
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Kasumi Hanazuki
@@ -44,6 +44,7 @@ files:
 - include/rcx/rcx.hpp
 - lib/rcx.rb
 - lib/rcx/mkmf.rb
+- lib/rcx/mkmf/c++20.rb
 - lib/rcx/version.rb
 - package.json
 - yarn.lock