rcx 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59b6c06f1c9ff032b2b70878a6368e4d83e4a8370a19fb2d51b5420831a0211e
-  data.tar.gz: 78d982e5b911b4bb891681bc06ff9da85fb57809076f8f508933269dc9d9a6e0
+  metadata.gz: 291d8e72a9ddea530ab4aa2d585c5d97406603a97d5b72a75caeb2cb79eea8aa
+  data.tar.gz: 570ed623fd7e76df3df6808559d1195476690b2983889e5fc76945e61a1936a8
 SHA512:
-  metadata.gz: 59354a09ceac21baa60fc1ef1f645d56645b61ccc707eb88f2c533c14d1c7b64f4c57223faebf02bea62c1f351aba4f00819eb9f2d20011cf645c2dc8807a210
-  data.tar.gz: ed6563dd44037828a5f620b27a54f2d3714e7e5cdcfe902f913da8a18c4ecb2bbf5ed32bd34c574feb818b7ecc2a80c11526fb5dde21fb4f8217a6089c6b850f
+  metadata.gz: b33290743f173becad0b8736cc6c50c34d5cd3057aedd07dca97500021f64dd7e900b00fc34f35bd9291b46aad91761d4a212b51b339931391040cd6f9461430
+  data.tar.gz: 2322cb7a7e48eb414cce22352b36f9bd8d21ee481bb742f4f3b60ac7a75715277ddc6c39daa43a4e59e2e6354d304935f4995607175c257e6abbda44930024c4

data/CHANGELOG.md

@@ -1,4 +1,8 @@
 ## UNRELEASED
 
+## v0.2.0 (2025-07-09)
+- Added `rcx::IO`
+- Added `rcx::Exception::new_from_errno`
+
 ## v0.1.0 (2025-02-04)
 - Initial release

data/Rakefile

@@ -37,3 +37,8 @@ end
 task :yarn_install do
   sh 'yarn', 'install'
 end
+
+desc 'Format the source code'
+task :format => FileList['**/*.hpp'] do |t|
+  sh 'clang-format', '-i', *t.prerequisites
+end

data/examples/class.cpp

