Class: Concurrent::TimerTask

Inherits:
RubyExecutorService
  • Object
show all
Includes:
Concern::Dereferenceable, Concern::Observable
Defined in:
lib/concurrent/timer_task.rb

Overview

A very common concurrency pattern is to run a thread that performs a task at regular intervals. The thread that performs the task sleeps for the given interval then wakes up and performs the task. Lather, rinse, repeat... This pattern causes two problems. First, it is difficult to test the business logic of the task because the task itself is tightly coupled with the concurrency logic. Second, an exception raised while performing the task can cause the entire thread to abend. In a long-running application where the task thread is intended to run for days/weeks/years a crashed task thread can pose a significant problem. TimerTask alleviates both problems.

When a TimerTask is launched it starts a thread for monitoring the execution interval. The TimerTask thread does not perform the task, however. Instead, the TimerTask launches the task on a separate thread. Should the task experience an unrecoverable crash only the task thread will crash. This makes the TimerTask very fault tolerant. Additionally, the TimerTask thread can respond to the success or failure of the task, performing logging or ancillary operations. TimerTask can also be configured with a timeout value allowing it to kill a task that runs too long.

One other advantage of TimerTask is that it forces the business logic to be completely decoupled from the concurrency logic. The business logic can be tested separately then passed to the TimerTask for scheduling and running.

In some cases it may be necessary for a TimerTask to affect its own execution cycle. To facilitate this, a reference to the TimerTask instance is passed as an argument to the provided block every time the task is executed.

The TimerTask class includes the Dereferenceable mixin module so the result of the last execution is always available via the #value method. Dereferencing options can be passed to the TimerTask during construction or at any later time using the #set_deref_options method.

TimerTask supports notification through the Ruby standard library Observable module. On execution the TimerTask will notify the observers with three arguments: time of execution, the result of the block (or nil on failure), and any raised exceptions (or nil on success). If the timeout interval is exceeded the observer will receive a Concurrent::TimeoutError object as the third argument.

Copy Options

Object references in Ruby are mutable. This can lead to serious problems when the Concern::Dereferenceable#value of an object is a mutable reference. Which is always the case unless the value is a Fixnum, Symbol, or similar "primitive" data type. Each instance can be configured with a few options that can help protect the program from potentially dangerous operations. Each of these options can be optionally set when the object instance is created:

  • :dup_on_deref When true the object will call the #dup method on the value object every time the #value method is called (default: false)
  • :freeze_on_deref When true the object will call the #freeze method on the value object every time the #value method is called (default: false)
  • :copy_on_deref When given a Proc object the Proc will be run every time the #value method is called. The Proc will be given the current value as its only argument and the result returned by the block will be the return value of the #value call. When nil this option will be ignored (default: nil)

When multiple deref options are set the order of operations is strictly defined. The order of deref operations is:

  • :copy_on_deref
  • :dup_on_deref
  • :freeze_on_deref

Because of this ordering there is no need to #freeze an object created by a provided :copy_on_deref block. Simply set :freeze_on_deref to true. Setting both :dup_on_deref to true and :freeze_on_deref to true is as close to the behavior of a "pure" functional language (like Erlang, Clojure, or Haskell) as we are likely to get in Ruby.

Examples:

Basic usage

task = Concurrent::TimerTask.new{ puts 'Boom!' }
task.execute

task.execution_interval #=> 60 (default)
task.timeout_interval   #=> 30 (default)

# wait 60 seconds...
#=> 'Boom!'

task.shutdown #=> true

Configuring :execution_interval and :timeout_interval

task = Concurrent::TimerTask.new(execution_interval: 5, timeout_interval: 5) do
       puts 'Boom!'
     end

task.execution_interval #=> 5
task.timeout_interval   #=> 5

Immediate execution with :run_now

task = Concurrent::TimerTask.new(run_now: true){ puts 'Boom!' }
task.execute

#=> 'Boom!'

Last #value and Dereferenceable mixin

task = Concurrent::TimerTask.new(
  dup_on_deref: true,
  execution_interval: 5
){ Time.now }

task.execute
Time.now   #=> 2013-11-07 18:06:50 -0500
sleep(10)
task.value #=> 2013-11-07 18:06:55 -0500

Controlling execution from within the block

timer_task = Concurrent::TimerTask.new(execution_interval: 1) do |task|
  task.execution_interval.times{ print 'Boom! ' }
  print "\n"
  task.execution_interval += 1
  if task.execution_interval > 5
    puts 'Stopping...'
    task.shutdown
  end
