class Concurrent::Cancellation
The Cancellation
abstraction provides cooperative cancellation.
The standard methods ‘Thread#raise` of `Thread#kill` available in Ruby are very dangerous (see linked the blog posts bellow). Therefore concurrent-ruby provides an alternative.
-
<jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/>
-
<www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/>
-
<blog.headius.com/2008/02/rubys-threadraise-threadkill-timeoutrb.html>
It provides an object which represents a task which can be executed, the task has to get the reference to the object and periodically cooperatively check that it is not cancelled. Good practices to make tasks cancellable:
-
check cancellation every cycle of a loop which does significant work,
-
do all blocking actions in a loop with a timeout then on timeout check cancellation and if ok block again with the timeout
The idea was inspired by <msdn.microsoft.com/en-us/library/dd537607(v=vs.110).aspx> @!macro warn.edge
{include:file:docs-source/cancellation.out.md}
Public Class Methods
Source
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 54 def initialize(origin = Promises.resolvable_event) super() @Origin = origin end
Creates the cancellation object.
@param [Promises::Future, Promises::Event] origin of the cancellation.
When it is resolved the cancellation is canceled.
@example
cancellation, origin = Concurrent::Cancellation.new
@see to_ary
Source
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 43 def self.timeout(intended_time) new Concurrent::Promises.schedule(intended_time) end
Create Cancellation
which will cancel itself in given time
@!macro promises.param.intended_time @return [Cancellation]
Public Instance Methods
Source
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 77 def canceled? @Origin.resolved? end
Is the cancellation cancelled? Respective, was the origin of the cancellation resolved. @return [true, false]
Source
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 85 def check!(error = CancelledOperationError) raise error if canceled? self end
Raise error when cancelled @param [#exception] error to be risen @raise the error @return [self]
Source
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 95 def join(*cancellations) Cancellation.new Promises.any_event(*[@Origin, *cancellations.map(&:origin)]) end
Creates a new Cancellation
which is cancelled when first of the supplied cancellations or self is cancelled.
@param [Cancellation] cancellations to combine @return [Cancellation] new cancellation
Source
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 70 def origin @Origin end
The event or future which is the origin of the cancellation @return [Promises::Future, Promises::Event]
Source
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 64 def to_ary [self, @Origin] end
Allow to multi-assign the Cancellation
object @return [Array(Cancellation
, Promises::Future
), Array(Cancellation
, Promises::Event)] @example
cancellation = Concurrent::Cancellation.new cancellation, origin = Concurrent::Cancellation.new