@@ -5,7 +5,7 @@
 void Init_examples_class() {
   using namespace rcx::arg;
 
-  auto ruby = rcx::Ruby();
+  auto ruby = rcx::Ruby::get();
   auto cls =
       ruby.define_class("Example")
           .define_method(

data/include/rcx/internal/rcx.hpp

@@ -60,6 +60,7 @@ namespace rcx {
 #ifdef RCX_IO_BUFFER
     class IOBuffer;
 #endif
+    class IO;
   }
   using namespace value;
 
@@ -256,6 +257,9 @@ namespace rcx {
       IOBuffer convert(Value value);
     };
 #endif
+    template <> struct FromValue<IO> {
+      IO convert(Value value);
+    };
 
 #define RCX_DECLARE_CLASS_CONV(CLS)                                                                \
   template <> struct FromValue<ClassT<CLS>> {                                                      \
@@ -269,6 +273,7 @@ namespace rcx {
     RCX_DECLARE_CLASS_CONV(String);
     RCX_DECLARE_CLASS_CONV(Array);
     RCX_DECLARE_CLASS_CONV(Exception);
+    RCX_DECLARE_CLASS_CONV(IO);
 #ifdef RCX_IO_BUFFER
     RCX_DECLARE_CLASS_CONV(IOBuffer);
 #endif
@@ -358,8 +363,10 @@ namespace rcx {
     ///
     constexpr inline ArgSplat arg_splat;
     /// Block.
+    ///
     constexpr inline Block block;
     /// Optional block.
+    ///
     constexpr inline BlockOpt block_opt;
   }
 
@@ -577,28 +584,40 @@ namespace rcx {
 
       /// Defines a module under this module.
       ///
+      /// Creates a new module nested under this module. The module will be accessible
+      /// as a constant within this module's namespace.
+      ///
       /// @warning Modules defined this way will be never garbage-collected.
       ///
-      /// @param name Name of the module.
+      /// @param name Name of the module to define.
       /// @return The newly defined module.
       Module define_module(concepts::Identifier auto &&name) const;
 
-      /// Defines a class under this module.
+      /// Defines a class under this module with a specified superclass.
+      ///
+      /// Creates a new class nested under this module with the given superclass.
+      /// The class will be accessible as a constant within this module's namespace.
       ///
       /// @warning Classes defined this way will be never garbage-collected.
       ///
-      /// @param name Name of the class.
-      /// @param superclass The new class will be a subclass of this class.
+      /// @tparam T The C++ type of the class.
+      /// @tparam S The C++ type of the superclass.
+      /// @param name Name of the class to define.
+      /// @param superclass The class that will serve as the superclass.
       /// @return The newly defined class.
       template <typename T = Value, typename S>
       ClassT<T> define_class(concepts::Identifier auto &&name, ClassT<S> superclass) const;
 
-      /// Defines a subclass of Object under this module.
+      /// Defines a class under this module inheriting from Object.
+      ///
+      /// Creates a new class nested under this module, with Object as the superclass.
+      /// The class will be accessible as a constant within this module's namespace.
       ///
       /// @warning Classes defined this way will be never garbage-collected.
       ///
-      /// @param name Name of the class.
-      /// @return The newly created class.
+      /// @tparam T The C++ type of the class.
+      /// @param name Name of the class to define.
+      /// @return The newly defined class.
       template <typename T = Value> ClassT<T> define_class(concepts::Identifier auto &&name) const;
 
       /// Defines an instance method.
@@ -639,7 +658,7 @@ namespace rcx {
 
       /// Creates an anonymous module.
       ///
-      /// @return The newly created module.
+      /// @return The newly created anonymous module.
       static Module new_module();
     };
 
@@ -713,59 +732,142 @@ namespace rcx {
       ClassT<T> define_copy_constructor() const
         requires std::copy_constructible<T>;
 
-      /// Creates a new class.
+      /// Creates an anonymous class inheriting from Object.
+      ///
+      /// Creates a new anonymous class that is not assigned to any constant,
+      /// with Object as the superclass. The class can be used dynamically
+      /// or assigned to constants later.
       ///
-      /// @return The newly created class.
+      /// @return The newly created anonymous class.
       static Class new_class();
 
-      /// Creates a new class with a superclass.
+      /// Creates an anonymous class with a specified superclass.
+      ///
+      /// Creates a new anonymous class that is not assigned to any constant,
+      /// with the given class as the superclass. The class can be used dynamically
+      /// or assigned to constants later.
       ///
-      /// @param superclass The new class will be a subclass of this class.
-      /// @return The newly created class.
+      /// @tparam S The C++ type of the superclass.
+      /// @param superclass The class that will serve as the superclass.
+      /// @return The newly created anonymous class.
       template <typename S> static ClassT<S> new_class(ClassT<S> superclass);
     };
 
+    /// Represents a Ruby `Symbol`.
+    ///
+    /// A `Symbol` object represents a name inside the Ruby interpreter.
     class Symbol: public ValueT<Symbol, Value> {
     public:
       using ValueT<Symbol, Value>::ValueT;
-      template <size_t N> explicit Symbol(char const (&)[N]) noexcept;
+
+      /// Creates a `Symbol` from a C string literal.
+      ///
+      /// @param s The C string literal.
+      template <size_t N> explicit Symbol(char const (&s)[N]) noexcept;
+
+      /// Creates a `Symbol` from a string view.
+      ///
+      /// @param sv The string view.
       explicit Symbol(std::string_view sv) noexcept;
 
-      /**
-       * Returns Ruby-internal ID.
-       *
-       * The ID returned by this method may be dynamic and subject to garbage collection.
-       * So do not store, whether on stack or in heap.
-       */
+      /// Returns Ruby-internal ID.
+      ///
+      /// @warning The ID returned by this method may be dynamic and subject to garbage collection.
+      /// So do not store, whether on stack or in heap.
+      /// @return The Ruby-internal ID.
       ID as_ID() const noexcept;
     };
 
+    /// Represents a Ruby `String`.
+    ///
     class String: public ValueT<String, Value> {
     public:
       using ValueT<String, Value>::ValueT;
 
+      /// Creates a deduped frozen `String` from a C++ string-like object.
+      ///
+      /// @param s The C++ string-like object.
+      /// @return The created deduped frozen `String`.
       template <concepts::StringLike S> static String intern_from(S &&s);
+
+      /// Creates a deduped frozen `String` from a C string.
+      ///
+      /// @param s The C string.
+      /// @return The created deduped frozen `String`.
       template <concepts::CharLike CharT> static String intern_from(CharT const *RCX_Nonnull s);
+
+      /// Creates a mutable `String` from a C++ string-like object.
+      ///
+      /// @param s The C++ string-like object.
+      /// @return The created mutable `String`.
       template <concepts::StringLike S> static String copy_from(S &&s);
+
+      /// Creates a mutable `String` from a C string.
+      ///
+      /// @param s The C string.
+      /// @return The created mutable `String`.
       template <concepts::CharLike CharT> static String copy_from(CharT const *RCX_Nonnull s);
 
+      /// Returns the length of the string in octets.
+      ///
+      /// @return The length of the string in octets.
       size_t size() const noexcept;
+
+      /// Returns a mutable pointer to the string's content.
+      ///
+      /// @return A mutable pointer to the string's content.
+      /// @throws FrozenError When the string is frozen.
       char *RCX_Nonnull data() const;
+
+      /// Returns a const pointer to the string's content.
+      ///
+      /// @return A const pointer to the string's content.
       char const *RCX_Nonnull cdata() const noexcept;
+
+      /// Returns a string view of the string's content.
+      ///
+      /// @return A string view of the string's content.
       explicit operator std::string_view() const noexcept;
 
+      /// Locks the string to prevent it from being freed or relocated.
+      ///
+      /// @return The locked string.
       String lock() const;
+
+      /// Unlocks the string to allow it to be modified.
+      ///
+      /// @return The unlocked string.
       String unlock() const;
     };
 
+    /// Represents a Ruby `Array`.
+    ///
     class Array: public ValueT<Array, Value> {
     public:
       using ValueT<Array, Value>::ValueT;
 
+      /// Returns the number of elements in the array.
+      ///
+      /// @return The number of elements in the array.
       size_t size() const noexcept;
+
+      /// Returns the element at the given index.
+      ///
+      /// @tparam T The type to convert the element to.
+      /// @param i The index of the element.
+      /// @return The element at the given index.
       template <concepts::ConvertibleFromValue T = Value> decltype(auto) at(size_t i) const;
+
+      /// Returns the element at the given index.
+      ///
+      /// @param i The index of the element.
+      /// @return The element at the given index.
       Value operator[](size_t i) const;
 
+      /// Creates a new `Array` from a contiguous range of values.
+      ///
+      /// @param elements The contiguous range of values.
+      /// @return The new `Array`.
       template <std::ranges::contiguous_range R>
 #ifdef HAVE_STD_IS_LAYOUT_COMPATIBLE
         requires std::is_layout_compatible_v<std::ranges::range_value_t<R>, ValueBase>
@@ -775,38 +877,131 @@ namespace rcx {
 #endif
       static Array new_from(R const &elements);
 
+      /// Creates a new `Array` from an initializer list of values.
+      ///
+      /// @param elements The initializer list of values.
+      /// @return The new `Array`.
       static Array new_from(std::initializer_list<ValueBase> elements);
 
+      /// Creates a new `Array` from a tuple of values.
+      ///
+      /// @param elements The tuple of values.
+      /// @return The new `Array`.
       template <std::derived_from<ValueBase>... T>
       static Array new_from(std::tuple<T...> const &elements);
 
+      /// Creates a new empty `Array`.
+      ///
+      /// @return The new empty `Array`.
       static Array new_array();
+
+      /// Creates a new empty `Array` with the given capacity.
+      ///
+      /// @param capacity The capacity of the new `Array`.
+      /// @return The new empty `Array`.
       static Array new_array(long capacity);
 
+      /// Appends a value to the end of the array.
+      ///
+      /// @param value The value to append.
+      /// @return The array itself.
       template <concepts::ConvertibleIntoValue T = Value> Array push_back(T value) const;
+
+      /// Removes and returns the last element of the array.
+      ///
+      /// @tparam T The type to convert the element to.
+      /// @return The last element of the array.
       template <concepts::ConvertibleFromValue T = Value> T pop_back() const;
+
+      /// Prepends a value to the beginning of the array.
+      ///
+      /// @param value The value to prepend.
+      /// @return The array itself.
       template <concepts::ConvertibleIntoValue T = Value> Array push_front(T value) const;
+
+      /// Removes and returns the first element of the array.
+      ///
+      /// @tparam T The type to convert the element to.
+      /// @return The first element of the array.
       template <concepts::ConvertibleFromValue T = Value> T pop_front() const;
     };
 
+    /// Represents a Ruby `Proc`.
+    ///
     class Proc: public ValueT<Proc, Value> {
     public:
       using ValueT<Proc, Value>::ValueT;
 
+      /// Checks if this `Proc` is a lambda.
+      ///
+      /// @return `true` if this `Proc` is a lambda, `false` otherwise.
       bool is_lambda() const;
+
+      /// Calls this `Proc` with the given arguments.
+      ///
+      /// @param args The arguments to pass to the `Proc`.
+      /// @return The result of calling the `Proc`.
       Value call(Array args) const;
     };
 
+    /// Represents a Ruby exception.
+    ///
+    /// This class provides functionality for creating and formatting exceptions in Ruby.
     class Exception: public ValueT<Exception, Value> {
     public:
       using ValueT<Exception, Value>::ValueT;
 
+      /// Creates a formatted exception of the specified type.
+      ///
+      /// This method creates an exception instance with a formatted message using C++20 std::format
+      /// syntax. The message is created as a frozen string and passed to the exception constructor.
+      ///
+      /// @tparam E The type of exception class (must be derived from Exception).
+      /// @tparam Args The argument types for the format string.
+      /// @param cls The exception class to instantiate.
+      /// @param fmt The format string (follows std::format syntax).
+      /// @param args The arguments to format into the string.
+      /// @return A new exception instance with the formatted message.
       template <std::derived_from<Exception> E, typename... Args>
       static E format(ClassT<E> cls, std::format_string<Args...> fmt, Args &&...args);
+
+      /// Creates a `SystemCallError` from an errno value.
+      ///
+      /// This method creates a SystemCallError exception based on the provided errno value.
+      /// The errno is converted to an appropriate Ruby exception message automatically.
+      ///
+      /// @param message An optional message to be appended to the error message.
+      /// @param err The errno value (defaults to the current errno).
+      /// @return The newly created `SystemCallError`.
+      static Exception new_from_errno(char const *RCX_Nullable message = nullptr, int err = errno);
+    };
+
+    /// Represents a Ruby `IO`.
+    ///
+    class IO: public ValueT<IO, Value> {
+    public:
+      using ValueT<IO, Value>::ValueT;
+
+      /// The file descriptor of the IO object.
+      ///
+      /// @return The file descriptor.
+      /// @throws IOError If file IO object is closed.
+      int descriptor() const;
+
+      /// Checks if the IO object is opened for reading.
+      ///
+      /// @throws IOError If the IO object is not readable.
+      void check_readable() const;
+
+      /// Checks if the IO object is opened for writing.
+      ///
+      /// @throws IOError If the IO object is not writable.
+      void check_writable() const;
     };
 
 #ifdef RCX_IO_BUFFER
     /// Represents an `IO::Buffer` object.
+    ///
     class IOBuffer: public ValueT<IOBuffer, Value> {
     public:
       using ValueT<IOBuffer, Value>::ValueT;
@@ -958,6 +1153,10 @@ namespace rcx {
     ///
     inline value::ClassT<value::Exception> const Exception =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eException);
+    /// `StandardError` class
+    ///
+    inline value::ClassT<value::Exception> const StandardError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eStandardError);
     /// `SystemExit` class
     ///
     inline value::ClassT<value::Exception> const SystemExit =
@@ -970,30 +1169,22 @@ namespace rcx {
     ///
     inline value::ClassT<value::Exception> const SignalException =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eSignal);
-    /// `StandardError` class
-    ///
-    inline value::ClassT<value::Exception> const StandardError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eStandardError);
-    /// `RuntimeError` class
-    ///
-    inline value::ClassT<value::Exception> const RuntimeError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eRuntimeError);
-    /// `FrozenError` class
-    ///
-    inline value::ClassT<value::Exception> const FrozenError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eFrozenError);
-    /// `TypeError` class
-    ///
-    inline value::ClassT<value::Exception> const TypeError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eTypeError);
     /// `ArgumentError` class
     ///
     inline value::ClassT<value::Exception> const ArgumentError =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eArgError);
+    /// `EOFError` class
+    ///
+    inline value::ClassT<value::Exception> const EOFError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eEOFError);
     /// `IndexError` class
     ///
     inline value::ClassT<value::Exception> const IndexError =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eIndexError);