end

timer_task.execute # blocking call - this task will stop itself
#=> Boom!
#=> Boom! Boom!
#=> Boom! Boom! Boom!
#=> Boom! Boom! Boom! Boom!
#=> Boom! Boom! Boom! Boom! Boom!
#=> Stopping...

Observation

class TaskObserver
  def update(time, result, ex)
    if result
      print "(#{time}) Execution successfully returned #{result}\n"
    elsif ex.is_a?(Concurrent::TimeoutError)
      print "(#{time}) Execution timed out\n"
    else
      print "(#{time}) Execution failed with error #{ex}\n"
    end
  end
end

task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ 42 }
task.add_observer(TaskObserver.new)
task.execute

#=> (2013-10-13 19:08:58 -0400) Execution successfully returned 42
#=> (2013-10-13 19:08:59 -0400) Execution successfully returned 42
#=> (2013-10-13 19:09:00 -0400) Execution successfully returned 42
task.shutdown

task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ sleep }
task.add_observer(TaskObserver.new)
task.execute

#=> (2013-10-13 19:07:25 -0400) Execution timed out
#=> (2013-10-13 19:07:27 -0400) Execution timed out
#=> (2013-10-13 19:07:29 -0400) Execution timed out
task.shutdown

task = Concurrent::TimerTask.new(execution_interval: 1){ raise StandardError }
task.add_observer(TaskObserver.new)
task.execute

#=> (2013-10-13 19:09:37 -0400) Execution failed with error StandardError
#=> (2013-10-13 19:09:38 -0400) Execution failed with error StandardError
#=> (2013-10-13 19:09:39 -0400) Execution failed with error StandardError
task.shutdown

See Also:

Constant Summary

EXECUTION_INTERVAL =

Default :execution_interval in seconds.

60
TIMEOUT_INTERVAL =

Default :timeout_interval in seconds.

30

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (TimerTask) initialize(opts = {}) {|task| ... }

Create a new TimerTask with the given task and configuration.

Parameters:

  • opts (Hash) (defaults to: {}) —

    the options defining task execution.

Options Hash (opts):

  • :execution_interval (Integer) —

    number of seconds between task executions (default: EXECUTION_INTERVAL)

  • :timeout_interval (Integer) —

    number of seconds a task can run before it is considered to have failed (default: TIMEOUT_INTERVAL)

  • :run_now (Boolean) —

    Whether to run the task immediately upon instantiation or to wait until the first # execution_interval has passed (default: false)

  • :dup_on_deref (Boolean) — default: false —

    Call #dup before returning the data from Concern::Dereferenceable#value

  • :freeze_on_deref (Boolean) — default: false —

    Call #freeze before returning the data from Concern::Dereferenceable#value

  • :copy_on_deref (Proc) — default: nil —

    When calling the Concern::Dereferenceable#value method, call the given proc passing the internal value as the sole argument then return the new value returned from the proc.

Yields:

  • to the block after :execution_interval seconds have passed since the last yield

Yield Parameters:

  • task —

    a reference to the TimerTask instance so that the block can control its own lifecycle. Necessary since self will refer to the execution context of the block rather than the running TimerTask.

Raises:

  • ArgumentError when no block is given.



189
190
191
192
 
# File 'lib/concurrent/timer_task.rb', line 189

def initialize(opts = {}, &task)
  raise ArgumentError.new('no block given') unless block_given?
  super
end

Instance Attribute Details

- (Fixnum) execution_interval

Returns Number of seconds after the task completes before the task is performed again.

Returns:

  • (Fixnum) —

    Number of seconds after the task completes before the task is performed again.



238
239
240
 
# File 'lib/concurrent/timer_task.rb', line 238

def execution_interval
  synchronize { @execution_interval }
end

- (Symbol) fallback_policy (readonly) Originally defined in class RubyExecutorService

Returns The fallback policy in effect. Either :abort, :discard, or :caller_runs.

Returns:

  • (Symbol) —

    The fallback policy in effect. Either :abort, :discard, or :caller_runs.

- (Symbol) fallback_policy (readonly) Originally defined in class AbstractExecutorService

Returns The fallback policy in effect. Either :abort, :discard, or :caller_runs.

Returns:

  • (Symbol) —

    The fallback policy in effect. Either :abort, :discard, or :caller_runs.

