From 511acba4aeb3e35cf025a8a6cde4241b7b5167f3 Mon Sep 17 00:00:00 2001 From: Samuel Williams Date: Sat, 26 Dec 2020 22:09:49 +1300 Subject: Update method name and add documentation. --- doc/fiber.md | 12 +++++++++++- lib/timeout.rb | 7 +++++-- scheduler.c | 13 +++++++------ test/fiber/scheduler.rb | 2 +- test/fiber/test_timeout.rb | 2 +- 5 files changed, 25 insertions(+), 11 deletions(-) diff --git a/doc/fiber.md b/doc/fiber.md index 5abd848677..840bebd188 100644 --- a/doc/fiber.md +++ b/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. diff --git a/lib/timeout.rb b/lib/timeout.rb index 9625db77a8..dc8eb24a10 100644 --- a/lib/timeout.rb +++ b/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 include # Timeout 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 diff --git a/scheduler.c b/scheduler.c index 49fb6e1408..0080d556e6 100644 --- a/scheduler.c +++ b/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 diff --git a/test/fiber/scheduler.rb b/test/fiber/scheduler.rb index 8a8585fcbe..0461cfbe3f 100644 --- a/test/fiber/scheduler.rb +++ b/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 diff --git a/test/fiber/test_timeout.rb b/test/fiber/test_timeout.rb index b974aa0e35..127e4b0084 100644 --- a/test/fiber/test_timeout.rb +++ b/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 -- cgit v1.2.3