Class: Concurrent::Cancellation

Inherits:
Synchronization::Object
  • Object
show all
Defined in:
lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb

Overview

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:

  • 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>

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(origin = Promises.resolvable_event) ⇒ Cancellation

Creates the cancellation object.

Examples:

cancellation, origin = Concurrent::Cancellation.new

Parameters:

  • origin (Promises::Future, Promises::Event) (defaults to: Promises.resolvable_event) —

    of the cancellation. When it is resolved the cancellation is canceled.

See Also:



54
55
56
57
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb', line 54

def initialize(origin = Promises.resolvable_event)
  super()
  @Origin = origin
end

Class Method Details

.timeout(intended_time) ⇒ Cancellation

Create Cancellation which will cancel itself in given time

Returns:



43
44
45
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb', line 43

def self.timeout(intended_time)
  new Concurrent::Promises.schedule(intended_time)
end

Instance Method Details

#canceled? ⇒ true, false

Is the cancellation cancelled? Respective, was the origin of the cancellation resolved.

Returns:

  • (true, false) 


77
78
79
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb', line 77

def canceled?
  @Origin.resolved?
end

#check!(error = CancelledOperationError) ⇒ self

Raise error when cancelled

Parameters:

  • error (#exception) (defaults to: CancelledOperationError) —

    to be risen

Returns:

  • (self)

Raises:

  • the error



85
86
87
88
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb', line 85

def check!(error = CancelledOperationError)
  raise error if canceled?
  self
end

#join(*cancellations) ⇒ Cancellation

Creates a new Cancellation which is cancelled when first of the supplied cancellations or self is cancelled.

Parameters:

Returns:



95
96
97
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb', line 95

def join(*cancellations)
  Cancellation.new Promises.any_event(*[@Origin, *cancellations.map(&:origin)])
end

#origin ⇒ Promises::Future, Promises::Event

The event or future which is the origin of the cancellation

Returns:



70
71
72
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb', line 70

def origin
  @Origin
end

#to_ary ⇒ Array(Cancellation, Promises::Future), Array(Cancellation, Promises::Event)

Allow to multi-assign the Cancellation object

Examples:

cancellation         = Concurrent::Cancellation.new
cancellation, origin = Concurrent::Cancellation.new

Returns:



64
65
66
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb', line 64

def to_ary
  [self, @Origin]
end

#to_s ⇒ String Also known as: inspect

Short string representation.

Returns:

  • (String) 


101
102
103
 
# File 'lib/concurrent-ruby-edge/concurrent/edge/cancellation.rb', line 101

def to_s
  format '%s %s>', super[0..-2], canceled? ? 'canceled' : 'pending'
end