- (Fixnum) timeout_interval

Returns Number of seconds the task can run before it is considered to have failed.

Returns:

  • (Fixnum) —

    Number of seconds the task can run before it is considered to have failed.



256
257
258
 
# File 'lib/concurrent/timer_task.rb', line 256

def timeout_interval
  synchronize { @timeout_interval }
end

Class Method Details

+ (TimerTask) execute(opts = {}) {|task| ... }

Create and execute a new TimerTask.

Examples:

task = Concurrent::TimerTask.execute(execution_interval: 10){ print "Hello World\n" }
task.running? #=> true

Parameters:

  • opts (Hash) (defaults to: {}) —

    the options defining task execution.

Options Hash (opts):

  • :execution_interval (Integer) —

    number of seconds between task executions (default: EXECUTION_INTERVAL)

  • :timeout_interval (Integer) —

    number of seconds a task can run before it is considered to have failed (default: TIMEOUT_INTERVAL)

  • :run_now (Boolean) —

    Whether to run the task immediately upon instantiation or to wait until the first # execution_interval has passed (default: false)

  • :dup_on_deref (Boolean) — default: false —

    Call #dup before returning the data from Concern::Dereferenceable#value

  • :freeze_on_deref (Boolean) — default: false —

    Call #freeze before returning the data from Concern::Dereferenceable#value

  • :copy_on_deref (Proc) — default: nil —

    When calling the Concern::Dereferenceable#value method, call the given proc passing the internal value as the sole argument then return the new value returned from the proc.

Yields:

  • to the block after :execution_interval seconds have passed since the last yield

Yield Parameters:

  • task —

    a reference to the TimerTask instance so that the block can control its own lifecycle. Necessary since self will refer to the execution context of the block rather than the running TimerTask.

Returns:

Raises:

  • ArgumentError when no block is given.



231
232
233
 
# File 'lib/concurrent/timer_task.rb', line 231

def self.execute(opts = {}, &task)
  TimerTask.new(opts, &task).execute
end

Instance Method Details

- (Object) add_observer(observer = nil, func = :update, &block) Originally defined in module Concern::Observable

Adds an observer to this set. If a block is passed, the observer will be created by this method and no other params should be passed.

Parameters:

  • observer (Object) (defaults to: nil) —

    the observer to add

  • func (Symbol) (defaults to: :update) —

    the function to call on the observer during notification. Default is :update

Returns:

  • (Object) —

    the added observer

- (Integer) count_observers Originally defined in module Concern::Observable

Return the number of observers associated with this object.

Returns:

  • (Integer) —

    the observers count

- (Object) delete_observer(observer) Originally defined in module Concern::Observable

Remove observer as an observer on this object so that it will no longer receive notifications.

Parameters:

  • observer (Object) —

    the observer to remove

Returns:

  • (Object) —

    the deleted observer

- (Observable) delete_observers Originally defined in module Concern::Observable

Remove all observers associated with this object.

Returns:

- (TimerTask) execute

Execute a previously created TimerTask.

Examples:

Instance and execute in separate steps

task = Concurrent::TimerTask.new(execution_interval: 10){ print "Hello World\n" }
task.running? #=> false
task.execute
task.running? #=> true

Instance and execute in one line

task = Concurrent::TimerTask.new(execution_interval: 10){ print "Hello World\n" }.execute
task.running? #=> true

Returns:



214
215
216
217
218
219
220
221
222
 
# File 'lib/concurrent/timer_task.rb', line 214

def execute
  synchronize do
    if @running.false?
      @running.make_true
      schedule_next_task(@run_now ? 0 : @execution_interval)
    end
  end
  self
end

- (Boolean) running?

Is the executor running?

Returns:

  • (Boolean) —

    true when running, false when shutting down or shutdown



197
198
199
 
# File 'lib/concurrent/timer_task.rb', line 197

def running?
  @running.true?
end

- (Object) value Also known as: deref Originally defined in module Concern::Dereferenceable

Return the value this object represents after applying the options specified by the #set_deref_options method.

Returns:

  • (Object) —

    the current value of the object

- (Observable) with_observer(observer = nil, func = :update, &block) Originally defined in module Concern::Observable

As #add_observer but can be used for chaining.

Parameters:

  • observer (Object) (defaults to: nil) —

    the observer to add

  • func (Symbol) (defaults to: :update) —

    the function to call on the observer during notification.

Returns: