Update method name and add documentation.

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

doc/fiber.md

@@ -76,10 +76,20 @@ class Scheduler
 
   # Sleep the current task for the specified duration, or forever if not
   # specified.
-  # @param duration [Numeric] The amount of time to sleep in seconds.
+  # @parameter duration [Numeric] The amount of time to sleep in seconds.
   def kernel_sleep(duration = nil)
   end
 
+  # Execute the given block. If the block execution exceeds the given timeout,
+  # the specified exception `klass` will be raised. Typically, only non-blocking
+  # methods which enter the scheduler will raise such exceptions.
+  # @parameter duration [Integer] The amount of time to wait, after which an exception will be raised.
+  # @parameter klass [Class] The exception class to raise.
+  # @parameter *arguments [Array] The arguments to send to the constructor of the exception.
+  # @yields {...} The user code to execute.
+  def timeout_after(duration, klass, *arguments, &block)
+  end
+
   # Block the calling fiber.
   # @parameter blocker [Object] What we are waiting on, informational only.
   # @parameter timeout [Numeric | Nil] The amount of time to wait for in seconds.

lib/timeout.rb

@@ -73,6 +73,9 @@ module Timeout
   # ensure to prevent the handling of the exception.  For that reason, this
   # method cannot be relied on to enforce timeouts for untrusted blocks.
   #
+  # If a scheduler is defined, it will be used to handle the timeout by invoking
+  # Scheduler#timeout_after.
+  #
   # Note that this is both a method of module Timeout, so you can <tt>include
   # Timeout</tt> into your classes so they have a #timeout method, as well as
   # a module method, so you can call it directly as Timeout.timeout().
@@ -81,8 +84,8 @@ module Timeout
 
     message ||= "execution expired".freeze
 
-    if (scheduler = Fiber.scheduler)&.respond_to?(:timeout_raise)
-      return scheduler.timeout_raise(sec, klass || Error, message, &block)
+    if (scheduler = Fiber.scheduler)&.respond_to?(:timeout_after)
+      return scheduler.timeout_after(sec, klass || Error, message, &block)
     end
 
     from = "from #{caller_locations(1, 1)[0]}" if $DEBUG

scheduler.c

@@ -17,7 +17,7 @@ static ID id_close;
 static ID id_block;
 static ID id_unblock;
 
-static ID id_timeout_raise;
+static ID id_timeout_after;
 static ID id_kernel_sleep;
 static ID id_process_wait;
 
@@ -33,7 +33,7 @@ Init_Fiber_Scheduler(void)
     id_block = rb_intern_const("block");
     id_unblock = rb_intern_const("unblock");
 
-    id_timeout_raise = rb_intern_const("timeout_raise");
+    id_timeout_after = rb_intern_const("timeout_after");
     id_kernel_sleep = rb_intern_const("kernel_sleep");
     id_process_wait = rb_intern_const("process_wait");
 
@@ -110,19 +110,20 @@ rb_fiber_scheduler_make_timeout(struct timeval *timeout)
     return Qnil;
 }
 
-VALUE rb_fiber_scheduler_timeout_raise(VALUE scheduler, VALUE timeout, VALUE exception, VALUE message)
+VALUE
+rb_fiber_scheduler_timeout_after(VALUE scheduler, VALUE timeout, VALUE exception, VALUE message)
 {
     VALUE arguments[] = {
         timeout, exception, message
     };
 
-    return rb_check_funcall(scheduler, id_timeout_raise, 3, arguments);
+    return rb_check_funcall(scheduler, id_timeout_after, 3, arguments);
 }
 
 VALUE
-rb_fiber_scheduler_timeout_raisev(VALUE scheduler, int argc, VALUE * argv)
+rb_fiber_scheduler_timeout_afterv(VALUE scheduler, int argc, VALUE * argv)
 {
-    return rb_check_funcall(scheduler, id_timeout_raise, argc, argv);
+    return rb_check_funcall(scheduler, id_timeout_after, argc, argv);
 }
 
 VALUE

test/fiber/scheduler.rb

@@ -129,7 +129,7 @@ class Scheduler
     Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 
-  def timeout_raise(duration, klass, message, &block)
+  def timeout_after(duration, klass, message, &block)
     fiber = Fiber.current
 
     self.fiber do

test/fiber/test_timeout.rb

@@ -5,7 +5,7 @@ require_relative 'scheduler'
 require 'timeout'
 
 class TestFiberTimeout < Test::Unit::TestCase
-  def test_timeout_raise
+  def test_timeout_after
     error = nil
 
     thread = Thread.new do