Mark IO::Buffer as experimental.

Merged: https://github.com/ruby/ruby/pull/4621

common.mk

@@ -6993,6 +6993,7 @@ io.$(OBJEXT): {$(VPATH)}vm_opts.h
 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

doc/fiber.md

@@ -83,6 +83,7 @@ class Scheduler
   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
   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.

include/ruby/io/buffer.h

@@ -16,6 +16,9 @@
 
 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;
 

io_buffer.c

@@ -11,6 +11,7 @@
 
 #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)
 #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;
 

test/fiber/test_scheduler.rb

@@ -55,6 +55,7 @@ class TestFiberScheduler < Test::Unit::TestCase
   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

tool/test/runner.rb

@@ -12,6 +12,8 @@ require "iseq_loader_checker"
 require "gc_checker"
 require_relative "../test-coverage.rb" if ENV.key?('COVERAGE')
 
+Warning[:experimental] = false
+
 case $0
 when __FILE__
   dir = __dir__