Class: ProcessBalancer::Private::Cancellation

Inherits:
Object
  • Object
show all
Defined in:
lib/process_balancer/private/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:



62
63
64
65
 
# File 'lib/process_balancer/private/cancellation.rb', line 62

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:



51
52
53
 
# File 'lib/process_balancer/private/cancellation.rb', line 51

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) 


85
86
87
 
# File 'lib/process_balancer/private/cancellation.rb', line 85

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



93
94
95
96
 
# File 'lib/process_balancer/private/cancellation.rb', line 93

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:



103
104
105
 
# File 'lib/process_balancer/private/cancellation.rb', line 103

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:

  • (Promises::Future, Promises::Event) 


78
79
80
 
# File 'lib/process_balancer/private/cancellation.rb', line 78

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:



72
73
74
 
# File 'lib/process_balancer/private/cancellation.rb', line 72

def to_ary
  [self, @Origin]
end

#to_s ⇒ String Also known as: inspect

Short string representation.

Returns:

  • (String) 


109
110
111
 
# File 'lib/process_balancer/private/cancellation.rb', line 109

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