+    /// `StopIteration` class
+    ///
+    inline value::ClassT<value::Exception> const StopIteration =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eStopIteration);
     /// `KeyError` class
     ///
     inline value::ClassT<value::Exception> const KeyError =
@@ -1002,26 +1193,38 @@ namespace rcx {
     ///
     inline value::ClassT<value::Exception> const RangeError =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eRangeError);
-    /// `NameError` class
-    ///
-    inline value::ClassT<value::Exception> const NameError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eNameError);
-    /// `EncodingError` class
+    /// `IOError` class
     ///
-    inline value::ClassT<value::Exception> const EncodingError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eEncodingError);
-    /// `Encoding::CompatibilityError` class
+    inline value::ClassT<value::Exception> const IOError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eIOError);
+    /// `RuntimeError` class
     ///
-    inline value::ClassT<value::Exception> const EncodingCompatibilityError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eEncCompatError);
-    /// `NoMethodError` class
+    inline value::ClassT<value::Exception> const RuntimeError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eRuntimeError);
+    /// `FrozenError` class
     ///
-    inline value::ClassT<value::Exception> const NoMethodError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eNoMethodError);
+    inline value::ClassT<value::Exception> const FrozenError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eFrozenError);
     /// `SecurityError` class
     ///
     inline value::ClassT<value::Exception> const SecurityError =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eSecurityError);
