Class: Garcon::TimerTask
- Includes:
- Dereferenceable, Observable, RubyExecutor
- Defined in:
- lib/garcon/task/timer_task.rb
Overview
A very common currency 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. Derefencing 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 `Garcon::TimeoutError` object as the third argument.
Constant Summary collapse
- EXECUTION_INTERVAL =
Default :execution_interval in seconds.
60
- TIMEOUT_INTERVAL =
Default :timeout_interval in seconds.
30
Constants included from RubyExecutor
Instance Attribute Summary collapse
-
#execution_interval ⇒ Fixnum
Number of seconds after the task completes before it is performed again.
-
#timeout_interval ⇒ Fixnum
Number of seconds the task can run before it is considered failed.
Attributes included from Executor
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?.
Methods included from Observable
#add_observer, #count_observers, #delete_observer, #delete_observers, #with_observer
Methods included from RubyExecutor
#<<, #kill, #post, #shutdown, #shutdown?, #shuttingdown?, #wait_for_termination
Methods included from Executor
#auto_terminate?, #can_overflow?, #serialized?
Methods included from Dereferenceable
Constructor Details
#initialize(opts = {}) {|task| ... } ⇒ TimerTask
Calls Garcon::Dereferenceable# set_deref_options passing opts. All options supported by Garcon::Dereferenceable can be set during object initialization.
Create a new TimerTask with the given task and configuration.
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 |
# File 'lib/garcon/task/timer_task.rb', line 215 def initialize(opts = {}, &task) raise ArgumentError.new('no block given') unless block_given? init_executor (opts) self.execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL self.timeout_interval = opts[:timeout] || opts[:timeout_interval] || TIMEOUT_INTERVAL @run_now = opts[:now] || opts[:run_now] @executor = Garcon::SafeTaskExecutor.new(task) @running = Garcon::AtomicBoolean.new(false) self.observers = CopyOnNotifyObserverSet.new end |
Instance Attribute Details
#execution_interval ⇒ Fixnum
Returns Number of seconds after the task completes before it is performed again.
282 283 284 285 286 287 |
# File 'lib/garcon/task/timer_task.rb', line 282 def execution_interval mutex.lock @execution_interval ensure mutex.unlock end |
#timeout_interval ⇒ Fixnum
Returns Number of seconds the task can run before it is considered failed.
308 309 310 311 312 313 |
# File 'lib/garcon/task/timer_task.rb', line 308 def timeout_interval mutex.lock @timeout_interval ensure mutex.unlock end |
Class Method Details
.execute(opts = {}) {|task| ... } ⇒ TimerTask
Calls Garcon::Dereferenceable# set_deref_options passing opts. All options supported by Garcon::Dereferenceable can be set during object initialization.
Create and execute a new TimerTask.
275 276 277 |
# File 'lib/garcon/task/timer_task.rb', line 275 def self.execute(opts = {}, &task) TimerTask.new(opts, &task).execute end |
Instance Method Details
#execute ⇒ TimerTask
Execute a previously created TimerTask.
256 257 258 259 260 261 262 263 264 |
# File 'lib/garcon/task/timer_task.rb', line 256 def execute mutex.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?
238 239 240 |
# File 'lib/garcon/task/timer_task.rb', line 238 def running? @running.true? end |