Class: Concurrent::TimerTask
- Inherits:
-
RubyExecutorService
- Object
- Synchronization::LockableObject
- AbstractExecutorService
- RubyExecutorService
- Concurrent::TimerTask
- Includes:
- Concern::Dereferenceable, Concern::Observable
- Defined in:
- lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/concurrent-ruby-1.1.10/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.
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).
## 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.
Constant Summary collapse
- EXECUTION_INTERVAL =
Default ‘:execution_interval` in seconds.
60
- TIMEOUT_INTERVAL =
Default ‘:timeout_interval` in seconds.
30
Constants inherited from AbstractExecutorService
AbstractExecutorService::FALLBACK_POLICIES
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?.
Methods included from Concern::Observable
#add_observer, #count_observers, #delete_observer, #delete_observers, #with_observer
Methods included from Concern::Dereferenceable
Constructor Details
#initialize(opts = {}) {|task| ... } ⇒ TimerTask
Create a new TimerTask with the given task and configuration.
180 181 182 183 184 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/concurrent-ruby-1.1.10/lib/concurrent-ruby/concurrent/timer_task.rb', line 180 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.
230 231 232 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/concurrent-ruby-1.1.10/lib/concurrent-ruby/concurrent/timer_task.rb', line 230 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.
248 249 250 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/concurrent-ruby-1.1.10/lib/concurrent-ruby/concurrent/timer_task.rb', line 248 def timeout_interval warn 'TimerTask timeouts are now ignored as these were not able to be implemented correctly' end |
Class Method Details
.execute(opts = {}) {|task| ... } ⇒ TimerTask
Create and execute a new ‘TimerTask`.
223 224 225 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/concurrent-ruby-1.1.10/lib/concurrent-ruby/concurrent/timer_task.rb', line 223 def self.execute(opts = {}, &task) TimerTask.new(opts, &task).execute end |
Instance Method Details
#execute ⇒ TimerTask
Execute a previously created ‘TimerTask`.
206 207 208 209 210 211 212 213 214 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/concurrent-ruby-1.1.10/lib/concurrent-ruby/concurrent/timer_task.rb', line 206 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?
189 190 191 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/concurrent-ruby-1.1.10/lib/concurrent-ruby/concurrent/timer_task.rb', line 189 def running? @running.true? end |