+    /// `SystemCallError` class
+    ///
+    inline value::ClassT<value::Exception> const SystemCallError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eSystemCallError);
+    /// `ThreadError` class
+    ///
+    inline value::ClassT<value::Exception> const ThreadError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eThreadError);
+    /// `TypeError` class
+    ///
+    inline value::ClassT<value::Exception> const TypeError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eTypeError);
+    /// `ZeroDivisionError` class
+    ///
+    inline value::ClassT<value::Exception> const ZeroDivisionError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eZeroDivError);
     /// `NotImplementedError` class
     ///
     inline value::ClassT<value::Exception> const NotImplementedError =
@@ -1030,6 +1233,34 @@ namespace rcx {
     ///
     inline value::ClassT<value::Exception> const NoMemoryError =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eNoMemError);
+    /// `NoMethodError` class
+    ///
+    inline value::ClassT<value::Exception> const NoMethodError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eNoMethodError);
+    /// `FloatDomainError` class
+    ///
+    inline value::ClassT<value::Exception> const FloatDomainError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eFloatDomainError);
+    /// `LocalJumpError` class
+    ///
+    inline value::ClassT<value::Exception> const LocalJumpError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eLocalJumpError);
+    /// `SystemStackError` class
+    ///
+    inline value::ClassT<value::Exception> const SystemStackError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eSysStackError);
+    /// `RegexpError` class
+    ///
+    inline value::ClassT<value::Exception> const RegexpError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eRegexpError);
+    /// `EncodingError` class
+    ///
+    inline value::ClassT<value::Exception> const EncodingError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eEncodingError);
+    /// `Encoding::CompatibilityError` class
+    ///
+    inline value::ClassT<value::Exception> const EncodingCompatibilityError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eEncCompatError);
     /// `NoMatchingPatternError` class
     ///
     inline value::ClassT<value::Exception> const NoMatchingPatternError =
