Class: Concurrent::Delay
- Inherits:
-
Synchronization::LockableObject
- Object
- Synchronization::LockableObject
- Concurrent::Delay
- Includes:
- Concern::Obligation
- Defined in:
- lib/concurrent-ruby/concurrent/delay.rb
Overview
The default behavior of ‘Delay` is to block indefinitely when calling either `value` or `wait`, executing the delayed operation on the current thread. This makes the `timeout` value completely irrelevant. To enable non-blocking behavior, use the `executor` constructor option. This will cause the delayed operation to be execute on the given executor, allowing the call to timeout.
Lazy evaluation of a block yielding an immutable result. Useful for expensive operations that may never be needed. It may be non-blocking, supports the ‘Concern::Obligation` interface, and accepts the injection of custom executor upon which to execute the block. Processing of block will be deferred until the first time `#value` is called. At that time the caller can choose to return immediately and let the block execute asynchronously, block indefinitely, or block with a timeout.
When a ‘Delay` is created its state is set to `pending`. The value and reason are both `nil`. The first time the `#value` method is called the enclosed opration will be run and the calling thread will block. Other threads attempting to call `#value` will block as well. Once the operation is complete the value will be set to the result of the operation or the reason will be set to the raised exception, as appropriate. All threads blocked on `#value` will return. Subsequent calls to `#value` will immediately return the cached value. The operation will only be run once. This means that any side effects created by the operation will only happen once as well.
‘Delay` includes the `Concurrent::Concern::Dereferenceable` mixin to support thread safety of the reference returned by `#value`.
## Copy Options
Object references in Ruby are mutable. This can lead to serious problems when the #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.
Instance Method Summary collapse
-
#initialize(opts = {}) { ... } ⇒ Delay
constructor
Create a new ‘Delay` in the `:pending` state.
-
#reconfigure { ... } ⇒ true, false
Reconfigures the block returning the value if still ‘#incomplete?`.
-
#value(timeout = nil) ⇒ Object
Return the value this object represents after applying the options specified by the ‘#set_deref_options` method.
-
#value!(timeout = nil) ⇒ Object
Return the value this object represents after applying the options specified by the ‘#set_deref_options` method.
-
#wait(timeout = nil) ⇒ Object
Return the value this object represents after applying the options specified by the ‘#set_deref_options` method.
Methods included from Concern::Obligation
#complete?, #exception, #fulfilled?, #incomplete?, #pending?, #reason, #rejected?, #state, #unscheduled?, #wait!
Constructor Details
#initialize(opts = {}) { ... } ⇒ Delay
Create a new ‘Delay` in the `:pending` state.
62 63 64 65 66 |
# File 'lib/concurrent-ruby/concurrent/delay.rb', line 62 def initialize(opts = {}, &block) raise ArgumentError.new('no block given') unless block_given? super(&nil) synchronize { ns_initialize(opts, &block) } end |
Instance Method Details
#reconfigure { ... } ⇒ true, false
Reconfigures the block returning the value if still ‘#incomplete?`
146 147 148 149 150 151 152 153 154 155 156 |
# File 'lib/concurrent-ruby/concurrent/delay.rb', line 146 def reconfigure(&block) synchronize do raise ArgumentError.new('no block given') unless block_given? unless @evaluation_started @task = block true else false end end end |
#value(timeout = nil) ⇒ Object
The default behavior of ‘Delay` is to block indefinitely when calling either `value` or `wait`, executing the delayed operation on the current thread. This makes the `timeout` value completely irrelevant. To enable non-blocking behavior, use the `executor` constructor option. This will cause the delayed operation to be execute on the given executor, allowing the call to timeout.
Return the value this object represents after applying the options specified by the ‘#set_deref_options` method. If the delayed operation raised an exception this method will return nil. The execption object can be accessed via the `#reason` method.
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 |
# File 'lib/concurrent-ruby/concurrent/delay.rb', line 77 def value(timeout = nil) if @executor # TODO (pitr 12-Sep-2015): broken unsafe read? super else # this function has been optimized for performance and # should not be modified without running new benchmarks synchronize do execute = @evaluation_started = true unless @evaluation_started if execute begin set_state(true, @task.call, nil) rescue => ex set_state(false, nil, ex) end elsif incomplete? raise IllegalOperationError, 'Recursive call to #value during evaluation of the Delay' end end if @do_nothing_on_deref @value else (@value) end end end |
#value!(timeout = nil) ⇒ Object
The default behavior of ‘Delay` is to block indefinitely when calling either `value` or `wait`, executing the delayed operation on the current thread. This makes the `timeout` value completely irrelevant. To enable non-blocking behavior, use the `executor` constructor option. This will cause the delayed operation to be execute on the given executor, allowing the call to timeout.
Return the value this object represents after applying the options specified by the ‘#set_deref_options` method. If the delayed operation raised an exception, this method will raise that exception (even when) the operation has already been executed).
113 114 115 116 117 118 119 120 121 |
# File 'lib/concurrent-ruby/concurrent/delay.rb', line 113 def value!(timeout = nil) if @executor super else result = value raise @reason if @reason result end end |
#wait(timeout = nil) ⇒ Object
The default behavior of ‘Delay` is to block indefinitely when calling either `value` or `wait`, executing the delayed operation on the current thread. This makes the `timeout` value completely irrelevant. To enable non-blocking behavior, use the `executor` constructor option. This will cause the delayed operation to be execute on the given executor, allowing the call to timeout.
Return the value this object represents after applying the options specified by the ‘#set_deref_options` method.
132 133 134 135 136 137 138 139 140 |
# File 'lib/concurrent-ruby/concurrent/delay.rb', line 132 def wait(timeout = nil) if @executor execute_task_once super(timeout) else value end self end |