Class: Concurrent::TimerTask
- Inherits:
-
RubyExecutorService
- Object
- Synchronization::LockableObject
- AbstractExecutorService
- RubyExecutorService
- Concurrent::TimerTask
- Includes:
- Concern::Dereferenceable, Concern::Observable
- Defined in:
- lib/concurrent-ruby/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 thevalue
object every time the#value
method is called (default: false):freeze_on_deref
When true the object will call the#freeze
method on thevalue
object every time the#value
method is called (default: false):copy_on_deref
When given aProc
object theProc
will be run every time the#value
method is called. TheProc
will be given the currentvalue
as its only argument and the result returned by the block will be the return value of the#value
call. Whennil
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.
Constant Summary collapse
- EXECUTION_INTERVAL =
Default
:execution_interval
in seconds. 60
- TIMEOUT_INTERVAL =
Default
:timeout_interval
in seconds. 30
Instance Attribute Summary collapse
-
#execution_interval ⇒ Fixnum
Number of seconds after the task completes before the task is performed again.
-
#timeout_interval ⇒ Fixnum
Number of seconds the task can run before it is considered to have failed.
Class Method Summary collapse
-
.execute(opts = {}) {|task| ... } ⇒ TimerTask
Create and execute a new
TimerTask
.
Instance Method Summary collapse
-
#execute ⇒ TimerTask
Execute a previously created
TimerTask
. -
#initialize(opts = {}) {|task| ... } ⇒ TimerTask
constructor
Create a new TimerTask with the given task and configuration.
-
#running? ⇒ Boolean
Is the executor running?.
-
#add_observer(observer = nil, func = :update, &block) ⇒ Object
included
from Concern::Observable
Adds an observer to this set.
-
#count_observers ⇒ Integer
included
from Concern::Observable
Return the number of observers associated with this object.
-
#delete_observer(observer) ⇒ Object
included
from Concern::Observable
Remove
observer
as an observer on this object so that it will no longer receive notifications. -
#delete_observers ⇒ Observable
included
from Concern::Observable
Remove all observers associated with this object.
-
#value ⇒ Object
(also: #deref)
included
from Concern::Dereferenceable
Return the value this object represents after applying the options specified by the
#set_deref_options
method. -
#with_observer(observer = nil, func = :update, &block) ⇒ Observable
included
from Concern::Observable
As
#add_observer
but can be used for chaining.
Constructor Details
#initialize(opts = {}) {|task| ... } ⇒ TimerTask
Create a new TimerTask with the given task and configuration.
190 191 192 193 194 |
# File 'lib/concurrent-ruby/concurrent/timer_task.rb', line 190 def initialize(opts = {}, &task) raise ArgumentError.new('no block given') unless block_given? super opts end |
Instance Attribute Details
#execution_interval ⇒ Fixnum
Returns Number of seconds after the task completes before the task is performed again.
240 241 242 |
# File 'lib/concurrent-ruby/concurrent/timer_task.rb', line 240 def execution_interval synchronize { @execution_interval } end |
#timeout_interval ⇒ Fixnum
Returns Number of seconds the task can run before it is considered to have failed.
258 259 260 |
# File 'lib/concurrent-ruby/concurrent/timer_task.rb', line 258 def timeout_interval synchronize { @timeout_interval } end |
Class Method Details
Instance Method Details
#execute ⇒ TimerTask
Execute a previously created TimerTask
.
216 217 218 219 220 221 222 223 224 |
# File 'lib/concurrent-ruby/concurrent/timer_task.rb', line 216 def execute synchronize do if @running.false? @running.make_true schedule_next_task(@run_now ? 0 : @execution_interval) end end self end |
#running? ⇒ Boolean
Is the executor running?
199 200 201 |
# File 'lib/concurrent-ruby/concurrent/timer_task.rb', line 199 def running? @running.true? end |
#add_observer(observer = nil, func = :update, &block) ⇒ Object 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.
#count_observers ⇒ Integer Originally defined in module Concern::Observable
Return the number of observers associated with this object.
#delete_observer(observer) ⇒ Object Originally defined in module Concern::Observable
Remove observer
as an observer on this object so that it will no
longer receive notifications.
#delete_observers ⇒ Observable Originally defined in module Concern::Observable
Remove all observers associated with this object.
#value ⇒ Object 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.
#with_observer(observer = nil, func = :update, &block) ⇒ Observable Originally defined in module Concern::Observable
As #add_observer
but can be used for chaining.