@@ -1042,6 +1273,10 @@ namespace rcx {
     ///
     inline value::ClassT<value::Exception> const ScriptError =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eScriptError);
+    /// `NameError` class
+    ///
+    inline value::ClassT<value::Exception> const NameError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eNameError);
     /// `SyntaxError` class
     ///
     inline value::ClassT<value::Exception> const SyntaxError =
@@ -1050,10 +1285,10 @@ namespace rcx {
     ///
     inline value::ClassT<value::Exception> const LoadError =
         detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eLoadError);
-    /// `SystemCallError` class
+    /// `Math::DomainError` class
     ///
-    inline value::ClassT<value::Exception> const SystemCallError =
-        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eSystemCallError);
+    inline value::ClassT<value::Exception> const MathDomainError =
+        detail::unsafe_coerce<value::ClassT<value::Exception>>(::rb_eMathDomainError);
 
 #ifdef RCX_IO_BUFFER
     /// `IO::Buffer` class
@@ -1224,27 +1459,67 @@ namespace rcx {
   };
   template <std::derived_from<ValueBase> T> Leak(T) -> Leak<T>;
 
+  /// Provides access to Ruby's environment.
+  ///
   class Ruby {
+  private:
+    Ruby() = default;
+
   public:
+    /// Defines a module at the top level.
+    ///
+    /// Creates a new module under Ruby's Object class. The module will be accessible
+    /// as a top-level constant in Ruby code.
+    ///
+    /// @warning Modules defined this way will be never garbage-collected.
+    ///
+    /// @param name Name of the module to define.
+    /// @return The newly defined module.
     Module define_module(concepts::Identifier auto &&name);
 
+    /// Defines a class at the top level with a specified superclass.
+    ///
+    /// Creates a new class under Ruby's Object class with the given superclass.
+    /// The class will be accessible as a top-level constant in Ruby code.
+    ///
+    /// @warning Classes defined this way will be never garbage-collected.
+    ///
+    /// @tparam T The C++ type of the class.
+    /// @tparam S The C++ type of the superclass.
+    /// @param name Name of the class to define.
+    /// @param superclass The class that will serve as the superclass.
+    /// @return The newly defined class.
     template <typename T = Value, typename S>
     ClassT<T> define_class(concepts::Identifier auto &&name, ClassT<S> superclass);
 
+    /// Defines a class at the top level inheriting from Object.
+    ///
+    /// Creates a new class under Ruby's Object class, with Object as the superclass.
+    /// The class will be accessible as a top-level constant in Ruby code.
+    ///
+    /// @warning Classes defined this way will be never garbage-collected.
+    ///
+    /// @tparam T The C++ type of the class.
+    /// @param name Name of the class to define.
+    /// @return The newly defined class.
     template <typename T = Value> ClassT<T> define_class(concepts::Identifier auto &&name);
-  };
 
