https://git.ruby-lang.org/ruby.git/commit/?id=81d0ce7e97

From 81d0ce7e97af74a2086e143f9e349ee519bd1c4d Mon Sep 17 00:00:00 2001
From: Samuel Williams <samuel.williams@o...>
Date: Wed, 10 Nov 2021 15:42:57 +1300
Subject: Mark IO::Buffer as experimental.

---
 common.mk                    |  1 +
 doc/fiber.md                 |  2 ++
 include/ruby/io/buffer.h     |  3 +++
 io_buffer.c                  | 18 ++++++++++++++++++
 test/fiber/test_scheduler.rb |  1 +
 tool/test/runner.rb          |  2 ++
 6 files changed, 27 insertions(+)

diff --git a/common.mk b/common.mk
index 97a9c34b81b..8a916315ff7 100644
--- a/common.mk
+++ b/common.mk
@@ -6993,6 +6993,7 @@ io.$(OBJEXT): {$(VPATH)}vm_opts.h https://github.com/ruby/ruby/blob/trunk/common.mk#L6993
 io_buffer.$(OBJEXT): $(hdrdir)/ruby/ruby.h
 io_buffer.$(OBJEXT): $(top_srcdir)/internal/bits.h
 io_buffer.$(OBJEXT): $(top_srcdir)/internal/compilers.h
+io_buffer.$(OBJEXT): $(top_srcdir)/internal/error.h
 io_buffer.$(OBJEXT): $(top_srcdir)/internal/static_assert.h
 io_buffer.$(OBJEXT): $(top_srcdir)/internal/string.h
 io_buffer.$(OBJEXT): {$(VPATH)}assert.h
diff --git a/doc/fiber.md b/doc/fiber.md
index f0785d8ae61..a334faf7396 100644
--- a/doc/fiber.md
+++ b/doc/fiber.md
@@ -83,6 +83,7 @@ class Scheduler https://github.com/ruby/ruby/blob/trunk/doc/fiber.md#L83
   end
 
   # Read from the given io into the specified buffer.
+  # WARNING: Experimental hook! Do not use in production code!
   # @parameter io [IO] The io to read from.
   # @parameter buffer [IO::Buffer] The buffer to read into.
   # @parameter length [Integer] The minimum amount to read.
@@ -90,6 +91,7 @@ class Scheduler https://github.com/ruby/ruby/blob/trunk/doc/fiber.md#L91
   end
 
   # Write from the given buffer into the specified IO.
+  # WARNING: Experimental hook! Do not use in production code!
   # @parameter io [IO] The io to write to.
   # @parameter buffer [IO::Buffer] The buffer to write from.
   # @parameter length [Integer] The minimum amount to write.
diff --git a/include/ruby/io/buffer.h b/include/ruby/io/buffer.h
index 073215186cb..053e7e17f97 100644
--- a/include/ruby/io/buffer.h
+++ b/include/ruby/io/buffer.h
@@ -16,6 +16,9 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/io/buffer.h#L16
 
 RUBY_SYMBOL_EXPORT_BEGIN
 
+// WARNING: This entire interface is experimental and may change in the future!
+#define RB_IO_BUFFER_EXPERIMENTAL 1
+
 RUBY_EXTERN VALUE rb_cIOBuffer;
 RUBY_EXTERN size_t RUBY_IO_BUFFER_PAGE_SIZE;
 
diff --git a/io_buffer.c b/io_buffer.c
index 3455713f8df..521d9d8ea95 100644
--- a/io_buffer.c
+++ b/io_buffer.c
@@ -11,6 +11,7 @@ https://github.com/ruby/ruby/blob/trunk/io_buffer.c#L11
 
 #include "internal/string.h"
 #include "internal/bits.h"
+#include "internal/error.h"
 
 VALUE rb_cIOBuffer;
 size_t RUBY_IO_BUFFER_PAGE_SIZE;
@@ -121,8 +122,25 @@ static inline void io_buffer_unmap(void* base, size_t size) https://github.com/ruby/ruby/blob/trunk/io_buffer.c#L122
 #endif
 }
 
+static void io_buffer_experimental(void)
+{
+    static int warned = 0;
+
+    if (warned) return;
+
+    warned = 1;
+
+    if (rb_warning_category_enabled_p(RB_WARN_CATEGORY_EXPERIMENTAL)) {
+        rb_category_warn(RB_WARN_CATEGORY_EXPERIMENTAL,
+          "IO::Buffer is experimental and both the Ruby and C interface may change in the future!"
+        );
+    }
+}
+
 static void io_buffer_initialize(struct rb_io_buffer *data, void *base, size_t size, enum rb_io_buffer_flags flags, VALUE source)
 {
+    io_buffer_experimental();
+
     data->flags = flags;
     data->size = size;
 
diff --git a/test/fiber/test_scheduler.rb b/test/fiber/test_scheduler.rb
index f0f5b79f36f..1870ab1c33e 100644
--- a/test/fiber/test_scheduler.rb
+++ b/test/fiber/test_scheduler.rb
@@ -55,6 +55,7 @@ class TestFiberScheduler < Test::Unit::TestCase https://github.com/ruby/ruby/blob/trunk/test/fiber/test_scheduler.rb#L55
   def test_close_at_exit
     assert_in_out_err %W[-I#{__dir__} -], <<-RUBY, ['Running Fiber'], [], success: true
     require 'scheduler'
+    Warning[:experimental] = false
 
     scheduler = Scheduler.new
     Fiber.set_scheduler scheduler
diff --git a/tool/test/runner.rb b/tool/test/runner.rb
index c629943090b..8ea51e63aaf 100644
--- a/tool/test/runner.rb
+++ b/tool/test/runner.rb
@@ -12,6 +12,8 @@ require "iseq_loader_checker" https://github.com/ruby/ruby/blob/trunk/tool/test/runner.rb#L12
 require "gc_checker"
 require_relative "../test-coverage.rb" if ENV.key?('COVERAGE')
 
+Warning[:experimental] = false
+
 case $0
 when __FILE__
   dir = __dir__
-- 
cgit v1.2.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/