Class: Elevate::IOCoordinator

Inherits:
Object
  • Object
show all
Defined in:
lib/elevate/io_coordinator.rb

Overview

Implements task cancellation.

Compliant I/O mechanisms (such as HTTP requests) register long-running operations with a well-known instance of this class. When a cancellation request is received from another thread, the long-running operation is cancelled.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ IOCoordinator

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initializes a new IOCoordinator with the default state.



22
23
24
25
26
27
 
# File 'lib/elevate/io_coordinator.rb', line 22

def initialize
  @lock = NSLock.alloc.init
  @blocking_operation = nil
  @cancelled = false
  @exception_class = nil
end

Class Method Details

.for_thread ⇒ IOCoordinator?

Retrieves the current IOCoordinator for this thread.

Returns:

  • (IOCoordinator, nil) —

    IOCoordinator previously installed to this thread



15
16
17
 
# File 'lib/elevate/io_coordinator.rb', line 15

def self.for_thread
  Thread.current[:io_coordinator]
end

Instance Method Details

#cancel(exception_class = CancelledError) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Cancels the I/O operation (if any), raising an exception of type exception_class in the worker thread.

If the thread is not currently blocked, then set a flag requesting cancellation.



37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/elevate/io_coordinator.rb', line 37

def cancel(exception_class = CancelledError)
  blocking_operation = nil

  @lock.lock
  @cancelled = true
  @exception_class = exception_class
  blocking_operation = @blocking_operation
  @lock.unlock

  if blocking_operation
    blocking_operation.cancel
  end
end

#cancelled? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the cancelled flag.

Returns:

  • (Boolean) —

    true if this coordinator has been canceled previously.



57
58
59
60
61
62
63
64
65
 
# File 'lib/elevate/io_coordinator.rb', line 57

def cancelled?
  cancelled = nil

  @lock.lock
  cancelled = @cancelled
  @lock.unlock

  cancelled
end

#install ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Installs this IOCoordinator to a well-known thread-local.



72
73
74
 
# File 'lib/elevate/io_coordinator.rb', line 72

def install
  Thread.current[:io_coordinator] = self
end

#signal_blocked(operation) ⇒ void

This method returns an undefined value.

Marks the specified operation as one that will potentially block the worker thread for a significant amount of time.

Parameters:

  • operation (#cancel) —

    operation responsible for blocking



85
86
87
88
89
90
91
 
# File 'lib/elevate/io_coordinator.rb', line 85

def signal_blocked(operation)
  check_for_cancellation

  @lock.lock
  @blocking_operation = operation
  @lock.unlock
end

#signal_unblocked(operation) ⇒ void

This method returns an undefined value.

Signals that the specified operation has completed, and is no longer responsible for blocking the worker thread.



99
100
101
102
103
104
105
 
# File 'lib/elevate/io_coordinator.rb', line 99

def signal_unblocked(operation)
  @lock.lock
  @blocking_operation = nil
  @lock.unlock

  check_for_cancellation
end

#uninstall ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Removes the thread-local for the calling thread.



112
113
114
 
# File 'lib/elevate/io_coordinator.rb', line 112

def uninstall
  Thread.current[:io_coordinator] = nil
end