Class: JobResult

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

Overview

This class is basically an implementation of a future. It is intended to be used for the result of jobs.

The api for the “provider” of the result consists of #complete! and #fail!. They are to be called with the result or the Exception respectivly.

From the perspective of the “recipient” there are #completed? and #failed?, which indicate that a result is available by returning true (and false if not) and for #failed?, that the job ended with a failure additionally. For the retrival of the result there are two methods. The #result method returns the result if it is already availaible or raises an ThreadError otherwise. The #wait_for_completion method always returns the result, if it's not available, then it blocks if until the completion of the job.

After the result becomes availiable it will be transformed by a function ifr such a function is given in the constructor. If there is no such function an optional block to the #complete! method will transform the result.

Otherwise the results will be unaltered. The unaltered version of the result is always the second return value for all methods that return the result.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(result_transformer = nil) ⇒ JobResult

Returns a new instance of JobResult.


27
28
29
30
31
32
33
# File 'lib/job_result.rb', line 27

def initialize(result_transformer = nil)
  @completed = false
  @failed = false
  @mutex = Mutex.new
  @condition = ConditionVariable.new
  @result_transformer = result_transformer
end

Class Method Details

._load(str) ⇒ Object


113
114
115
# File 'lib/job_result.rb', line 113

def JobResult._load(str)
  JobResult.new.load(*(Marshal.restore str))
end

Instance Method Details

#_dump(depth) ⇒ Object


108
109
110
# File 'lib/job_result.rb', line 108

def _dump(depth)
  Marshal.dump [@completed, @failed, @result, @raw_result]
end

#complete!(result_object) { ... } ⇒ Object

Complete the operation successfully. If no result transformer was given to the constructor transforms the result with the optional block.

Parameters:

  • result_object (Object)

    Object representing the result of the job.

Yields:

  • the result.

Yield Returns:

  • the transformed result.


74
75
76
77
78
79
80
81
82
83
84
85
86
# File 'lib/job_result.rb', line 74

def complete!(result_object)
  @mutex.synchronize {
    @raw_result = result_object
    unless @result_transformer.nil?
      @result = @result_transformer[@raw_result]
    else
      @result = block_given? ? yield : @raw_result
    end
    @completed = true
    @failed = false
    @condition.broadcast
  }
end

#completed?Bool

Returns true if the result is availiable.

Returns:

  • (Bool)

49
50
51
# File 'lib/job_result.rb', line 49

def completed?()
  @completed
end

#fail!(error) ⇒ Object

Complete the operation unsuccessfully.

Parameters:

  • error (Exception)

    Exception representing the reason of the failure.


90
91
92
93
94
95
96
97
98
# File 'lib/job_result.rb', line 90

def fail!(error)
  @mutex.synchronize {
    @raw_result = error
    @result = error
    @completed = true
    @failed = true
    @condition.broadcast
  }
end

#failed?Bool

Returns true if the result is availiable and the operation failed.

Returns:

  • (Bool)

55
56
57
# File 'lib/job_result.rb', line 55

def failed?()
  @completed and @failed
end

#load(completed, failed, result, raw_result) ⇒ Object


101
102
103
104
105
# File 'lib/job_result.rb', line 101

def load(completed, failed, result, raw_result)
  @completed, @failed = completed, failed
  @result, @raw_result = result, raw_result
  self
end

#resultObject

Returns the result if already availiable or raises an ThreadError otherwise.

Returns:

  • (Object)

    the transformed result.

  • (Object)

    the raw result.

Raises:

  • (ThreadError)

    if the result is not yet availiable.


64
65
66
67
# File 'lib/job_result.rb', line 64

def result()
  raise ThreadError, "Not yet completed" if !completed?
  return @result, @raw_result
end

#wait_for_completionObject

Returns the result if already availiable or blocks until the result is made availiable through #complete! or #fail! and then returns it.

Returns:

  • (Object)

    the transformed result.

  • (Object)

    the raw result.


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

def wait_for_completion()
  @mutex.synchronize {
    return @result, @raw_result if completed?
    @condition.wait(@mutex)
  }
  return @result, @raw_result
end