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.

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:

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

new(origin = Promises.resolvable_event) click to toggle source

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

Calls superclass method
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 52
def initialize(origin = Promises.resolvable_event)
  super()
  @Origin = origin
end
timeout(intended_time) click to toggle source

Create Cancellation which will cancel itself in given time

@!macro promises.param.intended_time @return [Cancellation]

# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 41
def self.timeout(intended_time)
  new Concurrent::Promises.schedule(intended_time)
end

Public Instance Methods

canceled?() click to toggle source

Is the cancellation cancelled? Respective, was the origin of the cancellation resolved. @return [true, false]

# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 75
def canceled?
  @Origin.resolved?
end
check!(error = CancelledOperationError) click to toggle source

Raise error when cancelled @param [#exception] error to be risen @raise the error @return [self]

# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 83
def check!(error = CancelledOperationError)
  raise error if canceled?
  self
end
inspect()
Alias for: to_s
join(*cancellations) click to toggle source

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

# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 93
def join(*cancellations)
  Cancellation.new Promises.any_event(*[@Origin, *cancellations.map(&:origin)])
end
origin() click to toggle source

The event or future which is the origin of the cancellation @return [Promises::Future, Promises::Event]

# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 68
def origin
  @Origin
end
to_ary() click to toggle source

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
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 62
def to_ary
  [self, @Origin]
end
to_s() click to toggle source

Short string representation. @return [String]

Calls superclass method
# File lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb, line 99
def to_s
  format '%s %s>', super[0..-2], canceled? ? 'canceled' : 'pending'
end
Also aliased as: inspect