-  namespace detail {
-    inline Ruby &unsafe_ruby() {
-      static Ruby ruby = {};
-      return ruby;
-    }
-
-    inline Ruby &ruby() {
-      // TODO: check gvl
-      return unsafe_ruby();
-    }
-  }
+    /// Gets the Ruby environment without GVL checking.
+    ///
+    /// @warning This method bypasses GVL checking and should only be used
+    /// when you are certain the GVL is held or when calling from Ruby callbacks.
+    /// @return Reference to the Ruby environment instance.
+    static Ruby &unsafe_get();
+
+    /// Gets the Ruby environment with GVL checking.
+    ///
+    /// This method asserts that the Global VM Lock is held before returning
+    /// the Ruby environment instance. This is the recommended way to access
+    /// the Ruby environment from C++ code.
+    ///
+    /// @return Reference to the Ruby environment instance.
+    static Ruby &get();
+  };
 }
 
 namespace std {

data/include/rcx/internal/rcx_impl.hpp

@@ -13,6 +13,7 @@
 
 #include <ffi.h>
 #include <rcx/internal/rcx.hpp>
+#include <ruby/io.h>
 
 #if HAVE_CXXABI_H
 #include <cxxabi.h>
@@ -119,12 +120,12 @@ namespace rcx {
       template <typename F> static NativeRbFunc *RCX_Nonnull alloc(F &&function) {
         return alloc_callback([function](std::span<Value> args, Value self) -> Value {
           Parser<ArgSpec...> parser{args, self};
-          using Result = decltype(parser.parse(detail::unsafe_ruby(), std::move(function)));
+          using Result = decltype(parser.parse(Ruby::unsafe_get(), std::move(function)));
           if constexpr(std::is_void_v<Result>) {
-            parser.parse(detail::unsafe_ruby(), std::move(function));
+            parser.parse(Ruby::unsafe_get(), std::move(function));
             return {};
           } else {
-            return into_Value<Result>(parser.parse(detail::unsafe_ruby(), function));
+            return into_Value<Result>(parser.parse(Ruby::unsafe_get(), function));
           }
         });
       }
@@ -955,7 +956,7 @@ namespace rcx {
     return std::string_view(from_Value<String>(value));
   }
 
-  /// Proc
+  // Proc
 
   namespace value {
     inline bool Proc::is_lambda() const {
@@ -980,7 +981,7 @@ namespace rcx {
     };
   }
 
-  /// Exception
+  // Exception
 
   namespace value {
     template <std::derived_from<Exception> E, typename... Args>
@@ -988,6 +989,10 @@ namespace rcx {
       auto const msg = std::vformat(fmt.get(), std::make_format_args(args...));
       return cls.new_instance(String::intern_from(msg));
     }
+
+    inline Exception Exception::new_from_errno(char const *RCX_Nullable message, int err) {
+      return detail::unsafe_coerce<Exception>(rb_syserr_new(err, message));
+    }
   }
 
   namespace convert {
@@ -1000,6 +1005,40 @@ namespace rcx {
     }
   }
 
+  // IO
+
+  namespace value {
+    inline int IO::descriptor() const {
+      return detail::protect([this]() noexcept { return rb_io_descriptor(as_VALUE()); });
+    }
+
+    inline void IO::check_readable() const {
+      return detail::protect([this]() noexcept {
+        rb_io_t *pio;
+        RB_IO_POINTER(as_VALUE(), pio);
+        rb_io_check_readable(pio);
+      });
+    }
+
+    inline void IO::check_writable() const {
+      return detail::protect([this]() noexcept {
+        rb_io_t *pio;
+        RB_IO_POINTER(as_VALUE(), pio);
+        rb_io_check_writable(pio);
+      });
+    }
+  }
+
+  namespace convert {
+    inline IO FromValue<IO>::convert(Value value) {
+      if(!value.is_kind_of(builtin::IO)) {
+        throw Exception::format(
+            builtin::TypeError, "Expected an IO but got a {}", value.get_class());
+      }
+      return detail::unsafe_coerce<IO>(value.as_VALUE());
+    }
+  }
+
 #ifdef RCX_IO_BUFFER
   /// IOBuffer
   namespace value {
@@ -1319,6 +1358,18 @@ namespace rcx {
     return define_class<T>(std::forward<decltype(name)>(name), builtin::Object);
   }
 
+  inline Ruby &Ruby::unsafe_get() {
+    static Ruby ruby = {};
+    return ruby;
+  }
+
+  inline Ruby &Ruby::get() {
+#ifdef HAVE_RUBY_THREAD_HAS_GVL_P
+    rcx_assert(::ruby_thread_has_gvl_p() && "GVL must be held when calling Ruby APIs");
+#endif
+    return unsafe_get();
+  }
+
   namespace detail {
     inline std::string demangle_type_info(std::type_info const &ti) {
       if constexpr(have_abi_cxa_demangle) {

data/lib/rcx/mkmf.rb

@@ -52,3 +52,5 @@ if checking_for("nullability extension")  {
   }
   $defs.push("-DHAVE_FEATURE_NULLABILITY=1")
 end
+
+have_func('ruby_thread_has_gvl_p', 'ruby/thread.h')

data/lib/rcx/version.rb

@@ -1,3 +1,3 @@
 module RCX
-  VERSION = -'0.1.0'
+  VERSION = -'0.2.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rcx
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kasumi Hanazuki
 bindir: exe
 cert_chain: []
-date: 2025-02-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shellwords
@@ -68,7 +68,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.0.dev
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Write Ruby extension in modern C++
 test_files: []