Class: Theatre::Invocation

Inherits:
Object show all
Defined in:
lib/theatre/invocation.rb

Overview

An Invocation is an object which Theatre generates and returns from Theatre#trigger.

Defined Under Namespace

Classes: InvalidStateError

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(namespace, callback, payload = :theatre_no_payload) ⇒ Invocation

Create a new Invocation.

Parameters:

  • namespace (String) —

    The “/foo/bar/qaz” path to the namespace to which this Invocation belongs.

  • callback (Proc) —

    The block which should be executed by an Actor scheduler.

  • payload (Object) (defaults to: :theatre_no_payload) —

    The message that will be sent to the callback for processing.

Raises:

  • (ArgumentError) 


23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/theatre/invocation.rb', line 23

def initialize(namespace, callback, payload=:theatre_no_payload)
  raise ArgumentError, "Callback must be a Proc" unless callback.kind_of? Proc
  @payload       = payload
  @unique_id     = new_guid.freeze
  @callback      = callback
  @current_state = :new
  @state_lock    = Mutex.new
  
  # Used just to protect access to the @returned_value instance variable
  @returned_value_lock = Monitor.new
  
  # Used when wait() is called to notify all waiting threads by using a ConditionVariable
  @returned_value_blocker = Monitor::ConditionVariable.new @returned_value_lock
end

Instance Attribute Details

#callback ⇒ Object (readonly)

Returns the value of attribute callback.



12
13
14
 
# File 'lib/theatre/invocation.rb', line 12

def callback
  @callback
end

#error ⇒ Object (readonly)

Returns the value of attribute error.



12
13
14
 
# File 'lib/theatre/invocation.rb', line 12

def error
  @error
end

#finished_time ⇒ Object (readonly)

Returns the value of attribute finished_time.



12
13
14
 
# File 'lib/theatre/invocation.rb', line 12

def finished_time
  @finished_time
end

#namespace ⇒ Object (readonly)

Returns the value of attribute namespace.



12
13
14
 
# File 'lib/theatre/invocation.rb', line 12

def namespace
  @namespace
end

#queued_time ⇒ Object (readonly)

Returns the value of attribute queued_time.



12
13
14
 
# File 'lib/theatre/invocation.rb', line 12

def queued_time
  @queued_time
end

#returned_value ⇒ Object

Returns the value of attribute returned_value.



12
13
14
 
# File 'lib/theatre/invocation.rb', line 12

def returned_value
  @returned_value
end

#started_time ⇒ Object (readonly)

Returns the value of attribute started_time.



12
13
14
 
# File 'lib/theatre/invocation.rb', line 12

def started_time
  @started_time
end

#unique_id ⇒ Object (readonly)

Returns the value of attribute unique_id.



12
13
14
 
# File 'lib/theatre/invocation.rb', line 12

def unique_id
  @unique_id
end

Instance Method Details

#current_state ⇒ Object 



47
48
49
 
# File 'lib/theatre/invocation.rb', line 47

def current_state
  with_state_lock { @current_state }
end

#error? ⇒ Boolean

Returns:

  • (Boolean) 


77
78
79
 
# File 'lib/theatre/invocation.rb', line 77

def error?
  current_state.equal? :error
end

#execution_duration ⇒ Object 



72
73
74
75
 
# File 'lib/theatre/invocation.rb', line 72

def execution_duration
  return nil unless @finished_time
  @finished_time - @started_time
end

#queued ⇒ Object 



38
39
40
41
42
43
44
45
 
# File 'lib/theatre/invocation.rb', line 38

def queued
  with_state_lock do
    raise InvalidStateError unless @current_state == :new
    @current_state = :queued
    @queued_time = Time.now.freeze
  end
  true
end

#start ⇒ Object 



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/theatre/invocation.rb', line 51

def start
  with_state_lock do
    raise InvalidStateError unless @current_state == :queued
    @current_state = :running
  end
  @started_time = Time.now.freeze
  
  begin
    self.returned_value = if @payload.equal? :theatre_no_payload
      @callback.call
    else
      @callback.call @payload
    end
    with_state_lock { @current_state = :success }
  rescue => @error
    with_state_lock { @current_state = :error }
  ensure
    @finished_time = Time.now.freeze
  end
end

#success? ⇒ Boolean

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/theatre/invocation.rb', line 81

def success?
  current_state.equal? :success
end

#wait ⇒ Object

When this Invocation has been queued, started, and entered either the :success or :error state, this method will finally return. Until then, it blocks the Thread.

Returns:

  • (Object) —

    The result of invoking this Invocation’s callback



91
92
93
94
95
96
 
# File 'lib/theatre/invocation.rb', line 91

def wait
  with_returned_value_lock { return @returned_value if defined? @returned_value }
  @returned_value_blocker.wait
  # Return the returned_value
  with_returned_value_lock { @returned_value }
end