concurrent-ruby 1.0.5 → 1.1.10

Sign up to get free protection for your applications and to get access to all the features.
Files changed (164) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +155 -0
  3. data/Gemfile +37 -0
  4. data/LICENSE.txt +18 -18
  5. data/README.md +260 -103
  6. data/Rakefile +329 -0
  7. data/ext/concurrent-ruby/ConcurrentRubyService.java +17 -0
  8. data/ext/concurrent-ruby/com/concurrent_ruby/ext/AtomicReferenceLibrary.java +175 -0
  9. data/ext/concurrent-ruby/com/concurrent_ruby/ext/JRubyMapBackendLibrary.java +248 -0
  10. data/ext/concurrent-ruby/com/concurrent_ruby/ext/JavaAtomicBooleanLibrary.java +93 -0
  11. data/ext/concurrent-ruby/com/concurrent_ruby/ext/JavaAtomicFixnumLibrary.java +113 -0
  12. data/ext/concurrent-ruby/com/concurrent_ruby/ext/JavaSemaphoreLibrary.java +189 -0
  13. data/ext/concurrent-ruby/com/concurrent_ruby/ext/SynchronizationLibrary.java +307 -0
  14. data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166e/ConcurrentHashMap.java +31 -0
  15. data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166e/ConcurrentHashMapV8.java +3863 -0
  16. data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166e/LongAdder.java +203 -0
  17. data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166e/Striped64.java +342 -0
  18. data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166e/nounsafe/ConcurrentHashMapV8.java +3800 -0
  19. data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166e/nounsafe/LongAdder.java +204 -0
  20. data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166e/nounsafe/Striped64.java +291 -0
  21. data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166y/ThreadLocalRandom.java +199 -0
  22. data/lib/{concurrent → concurrent-ruby/concurrent}/agent.rb +7 -7
  23. data/lib/concurrent-ruby/concurrent/array.rb +66 -0
  24. data/lib/{concurrent → concurrent-ruby/concurrent}/async.rb +28 -24
  25. data/lib/{concurrent → concurrent-ruby/concurrent}/atom.rb +10 -10
  26. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/atomic_boolean.rb +26 -22
  27. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/atomic_fixnum.rb +27 -23
  28. data/lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb +164 -0
  29. data/lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb +205 -0
  30. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/count_down_latch.rb +7 -7
  31. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/cyclic_barrier.rb +1 -1
  32. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/event.rb +3 -3
  33. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/java_count_down_latch.rb +9 -6
  34. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/mutex_atomic_boolean.rb +2 -0
  35. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/mutex_count_down_latch.rb +1 -0
  36. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/mutex_semaphore.rb +18 -2
  37. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/read_write_lock.rb +2 -1
  38. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/reentrant_read_write_lock.rb +7 -7
  39. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/ruby_thread_local_var.rb +60 -40
  40. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/semaphore.rb +34 -13
  41. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/thread_local_var.rb +8 -8
  42. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic_reference/mutex_atomic.rb +3 -8
  43. data/lib/{concurrent → concurrent-ruby/concurrent}/atomic_reference/numeric_cas_wrapper.rb +1 -1
  44. data/lib/concurrent-ruby/concurrent/atomics.rb +10 -0
  45. data/lib/concurrent-ruby/concurrent/collection/lock_free_stack.rb +158 -0
  46. data/lib/{concurrent → concurrent-ruby/concurrent}/collection/map/atomic_reference_map_backend.rb +3 -3
  47. data/lib/{concurrent → concurrent-ruby/concurrent}/collection/map/mri_map_backend.rb +1 -1
  48. data/lib/{concurrent → concurrent-ruby/concurrent}/collection/map/non_concurrent_map_backend.rb +1 -2
  49. data/lib/concurrent-ruby/concurrent/collection/map/truffleruby_map_backend.rb +14 -0
  50. data/lib/{concurrent → concurrent-ruby/concurrent}/collection/non_concurrent_priority_queue.rb +30 -30
  51. data/lib/{concurrent → concurrent-ruby/concurrent}/collection/ruby_non_concurrent_priority_queue.rb +11 -1
  52. data/lib/{concurrent → concurrent-ruby/concurrent}/concern/dereferenceable.rb +3 -3
  53. data/lib/{concurrent → concurrent-ruby/concurrent}/concern/logging.rb +6 -1
  54. data/lib/{concurrent → concurrent-ruby/concurrent}/concern/observable.rb +7 -7
  55. data/lib/concurrent-ruby/concurrent/concurrent_ruby.jar +0 -0
  56. data/lib/{concurrent → concurrent-ruby/concurrent}/configuration.rb +15 -15
  57. data/lib/{concurrent → concurrent-ruby/concurrent}/constants.rb +1 -1
  58. data/lib/{concurrent → concurrent-ruby/concurrent}/dataflow.rb +2 -1
  59. data/lib/{concurrent → concurrent-ruby/concurrent}/delay.rb +9 -7
  60. data/lib/{concurrent → concurrent-ruby/concurrent}/exchanger.rb +21 -25
  61. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/abstract_executor_service.rb +35 -38
  62. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/cached_thread_pool.rb +5 -5
  63. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/executor_service.rb +17 -17
  64. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/fixed_thread_pool.rb +47 -33
  65. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/java_executor_service.rb +20 -17
  66. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/java_single_thread_executor.rb +4 -3
  67. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/java_thread_pool_executor.rb +29 -9
  68. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/ruby_executor_service.rb +10 -6
  69. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/ruby_single_thread_executor.rb +0 -1
  70. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/ruby_thread_pool_executor.rb +46 -42
  71. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/safe_task_executor.rb +5 -5
  72. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/simple_executor_service.rb +1 -1
  73. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/single_thread_executor.rb +3 -2
  74. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/thread_pool_executor.rb +7 -6
  75. data/lib/{concurrent → concurrent-ruby/concurrent}/executor/timer_set.rb +14 -17
  76. data/lib/{concurrent → concurrent-ruby/concurrent}/future.rb +4 -1
  77. data/lib/concurrent-ruby/concurrent/hash.rb +59 -0
  78. data/lib/{concurrent → concurrent-ruby/concurrent}/immutable_struct.rb +9 -1
  79. data/lib/{concurrent → concurrent-ruby/concurrent}/ivar.rb +5 -6
  80. data/lib/concurrent-ruby/concurrent/map.rb +346 -0
  81. data/lib/{concurrent → concurrent-ruby/concurrent}/maybe.rb +1 -1
  82. data/lib/{concurrent → concurrent-ruby/concurrent}/mutable_struct.rb +27 -16
  83. data/lib/{concurrent → concurrent-ruby/concurrent}/mvar.rb +2 -2
  84. data/lib/{concurrent → concurrent-ruby/concurrent}/promise.rb +54 -21
  85. data/lib/concurrent-ruby/concurrent/promises.rb +2167 -0
  86. data/lib/concurrent-ruby/concurrent/re_include.rb +58 -0
  87. data/lib/{concurrent → concurrent-ruby/concurrent}/scheduled_task.rb +29 -16
  88. data/lib/concurrent-ruby/concurrent/set.rb +74 -0
  89. data/lib/{concurrent → concurrent-ruby/concurrent}/settable_struct.rb +12 -1
  90. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/abstract_lockable_object.rb +5 -5
  91. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/abstract_struct.rb +18 -4
  92. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/condition.rb +2 -0
  93. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/jruby_object.rb +1 -0
  94. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/lock.rb +2 -0
  95. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/lockable_object.rb +8 -10
  96. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/mri_object.rb +1 -0
  97. data/lib/concurrent-ruby/concurrent/synchronization/mutex_lockable_object.rb +88 -0
  98. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/object.rb +53 -23
  99. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/rbx_lockable_object.rb +6 -0
  100. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/rbx_object.rb +1 -0
  101. data/lib/concurrent-ruby/concurrent/synchronization/truffleruby_object.rb +47 -0
  102. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/volatile.rb +11 -9
  103. data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization.rb +4 -5
  104. data/lib/concurrent-ruby/concurrent/thread_safe/util/data_structures.rb +88 -0
  105. data/lib/{concurrent → concurrent-ruby/concurrent}/thread_safe/util/striped64.rb +9 -4
  106. data/lib/{concurrent → concurrent-ruby/concurrent}/timer_task.rb +15 -35
  107. data/lib/{concurrent → concurrent-ruby/concurrent}/tuple.rb +1 -1
  108. data/lib/{concurrent → concurrent-ruby/concurrent}/tvar.rb +21 -58
  109. data/lib/{concurrent → concurrent-ruby/concurrent}/utility/engine.rb +4 -4
  110. data/lib/concurrent-ruby/concurrent/utility/monotonic_time.rb +90 -0
  111. data/lib/concurrent-ruby/concurrent/utility/native_extension_loader.rb +79 -0
  112. data/lib/{concurrent → concurrent-ruby/concurrent}/utility/processor_counter.rb +5 -35
  113. data/lib/concurrent-ruby/concurrent/version.rb +3 -0
  114. data/lib/concurrent-ruby/concurrent-ruby.rb +5 -0
  115. data/lib/{concurrent.rb → concurrent-ruby/concurrent.rb} +24 -20
  116. metadata +149 -134
  117. data/lib/concurrent/array.rb +0 -39
  118. data/lib/concurrent/atomic/atomic_reference.rb +0 -51
  119. data/lib/concurrent/atomic_reference/concurrent_update_error.rb +0 -8
  120. data/lib/concurrent/atomic_reference/direct_update.rb +0 -81
  121. data/lib/concurrent/atomic_reference/jruby+truffle.rb +0 -2
  122. data/lib/concurrent/atomic_reference/jruby.rb +0 -16
  123. data/lib/concurrent/atomic_reference/rbx.rb +0 -22
  124. data/lib/concurrent/atomic_reference/ruby.rb +0 -32
  125. data/lib/concurrent/atomics.rb +0 -53
  126. data/lib/concurrent/edge.rb +0 -26
  127. data/lib/concurrent/hash.rb +0 -36
  128. data/lib/concurrent/lazy_register.rb +0 -81
  129. data/lib/concurrent/map.rb +0 -240
  130. data/lib/concurrent/synchronization/mri_lockable_object.rb +0 -71
  131. data/lib/concurrent/synchronization/truffle_lockable_object.rb +0 -9
  132. data/lib/concurrent/synchronization/truffle_object.rb +0 -31
  133. data/lib/concurrent/thread_safe/util/array_hash_rbx.rb +0 -30
  134. data/lib/concurrent/utility/at_exit.rb +0 -97
  135. data/lib/concurrent/utility/monotonic_time.rb +0 -58
  136. data/lib/concurrent/utility/native_extension_loader.rb +0 -73
  137. data/lib/concurrent/version.rb +0 -4
  138. /data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/abstract_thread_local_var.rb +0 -0
  139. /data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/java_thread_local_var.rb +0 -0
  140. /data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/mutex_atomic_fixnum.rb +0 -0
  141. /data/lib/{concurrent → concurrent-ruby/concurrent}/collection/copy_on_notify_observer_set.rb +0 -0
  142. /data/lib/{concurrent → concurrent-ruby/concurrent}/collection/copy_on_write_observer_set.rb +0 -0
  143. /data/lib/{concurrent → concurrent-ruby/concurrent}/collection/java_non_concurrent_priority_queue.rb +0 -0
  144. /data/lib/{concurrent → concurrent-ruby/concurrent}/collection/map/synchronized_map_backend.rb +0 -0
  145. /data/lib/{concurrent → concurrent-ruby/concurrent}/concern/deprecation.rb +0 -0
  146. /data/lib/{concurrent → concurrent-ruby/concurrent}/concern/obligation.rb +0 -0
  147. /data/lib/{concurrent → concurrent-ruby/concurrent}/errors.rb +0 -0
  148. /data/lib/{concurrent → concurrent-ruby/concurrent}/executor/immediate_executor.rb +0 -0
  149. /data/lib/{concurrent → concurrent-ruby/concurrent}/executor/indirect_immediate_executor.rb +0 -0
  150. /data/lib/{concurrent → concurrent-ruby/concurrent}/executor/serial_executor_service.rb +0 -0
  151. /data/lib/{concurrent → concurrent-ruby/concurrent}/executor/serialized_execution.rb +0 -0
  152. /data/lib/{concurrent → concurrent-ruby/concurrent}/executor/serialized_execution_delegator.rb +0 -0
  153. /data/lib/{concurrent → concurrent-ruby/concurrent}/executors.rb +0 -0
  154. /data/lib/{concurrent → concurrent-ruby/concurrent}/options.rb +0 -0
  155. /data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/abstract_object.rb +0 -0
  156. /data/lib/{concurrent → concurrent-ruby/concurrent}/synchronization/jruby_lockable_object.rb +0 -0
  157. /data/lib/{concurrent → concurrent-ruby/concurrent}/thread_safe/synchronized_delegator.rb +0 -0
  158. /data/lib/{concurrent → concurrent-ruby/concurrent}/thread_safe/util/adder.rb +0 -0
  159. /data/lib/{concurrent → concurrent-ruby/concurrent}/thread_safe/util/cheap_lockable.rb +0 -0
  160. /data/lib/{concurrent → concurrent-ruby/concurrent}/thread_safe/util/power_of_two_tuple.rb +0 -0
  161. /data/lib/{concurrent → concurrent-ruby/concurrent}/thread_safe/util/volatile.rb +0 -0
  162. /data/lib/{concurrent → concurrent-ruby/concurrent}/thread_safe/util/xor_shift_random.rb +0 -0
  163. /data/lib/{concurrent → concurrent-ruby/concurrent}/thread_safe/util.rb +0 -0
  164. /data/lib/{concurrent → concurrent-ruby/concurrent}/utility/native_integer.rb +0 -0
@@ -0,0 +1,2167 @@
1
+ require 'concurrent/synchronization'
2
+ require 'concurrent/atomic/atomic_boolean'
3
+ require 'concurrent/atomic/atomic_fixnum'
4
+ require 'concurrent/collection/lock_free_stack'
5
+ require 'concurrent/errors'
6
+ require 'concurrent/re_include'
7
+
8
+ module Concurrent
9
+
10
+ # {include:file:docs-source/promises-main.md}
11
+ module Promises
12
+
13
+ # @!macro promises.param.default_executor
14
+ # @param [Executor, :io, :fast] default_executor Instance of an executor or a name of the
15
+ # global executor. Default executor propagates to chained futures unless overridden with
16
+ # executor parameter or changed with {AbstractEventFuture#with_default_executor}.
17
+ #
18
+ # @!macro promises.param.executor
19
+ # @param [Executor, :io, :fast] executor Instance of an executor or a name of the
20
+ # global executor. The task is executed on it, default executor remains unchanged.
21
+ #
22
+ # @!macro promises.param.args
23
+ # @param [Object] args arguments which are passed to the task when it's executed.
24
+ # (It might be prepended with other arguments, see the @yeild section).
25
+ #
26
+ # @!macro promises.shortcut.on
27
+ # Shortcut of {#$0_on} with default `:io` executor supplied.
28
+ # @see #$0_on
29
+ #
30
+ # @!macro promises.shortcut.using
31
+ # Shortcut of {#$0_using} with default `:io` executor supplied.
32
+ # @see #$0_using
33
+ #
34
+ # @!macro promise.param.task-future
35
+ # @yieldreturn will become result of the returned Future.
36
+ # Its returned value becomes {Future#value} fulfilling it,
37
+ # raised exception becomes {Future#reason} rejecting it.
38
+ #
39
+ # @!macro promise.param.callback
40
+ # @yieldreturn is forgotten.
41
+
42
+ # Container of all {Future}, {Event} factory methods. They are never constructed directly with
43
+ # new.
44
+ module FactoryMethods
45
+ extend ReInclude
46
+ extend self
47
+
48
+ module Configuration
49
+ # @return [Executor, :io, :fast] the executor which is used when none is supplied
50
+ # to a factory method. The method can be overridden in the receivers of
51
+ # `include FactoryMethod`
52
+ def default_executor
53
+ :io
54
+ end
55
+ end
56
+
57
+ include Configuration
58
+
59
+ # @!macro promises.shortcut.on
60
+ # @return [ResolvableEvent]
61
+ def resolvable_event
62
+ resolvable_event_on default_executor
63
+ end
64
+
65
+ # Created resolvable event, user is responsible for resolving the event once by
66
+ # {Promises::ResolvableEvent#resolve}.
67
+ #
68
+ # @!macro promises.param.default_executor
69
+ # @return [ResolvableEvent]
70
+ def resolvable_event_on(default_executor = self.default_executor)
71
+ ResolvableEventPromise.new(default_executor).future
72
+ end
73
+
74
+ # @!macro promises.shortcut.on
75
+ # @return [ResolvableFuture]
76
+ def resolvable_future
77
+ resolvable_future_on default_executor
78
+ end
79
+
80
+ # Creates resolvable future, user is responsible for resolving the future once by
81
+ # {Promises::ResolvableFuture#resolve}, {Promises::ResolvableFuture#fulfill},
82
+ # or {Promises::ResolvableFuture#reject}
83
+ #
84
+ # @!macro promises.param.default_executor
85
+ # @return [ResolvableFuture]
86
+ def resolvable_future_on(default_executor = self.default_executor)
87
+ ResolvableFuturePromise.new(default_executor).future
88
+ end
89
+
90
+ # @!macro promises.shortcut.on
91
+ # @return [Future]
92
+ def future(*args, &task)
93
+ future_on(default_executor, *args, &task)
94
+ end
95
+
96
+ # Constructs new Future which will be resolved after block is evaluated on default executor.
97
+ # Evaluation begins immediately.
98
+ #
99
+ # @!macro promises.param.default_executor
100
+ # @!macro promises.param.args
101
+ # @yield [*args] to the task.
102
+ # @!macro promise.param.task-future
103
+ # @return [Future]
104
+ def future_on(default_executor, *args, &task)
105
+ ImmediateEventPromise.new(default_executor).future.then(*args, &task)
106
+ end
107
+
108
+ # Creates resolved future with will be either fulfilled with the given value or rejection with
109
+ # the given reason.
110
+ #
111
+ # @param [true, false] fulfilled
112
+ # @param [Object] value
113
+ # @param [Object] reason
114
+ # @!macro promises.param.default_executor
115
+ # @return [Future]
116
+ def resolved_future(fulfilled, value, reason, default_executor = self.default_executor)
117
+ ImmediateFuturePromise.new(default_executor, fulfilled, value, reason).future
118
+ end
119
+
120
+ # Creates resolved future with will be fulfilled with the given value.
121
+ #
122
+ # @!macro promises.param.default_executor
123
+ # @param [Object] value
124
+ # @return [Future]
125
+ def fulfilled_future(value, default_executor = self.default_executor)
126
+ resolved_future true, value, nil, default_executor
127
+ end
128
+
129
+ # Creates resolved future with will be rejected with the given reason.
130
+ #
131
+ # @!macro promises.param.default_executor
132
+ # @param [Object] reason
133
+ # @return [Future]
134
+ def rejected_future(reason, default_executor = self.default_executor)
135
+ resolved_future false, nil, reason, default_executor
136
+ end
137
+
138
+ # Creates resolved event.
139
+ #
140
+ # @!macro promises.param.default_executor
141
+ # @return [Event]
142
+ def resolved_event(default_executor = self.default_executor)
143
+ ImmediateEventPromise.new(default_executor).event
144
+ end
145
+
146
+ # General constructor. Behaves differently based on the argument's type. It's provided for convenience
147
+ # but it's better to be explicit.
148
+ #
149
+ # @see rejected_future, resolved_event, fulfilled_future
150
+ # @!macro promises.param.default_executor
151
+ # @return [Event, Future]
152
+ #
153
+ # @overload make_future(nil, default_executor = self.default_executor)
154
+ # @param [nil] nil
155
+ # @return [Event] resolved event.
156
+ #
157
+ # @overload make_future(a_future, default_executor = self.default_executor)
158
+ # @param [Future] a_future
159
+ # @return [Future] a future which will be resolved when a_future is.
160
+ #
161
+ # @overload make_future(an_event, default_executor = self.default_executor)
162
+ # @param [Event] an_event
163
+ # @return [Event] an event which will be resolved when an_event is.
164
+ #
165
+ # @overload make_future(exception, default_executor = self.default_executor)
166
+ # @param [Exception] exception
167
+ # @return [Future] a rejected future with the exception as its reason.
168
+ #
169
+ # @overload make_future(value, default_executor = self.default_executor)
170
+ # @param [Object] value when none of the above overloads fits
171
+ # @return [Future] a fulfilled future with the value.
172
+ def make_future(argument = nil, default_executor = self.default_executor)
173
+ case argument
174
+ when AbstractEventFuture
175
+ # returning wrapper would change nothing
176
+ argument
177
+ when Exception
178
+ rejected_future argument, default_executor
179
+ when nil
180
+ resolved_event default_executor
181
+ else
182
+ fulfilled_future argument, default_executor
183
+ end
184
+ end
185
+
186
+ # @!macro promises.shortcut.on
187
+ # @return [Future, Event]
188
+ def delay(*args, &task)
189
+ delay_on default_executor, *args, &task
190
+ end
191
+
192
+ # Creates new event or future which is resolved only after it is touched,
193
+ # see {Concurrent::AbstractEventFuture#touch}.
194
+ #
195
+ # @!macro promises.param.default_executor
196
+ # @overload delay_on(default_executor, *args, &task)
197
+ # If task is provided it returns a {Future} representing the result of the task.
198
+ # @!macro promises.param.args
199
+ # @yield [*args] to the task.
200
+ # @!macro promise.param.task-future
201
+ # @return [Future]
202
+ # @overload delay_on(default_executor)
203
+ # If no task is provided, it returns an {Event}
204
+ # @return [Event]
205
+ def delay_on(default_executor, *args, &task)
206
+ event = DelayPromise.new(default_executor).event
207
+ task ? event.chain(*args, &task) : event
208
+ end
209
+
210
+ # @!macro promises.shortcut.on
211
+ # @return [Future, Event]
212
+ def schedule(intended_time, *args, &task)
213
+ schedule_on default_executor, intended_time, *args, &task
214
+ end
215
+
216
+ # Creates new event or future which is resolved in intended_time.
217
+ #
218
+ # @!macro promises.param.default_executor
219
+ # @!macro promises.param.intended_time
220
+ # @param [Numeric, Time] intended_time `Numeric` means to run in `intended_time` seconds.
221
+ # `Time` means to run on `intended_time`.
222
+ # @overload schedule_on(default_executor, intended_time, *args, &task)
223
+ # If task is provided it returns a {Future} representing the result of the task.
224
+ # @!macro promises.param.args
225
+ # @yield [*args] to the task.
226
+ # @!macro promise.param.task-future
227
+ # @return [Future]
228
+ # @overload schedule_on(default_executor, intended_time)
229
+ # If no task is provided, it returns an {Event}
230
+ # @return [Event]
231
+ def schedule_on(default_executor, intended_time, *args, &task)
232
+ event = ScheduledPromise.new(default_executor, intended_time).event
233
+ task ? event.chain(*args, &task) : event
234
+ end
235
+
236
+ # @!macro promises.shortcut.on
237
+ # @return [Future]
238
+ def zip_futures(*futures_and_or_events)
239
+ zip_futures_on default_executor, *futures_and_or_events
240
+ end
241
+
242
+ # Creates new future which is resolved after all futures_and_or_events are resolved.
243
+ # Its value is array of zipped future values. Its reason is array of reasons for rejection.
244
+ # If there is an error it rejects.
245
+ # @!macro promises.event-conversion
246
+ # If event is supplied, which does not have value and can be only resolved, it's
247
+ # represented as `:fulfilled` with value `nil`.
248
+ #
249
+ # @!macro promises.param.default_executor
250
+ # @param [AbstractEventFuture] futures_and_or_events
251
+ # @return [Future]
252
+ def zip_futures_on(default_executor, *futures_and_or_events)
253
+ ZipFuturesPromise.new_blocked_by(futures_and_or_events, default_executor).future
254
+ end
255
+
256
+ alias_method :zip, :zip_futures
257
+
258
+ # @!macro promises.shortcut.on
259
+ # @return [Event]
260
+ def zip_events(*futures_and_or_events)
261
+ zip_events_on default_executor, *futures_and_or_events
262
+ end
263
+
264
+ # Creates new event which is resolved after all futures_and_or_events are resolved.
265
+ # (Future is resolved when fulfilled or rejected.)
266
+ #
267
+ # @!macro promises.param.default_executor
268
+ # @param [AbstractEventFuture] futures_and_or_events
269
+ # @return [Event]
270
+ def zip_events_on(default_executor, *futures_and_or_events)
271
+ ZipEventsPromise.new_blocked_by(futures_and_or_events, default_executor).event
272
+ end
273
+
274
+ # @!macro promises.shortcut.on
275
+ # @return [Future]
276
+ def any_resolved_future(*futures_and_or_events)
277
+ any_resolved_future_on default_executor, *futures_and_or_events
278
+ end
279
+
280
+ alias_method :any, :any_resolved_future
281
+
282
+ # Creates new future which is resolved after first futures_and_or_events is resolved.
283
+ # Its result equals result of the first resolved future.
284
+ # @!macro promises.any-touch
285
+ # If resolved it does not propagate {Concurrent::AbstractEventFuture#touch}, leaving delayed
286
+ # futures un-executed if they are not required any more.
287
+ # @!macro promises.event-conversion
288
+ #
289
+ # @!macro promises.param.default_executor
290
+ # @param [AbstractEventFuture] futures_and_or_events
291
+ # @return [Future]
292
+ def any_resolved_future_on(default_executor, *futures_and_or_events)
293
+ AnyResolvedFuturePromise.new_blocked_by(futures_and_or_events, default_executor).future
294
+ end
295
+
296
+ # @!macro promises.shortcut.on
297
+ # @return [Future]
298
+ def any_fulfilled_future(*futures_and_or_events)
299
+ any_fulfilled_future_on default_executor, *futures_and_or_events
300
+ end
301
+
302
+ # Creates new future which is resolved after first of futures_and_or_events is fulfilled.
303
+ # Its result equals result of the first resolved future or if all futures_and_or_events reject,
304
+ # it has reason of the last resolved future.
305
+ # @!macro promises.any-touch
306
+ # @!macro promises.event-conversion
307
+ #
308
+ # @!macro promises.param.default_executor
309
+ # @param [AbstractEventFuture] futures_and_or_events
310
+ # @return [Future]
311
+ def any_fulfilled_future_on(default_executor, *futures_and_or_events)
312
+ AnyFulfilledFuturePromise.new_blocked_by(futures_and_or_events, default_executor).future
313
+ end
314
+
315
+ # @!macro promises.shortcut.on
316
+ # @return [Future]
317
+ def any_event(*futures_and_or_events)
318
+ any_event_on default_executor, *futures_and_or_events
319
+ end
320
+
321
+ # Creates new event which becomes resolved after first of the futures_and_or_events resolves.
322
+ # @!macro promises.any-touch
323
+ #
324
+ # @!macro promises.param.default_executor
325
+ # @param [AbstractEventFuture] futures_and_or_events
326
+ # @return [Event]
327
+ def any_event_on(default_executor, *futures_and_or_events)
328
+ AnyResolvedEventPromise.new_blocked_by(futures_and_or_events, default_executor).event
329
+ end
330
+
331
+ # TODO consider adding first(count, *futures)
332
+ # TODO consider adding zip_by(slice, *futures) processing futures in slices
333
+ # TODO or rather a generic aggregator taking a function
334
+ end
335
+
336
+ module InternalStates
337
+ # @!visibility private
338
+ class State
339
+ def resolved?
340
+ raise NotImplementedError
341
+ end
342
+
343
+ def to_sym
344
+ raise NotImplementedError
345
+ end
346
+ end
347
+
348
+ # @!visibility private
349
+ class Pending < State
350
+ def resolved?
351
+ false
352
+ end
353
+
354
+ def to_sym
355
+ :pending
356
+ end
357
+ end
358
+
359
+ # @!visibility private
360
+ class Reserved < Pending
361
+ end
362
+
363
+ # @!visibility private
364
+ class ResolvedWithResult < State
365
+ def resolved?
366
+ true
367
+ end
368
+
369
+ def to_sym
370
+ :resolved
371
+ end
372
+
373
+ def result
374
+ [fulfilled?, value, reason]
375
+ end
376
+
377
+ def fulfilled?
378
+ raise NotImplementedError
379
+ end
380
+
381
+ def value
382
+ raise NotImplementedError
383
+ end
384
+
385
+ def reason
386
+ raise NotImplementedError
387
+ end
388
+
389
+ def apply
390
+ raise NotImplementedError
391
+ end
392
+ end
393
+
394
+ # @!visibility private
395
+ class Fulfilled < ResolvedWithResult
396
+
397
+ def initialize(value)
398
+ @Value = value
399
+ end
400
+
401
+ def fulfilled?
402
+ true
403
+ end
404
+
405
+ def apply(args, block)
406
+ block.call value, *args
407
+ end
408
+
409
+ def value
410
+ @Value
411
+ end
412
+
413
+ def reason
414
+ nil
415
+ end
416
+
417
+ def to_sym
418
+ :fulfilled
419
+ end
420
+ end
421
+
422
+ # @!visibility private
423
+ class FulfilledArray < Fulfilled
424
+ def apply(args, block)
425
+ block.call(*value, *args)
426
+ end
427
+ end
428
+
429
+ # @!visibility private
430
+ class Rejected < ResolvedWithResult
431
+ def initialize(reason)
432
+ @Reason = reason
433
+ end
434
+
435
+ def fulfilled?
436
+ false
437
+ end
438
+
439
+ def value
440
+ nil
441
+ end
442
+
443
+ def reason
444
+ @Reason
445
+ end
446
+
447
+ def to_sym
448
+ :rejected
449
+ end
450
+
451
+ def apply(args, block)
452
+ block.call reason, *args
453
+ end
454
+ end
455
+
456
+ # @!visibility private
457
+ class PartiallyRejected < ResolvedWithResult
458
+ def initialize(value, reason)
459
+ super()
460
+ @Value = value
461
+ @Reason = reason
462
+ end
463
+
464
+ def fulfilled?
465
+ false
466
+ end
467
+
468
+ def to_sym
469
+ :rejected
470
+ end
471
+
472
+ def value
473
+ @Value
474
+ end
475
+
476
+ def reason
477
+ @Reason
478
+ end
479
+
480
+ def apply(args, block)
481
+ block.call(*reason, *args)
482
+ end
483
+ end
484
+
485
+ # @!visibility private
486
+ PENDING = Pending.new
487
+ # @!visibility private
488
+ RESERVED = Reserved.new
489
+ # @!visibility private
490
+ RESOLVED = Fulfilled.new(nil)
491
+
492
+ def RESOLVED.to_sym
493
+ :resolved
494
+ end
495
+ end
496
+
497
+ private_constant :InternalStates
498
+
499
+ # @!macro promises.shortcut.event-future
500
+ # @see Event#$0
501
+ # @see Future#$0
502
+
503
+ # @!macro promises.param.timeout
504
+ # @param [Numeric] timeout the maximum time in second to wait.
505
+
506
+ # @!macro promises.warn.blocks
507
+ # @note This function potentially blocks current thread until the Future is resolved.
508
+ # Be careful it can deadlock. Try to chain instead.
509
+
510
+ # Common ancestor of {Event} and {Future} classes, many shared methods are defined here.
511
+ class AbstractEventFuture < Synchronization::Object
512
+ safe_initialization!
513
+ attr_atomic(:internal_state)
514
+ private :internal_state=, :swap_internal_state, :compare_and_set_internal_state, :update_internal_state
515
+ # @!method internal_state
516
+ # @!visibility private
517
+
518
+ include InternalStates
519
+
520
+ def initialize(promise, default_executor)
521
+ super()
522
+ @Lock = Mutex.new
523
+ @Condition = ConditionVariable.new
524
+ @Promise = promise
525
+ @DefaultExecutor = default_executor
526
+ @Callbacks = LockFreeStack.new
527
+ @Waiters = AtomicFixnum.new 0
528
+ self.internal_state = PENDING
529
+ end
530
+
531
+ private :initialize
532
+
533
+ # Returns its state.
534
+ # @return [Symbol]
535
+ #
536
+ # @overload an_event.state
537
+ # @return [:pending, :resolved]
538
+ # @overload a_future.state
539
+ # Both :fulfilled, :rejected implies :resolved.
540
+ # @return [:pending, :fulfilled, :rejected]
541
+ def state
542
+ internal_state.to_sym
543
+ end
544
+
545
+ # Is it in pending state?
546
+ # @return [Boolean]
547
+ def pending?
548
+ !internal_state.resolved?
549
+ end
550
+
551
+ # Is it in resolved state?
552
+ # @return [Boolean]
553
+ def resolved?
554
+ internal_state.resolved?
555
+ end
556
+
557
+ # Propagates touch. Requests all the delayed futures, which it depends on, to be
558
+ # executed. This method is called by any other method requiring resolved state, like {#wait}.
559
+ # @return [self]
560
+ def touch
561
+ @Promise.touch
562
+ self
563
+ end
564
+
565
+ # @!macro promises.touches
566
+ # Calls {Concurrent::AbstractEventFuture#touch}.
567
+
568
+ # @!macro promises.method.wait
569
+ # Wait (block the Thread) until receiver is {#resolved?}.
570
+ # @!macro promises.touches
571
+ #
572
+ # @!macro promises.warn.blocks
573
+ # @!macro promises.param.timeout
574
+ # @return [self, true, false] self implies timeout was not used, true implies timeout was used
575
+ # and it was resolved, false implies it was not resolved within timeout.
576
+ def wait(timeout = nil)
577
+ result = wait_until_resolved(timeout)
578
+ timeout ? result : self
579
+ end
580
+
581
+ # Returns default executor.
582
+ # @return [Executor] default executor
583
+ # @see #with_default_executor
584
+ # @see FactoryMethods#future_on
585
+ # @see FactoryMethods#resolvable_future
586
+ # @see FactoryMethods#any_fulfilled_future_on
587
+ # @see similar
588
+ def default_executor
589
+ @DefaultExecutor
590
+ end
591
+
592
+ # @!macro promises.shortcut.on
593
+ # @return [Future]
594
+ def chain(*args, &task)
595
+ chain_on @DefaultExecutor, *args, &task
596
+ end
597
+
598
+ # Chains the task to be executed asynchronously on executor after it is resolved.
599
+ #
600
+ # @!macro promises.param.executor
601
+ # @!macro promises.param.args
602
+ # @return [Future]
603
+ # @!macro promise.param.task-future
604
+ #
605
+ # @overload an_event.chain_on(executor, *args, &task)
606
+ # @yield [*args] to the task.
607
+ # @overload a_future.chain_on(executor, *args, &task)
608
+ # @yield [fulfilled, value, reason, *args] to the task.
609
+ # @yieldparam [true, false] fulfilled
610
+ # @yieldparam [Object] value
611
+ # @yieldparam [Object] reason
612
+ def chain_on(executor, *args, &task)
613
+ ChainPromise.new_blocked_by1(self, @DefaultExecutor, executor, args, &task).future
614
+ end
615
+
616
+ # @return [String] Short string representation.
617
+ def to_s
618
+ format '%s %s>', super[0..-2], state
619
+ end
620
+
621
+ alias_method :inspect, :to_s
622
+
623
+ # Resolves the resolvable when receiver is resolved.
624
+ #
625
+ # @param [Resolvable] resolvable
626
+ # @return [self]
627
+ def chain_resolvable(resolvable)
628
+ on_resolution! { resolvable.resolve_with internal_state }
629
+ end
630
+
631
+ alias_method :tangle, :chain_resolvable
632
+
633
+ # @!macro promises.shortcut.using
634
+ # @return [self]
635
+ def on_resolution(*args, &callback)
636
+ on_resolution_using @DefaultExecutor, *args, &callback
637
+ end
638
+
639
+ # Stores the callback to be executed synchronously on resolving thread after it is
640
+ # resolved.
641
+ #
642
+ # @!macro promises.param.args
643
+ # @!macro promise.param.callback
644
+ # @return [self]
645
+ #
646
+ # @overload an_event.on_resolution!(*args, &callback)
647
+ # @yield [*args] to the callback.
648
+ # @overload a_future.on_resolution!(*args, &callback)
649
+ # @yield [fulfilled, value, reason, *args] to the callback.
650
+ # @yieldparam [true, false] fulfilled
651
+ # @yieldparam [Object] value
652
+ # @yieldparam [Object] reason
653
+ def on_resolution!(*args, &callback)
654
+ add_callback :callback_on_resolution, args, callback
655
+ end
656
+
657
+ # Stores the callback to be executed asynchronously on executor after it is resolved.
658
+ #
659
+ # @!macro promises.param.executor
660
+ # @!macro promises.param.args
661
+ # @!macro promise.param.callback
662
+ # @return [self]
663
+ #
664
+ # @overload an_event.on_resolution_using(executor, *args, &callback)
665
+ # @yield [*args] to the callback.
666
+ # @overload a_future.on_resolution_using(executor, *args, &callback)
667
+ # @yield [fulfilled, value, reason, *args] to the callback.
668
+ # @yieldparam [true, false] fulfilled
669
+ # @yieldparam [Object] value
670
+ # @yieldparam [Object] reason
671
+ def on_resolution_using(executor, *args, &callback)
672
+ add_callback :async_callback_on_resolution, executor, args, callback
673
+ end
674
+
675
+ # @!macro promises.method.with_default_executor
676
+ # Crates new object with same class with the executor set as its new default executor.
677
+ # Any futures depending on it will use the new default executor.
678
+ # @!macro promises.shortcut.event-future
679
+ # @abstract
680
+ # @return [AbstractEventFuture]
681
+ def with_default_executor(executor)
682
+ raise NotImplementedError
683
+ end
684
+
685
+ # @!visibility private
686
+ def resolve_with(state, raise_on_reassign = true, reserved = false)
687
+ if compare_and_set_internal_state(reserved ? RESERVED : PENDING, state)
688
+ # go to synchronized block only if there were waiting threads
689
+ @Lock.synchronize { @Condition.broadcast } unless @Waiters.value == 0
690
+ call_callbacks state
691
+ else
692
+ return rejected_resolution(raise_on_reassign, state)
693
+ end
694
+ self
695
+ end
696
+
697
+ # For inspection.
698
+ # @!visibility private
699
+ # @return [Array<AbstractPromise>]
700
+ def blocks
701
+ @Callbacks.each_with_object([]) do |(method, args), promises|
702
+ promises.push(args[0]) if method == :callback_notify_blocked
703
+ end
704
+ end
705
+
706
+ # For inspection.
707
+ # @!visibility private
708
+ def callbacks
709
+ @Callbacks.each.to_a
710
+ end
711
+
712
+ # For inspection.
713
+ # @!visibility private
714
+ def promise
715
+ @Promise
716
+ end
717
+
718
+ # For inspection.
719
+ # @!visibility private
720
+ def touched?
721
+ promise.touched?
722
+ end
723
+
724
+ # For inspection.
725
+ # @!visibility private
726
+ def waiting_threads
727
+ @Waiters.each.to_a
728
+ end
729
+
730
+ # @!visibility private
731
+ def add_callback_notify_blocked(promise, index)
732
+ add_callback :callback_notify_blocked, promise, index
733
+ end
734
+
735
+ # @!visibility private
736
+ def add_callback_clear_delayed_node(node)
737
+ add_callback(:callback_clear_delayed_node, node)
738
+ end
739
+
740
+ # @!visibility private
741
+ def with_hidden_resolvable
742
+ # TODO (pitr-ch 10-Dec-2018): documentation, better name if in edge
743
+ self
744
+ end
745
+
746
+ private
747
+
748
+ def add_callback(method, *args)
749
+ state = internal_state
750
+ if state.resolved?
751
+ call_callback method, state, args
752
+ else
753
+ @Callbacks.push [method, args]
754
+ state = internal_state
755
+ # take back if it was resolved in the meanwhile
756
+ call_callbacks state if state.resolved?
757
+ end
758
+ self
759
+ end
760
+
761
+ def callback_clear_delayed_node(state, node)
762
+ node.value = nil
763
+ end
764
+
765
+ # @return [Boolean]
766
+ def wait_until_resolved(timeout)
767
+ return true if resolved?
768
+
769
+ touch
770
+
771
+ @Lock.synchronize do
772
+ @Waiters.increment
773
+ begin
774
+ unless resolved?
775
+ @Condition.wait @Lock, timeout
776
+ end
777
+ ensure
778
+ # JRuby may raise ConcurrencyError
779
+ @Waiters.decrement
780
+ end
781
+ end
782
+ resolved?
783
+ end
784
+
785
+ def call_callback(method, state, args)
786
+ self.send method, state, *args
787
+ end
788
+
789
+ def call_callbacks(state)
790
+ method, args = @Callbacks.pop
791
+ while method
792
+ call_callback method, state, args
793
+ method, args = @Callbacks.pop
794
+ end
795
+ end
796
+
797
+ def with_async(executor, *args, &block)
798
+ Concurrent.executor(executor).post(*args, &block)
799
+ end
800
+
801
+ def async_callback_on_resolution(state, executor, args, callback)
802
+ with_async(executor, state, args, callback) do |st, ar, cb|
803
+ callback_on_resolution st, ar, cb
804
+ end
805
+ end
806
+
807
+ def callback_notify_blocked(state, promise, index)
808
+ promise.on_blocker_resolution self, index
809
+ end
810
+ end
811
+
812
+ # Represents an event which will happen in future (will be resolved). The event is either
813
+ # pending or resolved. It should be always resolved. Use {Future} to communicate rejections and
814
+ # cancellation.
815
+ class Event < AbstractEventFuture
816
+
817
+ alias_method :then, :chain
818
+
819
+
820
+ # @!macro promises.method.zip
821
+ # Creates a new event or a future which will be resolved when receiver and other are.
822
+ # Returns an event if receiver and other are events, otherwise returns a future.
823
+ # If just one of the parties is Future then the result
824
+ # of the returned future is equal to the result of the supplied future. If both are futures
825
+ # then the result is as described in {FactoryMethods#zip_futures_on}.
826
+ #
827
+ # @return [Future, Event]
828
+ def zip(other)
829
+ if other.is_a?(Future)
830
+ ZipFutureEventPromise.new_blocked_by2(other, self, @DefaultExecutor).future
831
+ else
832
+ ZipEventEventPromise.new_blocked_by2(self, other, @DefaultExecutor).event
833
+ end
834
+ end
835
+
836
+ alias_method :&, :zip
837
+
838
+ # Creates a new event which will be resolved when the first of receiver, `event_or_future`
839
+ # resolves.
840
+ #
841
+ # @return [Event]
842
+ def any(event_or_future)
843
+ AnyResolvedEventPromise.new_blocked_by2(self, event_or_future, @DefaultExecutor).event
844
+ end
845
+
846
+ alias_method :|, :any
847
+
848
+ # Creates new event dependent on receiver which will not evaluate until touched, see {#touch}.
849
+ # In other words, it inserts delay into the chain of Futures making rest of it lazy evaluated.
850
+ #
851
+ # @return [Event]
852
+ def delay
853
+ event = DelayPromise.new(@DefaultExecutor).event
854
+ ZipEventEventPromise.new_blocked_by2(self, event, @DefaultExecutor).event
855
+ end
856
+
857
+ # @!macro promise.method.schedule
858
+ # Creates new event dependent on receiver scheduled to execute on/in intended_time.
859
+ # In time is interpreted from the moment the receiver is resolved, therefore it inserts
860
+ # delay into the chain.
861
+ #
862
+ # @!macro promises.param.intended_time
863
+ # @return [Event]
864
+ def schedule(intended_time)
865
+ chain do
866
+ event = ScheduledPromise.new(@DefaultExecutor, intended_time).event
867
+ ZipEventEventPromise.new_blocked_by2(self, event, @DefaultExecutor).event
868
+ end.flat_event
869
+ end
870
+
871
+ # Converts event to a future. The future is fulfilled when the event is resolved, the future may never fail.
872
+ #
873
+ # @return [Future]
874
+ def to_future
875
+ future = Promises.resolvable_future
876
+ ensure
877
+ chain_resolvable(future)
878
+ end
879
+
880
+ # Returns self, since this is event
881
+ # @return [Event]
882
+ def to_event
883
+ self
884
+ end
885
+
886
+ # @!macro promises.method.with_default_executor
887
+ # @return [Event]
888
+ def with_default_executor(executor)
889
+ EventWrapperPromise.new_blocked_by1(self, executor).event
890
+ end
891
+
892
+ private
893
+
894
+ def rejected_resolution(raise_on_reassign, state)
895
+ Concurrent::MultipleAssignmentError.new('Event can be resolved only once') if raise_on_reassign
896
+ return false
897
+ end
898
+
899
+ def callback_on_resolution(state, args, callback)
900
+ callback.call(*args)
901
+ end
902
+ end
903
+
904
+ # Represents a value which will become available in future. May reject with a reason instead,
905
+ # e.g. when the tasks raises an exception.
906
+ class Future < AbstractEventFuture
907
+
908
+ # Is it in fulfilled state?
909
+ # @return [Boolean]
910
+ def fulfilled?
911
+ state = internal_state
912
+ state.resolved? && state.fulfilled?
913
+ end
914
+
915
+ # Is it in rejected state?
916
+ # @return [Boolean]
917
+ def rejected?
918
+ state = internal_state
919
+ state.resolved? && !state.fulfilled?
920
+ end
921
+
922
+ # @!macro promises.warn.nil
923
+ # @note Make sure returned `nil` is not confused with timeout, no value when rejected,
924
+ # no reason when fulfilled, etc.
925
+ # Use more exact methods if needed, like {#wait}, {#value!}, {#result}, etc.
926
+
927
+ # @!macro promises.method.value
928
+ # Return value of the future.
929
+ # @!macro promises.touches
930
+ #
931
+ # @!macro promises.warn.blocks
932
+ # @!macro promises.warn.nil
933
+ # @!macro promises.param.timeout
934
+ # @!macro promises.param.timeout_value
935
+ # @param [Object] timeout_value a value returned by the method when it times out
936
+ # @return [Object, nil, timeout_value] the value of the Future when fulfilled,
937
+ # timeout_value on timeout,
938
+ # nil on rejection.
939
+ def value(timeout = nil, timeout_value = nil)
940
+ if wait_until_resolved timeout
941
+ internal_state.value
942
+ else
943
+ timeout_value
944
+ end
945
+ end
946
+
947
+ # Returns reason of future's rejection.
948
+ # @!macro promises.touches
949
+ #
950
+ # @!macro promises.warn.blocks
951
+ # @!macro promises.warn.nil
952
+ # @!macro promises.param.timeout
953
+ # @!macro promises.param.timeout_value
954
+ # @return [Object, timeout_value] the reason, or timeout_value on timeout, or nil on fulfillment.
955
+ def reason(timeout = nil, timeout_value = nil)
956
+ if wait_until_resolved timeout
957
+ internal_state.reason
958
+ else
959
+ timeout_value
960
+ end
961
+ end
962
+
963
+ # Returns triplet fulfilled?, value, reason.
964
+ # @!macro promises.touches
965
+ #
966
+ # @!macro promises.warn.blocks
967
+ # @!macro promises.param.timeout
968
+ # @return [Array(Boolean, Object, Object), nil] triplet of fulfilled?, value, reason, or nil
969
+ # on timeout.
970
+ def result(timeout = nil)
971
+ internal_state.result if wait_until_resolved timeout
972
+ end
973
+
974
+ # @!macro promises.method.wait
975
+ # @raise [Exception] {#reason} on rejection
976
+ def wait!(timeout = nil)
977
+ result = wait_until_resolved!(timeout)
978
+ timeout ? result : self
979
+ end
980
+
981
+ # @!macro promises.method.value
982
+ # @return [Object, nil, timeout_value] the value of the Future when fulfilled,
983
+ # or nil on rejection,
984
+ # or timeout_value on timeout.
985
+ # @raise [Exception] {#reason} on rejection
986
+ def value!(timeout = nil, timeout_value = nil)
987
+ if wait_until_resolved! timeout
988
+ internal_state.value
989
+ else
990
+ timeout_value
991
+ end
992
+ end
993
+
994
+ # Allows rejected Future to be risen with `raise` method.
995
+ # If the reason is not an exception `Runtime.new(reason)` is returned.
996
+ #
997
+ # @example
998
+ # raise Promises.rejected_future(StandardError.new("boom"))
999
+ # raise Promises.rejected_future("or just boom")
1000
+ # @raise [Concurrent::Error] when raising not rejected future
1001
+ # @return [Exception]
1002
+ def exception(*args)
1003
+ raise Concurrent::Error, 'it is not rejected' unless rejected?
1004
+ raise ArgumentError unless args.size <= 1
1005
+ reason = Array(internal_state.reason).flatten.compact
1006
+ if reason.size > 1
1007
+ ex = Concurrent::MultipleErrors.new reason
1008
+ ex.set_backtrace(caller)
1009
+ ex
1010
+ else
1011
+ ex = if reason[0].respond_to? :exception
1012
+ reason[0].exception(*args)
1013
+ else
1014
+ RuntimeError.new(reason[0]).exception(*args)
1015
+ end
1016
+ ex.set_backtrace Array(ex.backtrace) + caller
1017
+ ex
1018
+ end
1019
+ end
1020
+
1021
+ # @!macro promises.shortcut.on
1022
+ # @return [Future]
1023
+ def then(*args, &task)
1024
+ then_on @DefaultExecutor, *args, &task
1025
+ end
1026
+
1027
+ # Chains the task to be executed asynchronously on executor after it fulfills. Does not run
1028
+ # the task if it rejects. It will resolve though, triggering any dependent futures.
1029
+ #
1030
+ # @!macro promises.param.executor
1031
+ # @!macro promises.param.args
1032
+ # @!macro promise.param.task-future
1033
+ # @return [Future]
1034
+ # @yield [value, *args] to the task.
1035
+ def then_on(executor, *args, &task)
1036
+ ThenPromise.new_blocked_by1(self, @DefaultExecutor, executor, args, &task).future
1037
+ end
1038
+
1039
+ # @!macro promises.shortcut.on
1040
+ # @return [Future]
1041
+ def rescue(*args, &task)
1042
+ rescue_on @DefaultExecutor, *args, &task
1043
+ end
1044
+
1045
+ # Chains the task to be executed asynchronously on executor after it rejects. Does not run
1046
+ # the task if it fulfills. It will resolve though, triggering any dependent futures.
1047
+ #
1048
+ # @!macro promises.param.executor
1049
+ # @!macro promises.param.args
1050
+ # @!macro promise.param.task-future
1051
+ # @return [Future]
1052
+ # @yield [reason, *args] to the task.
1053
+ def rescue_on(executor, *args, &task)
1054
+ RescuePromise.new_blocked_by1(self, @DefaultExecutor, executor, args, &task).future
1055
+ end
1056
+
1057
+ # @!macro promises.method.zip
1058
+ # @return [Future]
1059
+ def zip(other)
1060
+ if other.is_a?(Future)
1061
+ ZipFuturesPromise.new_blocked_by2(self, other, @DefaultExecutor).future
1062
+ else
1063
+ ZipFutureEventPromise.new_blocked_by2(self, other, @DefaultExecutor).future
1064
+ end
1065
+ end
1066
+
1067
+ alias_method :&, :zip
1068
+
1069
+ # Creates a new event which will be resolved when the first of receiver, `event_or_future`
1070
+ # resolves. Returning future will have value nil if event_or_future is event and resolves
1071
+ # first.
1072
+ #
1073
+ # @return [Future]
1074
+ def any(event_or_future)
1075
+ AnyResolvedFuturePromise.new_blocked_by2(self, event_or_future, @DefaultExecutor).future
1076
+ end
1077
+
1078
+ alias_method :|, :any
1079
+
1080
+ # Creates new future dependent on receiver which will not evaluate until touched, see {#touch}.
1081
+ # In other words, it inserts delay into the chain of Futures making rest of it lazy evaluated.
1082
+ #
1083
+ # @return [Future]
1084
+ def delay
1085
+ event = DelayPromise.new(@DefaultExecutor).event
1086
+ ZipFutureEventPromise.new_blocked_by2(self, event, @DefaultExecutor).future
1087
+ end
1088
+
1089
+ # @!macro promise.method.schedule
1090
+ # @return [Future]
1091
+ def schedule(intended_time)
1092
+ chain do
1093
+ event = ScheduledPromise.new(@DefaultExecutor, intended_time).event
1094
+ ZipFutureEventPromise.new_blocked_by2(self, event, @DefaultExecutor).future
1095
+ end.flat
1096
+ end
1097
+
1098
+ # @!macro promises.method.with_default_executor
1099
+ # @return [Future]
1100
+ def with_default_executor(executor)
1101
+ FutureWrapperPromise.new_blocked_by1(self, executor).future
1102
+ end
1103
+
1104
+ # Creates new future which will have result of the future returned by receiver. If receiver
1105
+ # rejects it will have its rejection.
1106
+ #
1107
+ # @param [Integer] level how many levels of futures should flatten
1108
+ # @return [Future]
1109
+ def flat_future(level = 1)
1110
+ FlatFuturePromise.new_blocked_by1(self, level, @DefaultExecutor).future
1111
+ end
1112
+
1113
+ alias_method :flat, :flat_future
1114
+
1115
+ # Creates new event which will be resolved when the returned event by receiver is.
1116
+ # Be careful if the receiver rejects it will just resolve since Event does not hold reason.
1117
+ #
1118
+ # @return [Event]
1119
+ def flat_event
1120
+ FlatEventPromise.new_blocked_by1(self, @DefaultExecutor).event
1121
+ end
1122
+
1123
+ # @!macro promises.shortcut.using
1124
+ # @return [self]
1125
+ def on_fulfillment(*args, &callback)
1126
+ on_fulfillment_using @DefaultExecutor, *args, &callback
1127
+ end
1128
+
1129
+ # Stores the callback to be executed synchronously on resolving thread after it is
1130
+ # fulfilled. Does nothing on rejection.
1131
+ #
1132
+ # @!macro promises.param.args
1133
+ # @!macro promise.param.callback
1134
+ # @return [self]
1135
+ # @yield [value, *args] to the callback.
1136
+ def on_fulfillment!(*args, &callback)
1137
+ add_callback :callback_on_fulfillment, args, callback
1138
+ end
1139
+
1140
+ # Stores the callback to be executed asynchronously on executor after it is
1141
+ # fulfilled. Does nothing on rejection.
1142
+ #
1143
+ # @!macro promises.param.executor
1144
+ # @!macro promises.param.args
1145
+ # @!macro promise.param.callback
1146
+ # @return [self]
1147
+ # @yield [value, *args] to the callback.
1148
+ def on_fulfillment_using(executor, *args, &callback)
1149
+ add_callback :async_callback_on_fulfillment, executor, args, callback
1150
+ end
1151
+
1152
+ # @!macro promises.shortcut.using
1153
+ # @return [self]
1154
+ def on_rejection(*args, &callback)
1155
+ on_rejection_using @DefaultExecutor, *args, &callback
1156
+ end
1157
+
1158
+ # Stores the callback to be executed synchronously on resolving thread after it is
1159
+ # rejected. Does nothing on fulfillment.
1160
+ #
1161
+ # @!macro promises.param.args
1162
+ # @!macro promise.param.callback
1163
+ # @return [self]
1164
+ # @yield [reason, *args] to the callback.
1165
+ def on_rejection!(*args, &callback)
1166
+ add_callback :callback_on_rejection, args, callback
1167
+ end
1168
+
1169
+ # Stores the callback to be executed asynchronously on executor after it is
1170
+ # rejected. Does nothing on fulfillment.
1171
+ #
1172
+ # @!macro promises.param.executor
1173
+ # @!macro promises.param.args
1174
+ # @!macro promise.param.callback
1175
+ # @return [self]
1176
+ # @yield [reason, *args] to the callback.
1177
+ def on_rejection_using(executor, *args, &callback)
1178
+ add_callback :async_callback_on_rejection, executor, args, callback
1179
+ end
1180
+
1181
+ # Allows to use futures as green threads. The receiver has to evaluate to a future which
1182
+ # represents what should be done next. It basically flattens indefinitely until non Future
1183
+ # values is returned which becomes result of the returned future. Any encountered exception
1184
+ # will become reason of the returned future.
1185
+ #
1186
+ # @return [Future]
1187
+ # @param [#call(value)] run_test
1188
+ # an object which when called returns either Future to keep running with
1189
+ # or nil, then the run completes with the value.
1190
+ # The run_test can be used to extract the Future from deeper structure,
1191
+ # or to distinguish Future which is a resulting value from a future
1192
+ # which is suppose to continue running.
1193
+ # @example
1194
+ # body = lambda do |v|
1195
+ # v += 1
1196
+ # v < 5 ? Promises.future(v, &body) : v
1197
+ # end
1198
+ # Promises.future(0, &body).run.value! # => 5
1199
+ def run(run_test = method(:run_test))
1200
+ RunFuturePromise.new_blocked_by1(self, @DefaultExecutor, run_test).future
1201
+ end
1202
+
1203
+ # @!visibility private
1204
+ def apply(args, block)
1205
+ internal_state.apply args, block
1206
+ end
1207
+
1208
+ # Converts future to event which is resolved when future is resolved by fulfillment or rejection.
1209
+ #
1210
+ # @return [Event]
1211
+ def to_event
1212
+ event = Promises.resolvable_event
1213
+ ensure
1214
+ chain_resolvable(event)
1215
+ end
1216
+
1217
+ # Returns self, since this is a future
1218
+ # @return [Future]
1219
+ def to_future
1220
+ self
1221
+ end
1222
+
1223
+ # @return [String] Short string representation.
1224
+ def to_s
1225
+ if resolved?
1226
+ format '%s with %s>', super[0..-2], (fulfilled? ? value : reason).inspect
1227
+ else
1228
+ super
1229
+ end
1230
+ end
1231
+
1232
+ alias_method :inspect, :to_s
1233
+
1234
+ private
1235
+
1236
+ def run_test(v)
1237
+ v if v.is_a?(Future)
1238
+ end
1239
+
1240
+ def rejected_resolution(raise_on_reassign, state)
1241
+ if raise_on_reassign
1242
+ if internal_state == RESERVED
1243
+ raise Concurrent::MultipleAssignmentError.new(
1244
+ "Future can be resolved only once. It is already reserved.")
1245
+ else
1246
+ raise Concurrent::MultipleAssignmentError.new(
1247
+ "Future can be resolved only once. It's #{result}, trying to set #{state.result}.",
1248
+ current_result: result,
1249
+ new_result: state.result)
1250
+ end
1251
+ end
1252
+ return false
1253
+ end
1254
+
1255
+ def wait_until_resolved!(timeout = nil)
1256
+ result = wait_until_resolved(timeout)
1257
+ raise self if rejected?
1258
+ result
1259
+ end
1260
+
1261
+ def async_callback_on_fulfillment(state, executor, args, callback)
1262
+ with_async(executor, state, args, callback) do |st, ar, cb|
1263
+ callback_on_fulfillment st, ar, cb
1264
+ end
1265
+ end
1266
+
1267
+ def async_callback_on_rejection(state, executor, args, callback)
1268
+ with_async(executor, state, args, callback) do |st, ar, cb|
1269
+ callback_on_rejection st, ar, cb
1270
+ end
1271
+ end
1272
+
1273
+ def callback_on_fulfillment(state, args, callback)
1274
+ state.apply args, callback if state.fulfilled?
1275
+ end
1276
+
1277
+ def callback_on_rejection(state, args, callback)
1278
+ state.apply args, callback unless state.fulfilled?
1279
+ end
1280
+
1281
+ def callback_on_resolution(state, args, callback)
1282
+ callback.call(*state.result, *args)
1283
+ end
1284
+
1285
+ end
1286
+
1287
+ # Marker module of Future, Event resolved manually.
1288
+ module Resolvable
1289
+ include InternalStates
1290
+ end
1291
+
1292
+ # A Event which can be resolved by user.
1293
+ class ResolvableEvent < Event
1294
+ include Resolvable
1295
+
1296
+ # @!macro raise_on_reassign
1297
+ # @raise [MultipleAssignmentError] when already resolved and raise_on_reassign is true.
1298
+
1299
+ # @!macro promise.param.raise_on_reassign
1300
+ # @param [Boolean] raise_on_reassign should method raise exception if already resolved
1301
+ # @return [self, false] false is returner when raise_on_reassign is false and the receiver
1302
+ # is already resolved.
1303
+ #
1304
+
1305
+ # Makes the event resolved, which triggers all dependent futures.
1306
+ #
1307
+ # @!macro promise.param.raise_on_reassign
1308
+ # @!macro promise.param.reserved
1309
+ # @param [true, false] reserved
1310
+ # Set to true if the resolvable is {#reserve}d by you,
1311
+ # marks resolution of reserved resolvable events and futures explicitly.
1312
+ # Advanced feature, ignore unless you use {Resolvable#reserve} from edge.
1313
+ def resolve(raise_on_reassign = true, reserved = false)
1314
+ resolve_with RESOLVED, raise_on_reassign, reserved
1315
+ end
1316
+
1317
+ # Creates new event wrapping receiver, effectively hiding the resolve method.
1318
+ #
1319
+ # @return [Event]
1320
+ def with_hidden_resolvable
1321
+ @with_hidden_resolvable ||= EventWrapperPromise.new_blocked_by1(self, @DefaultExecutor).event
1322
+ end
1323
+
1324
+ # Behaves as {AbstractEventFuture#wait} but has one additional optional argument
1325
+ # resolve_on_timeout.
1326
+ #
1327
+ # @param [true, false] resolve_on_timeout
1328
+ # If it times out and the argument is true it will also resolve the event.
1329
+ # @return [self, true, false]
1330
+ # @see AbstractEventFuture#wait
1331
+ def wait(timeout = nil, resolve_on_timeout = false)
1332
+ super(timeout) or if resolve_on_timeout
1333
+ # if it fails to resolve it was resolved in the meantime
1334
+ # so return true as if there was no timeout
1335
+ !resolve(false)
1336
+ else
1337
+ false
1338
+ end
1339
+ end
1340
+ end
1341
+
1342
+ # A Future which can be resolved by user.
1343
+ class ResolvableFuture < Future
1344
+ include Resolvable
1345
+
1346
+ # Makes the future resolved with result of triplet `fulfilled?`, `value`, `reason`,
1347
+ # which triggers all dependent futures.
1348
+ #
1349
+ # @param [true, false] fulfilled
1350
+ # @param [Object] value
1351
+ # @param [Object] reason
1352
+ # @!macro promise.param.raise_on_reassign
1353
+ # @!macro promise.param.reserved
1354
+ def resolve(fulfilled = true, value = nil, reason = nil, raise_on_reassign = true, reserved = false)
1355
+ resolve_with(fulfilled ? Fulfilled.new(value) : Rejected.new(reason), raise_on_reassign, reserved)
1356
+ end
1357
+
1358
+ # Makes the future fulfilled with `value`,
1359
+ # which triggers all dependent futures.
1360
+ #
1361
+ # @param [Object] value
1362
+ # @!macro promise.param.raise_on_reassign
1363
+ # @!macro promise.param.reserved
1364
+ def fulfill(value, raise_on_reassign = true, reserved = false)
1365
+ resolve_with Fulfilled.new(value), raise_on_reassign, reserved
1366
+ end
1367
+
1368
+ # Makes the future rejected with `reason`,
1369
+ # which triggers all dependent futures.
1370
+ #
1371
+ # @param [Object] reason
1372
+ # @!macro promise.param.raise_on_reassign
1373
+ # @!macro promise.param.reserved
1374
+ def reject(reason, raise_on_reassign = true, reserved = false)
1375
+ resolve_with Rejected.new(reason), raise_on_reassign, reserved
1376
+ end
1377
+
1378
+ # Evaluates the block and sets its result as future's value fulfilling, if the block raises
1379
+ # an exception the future rejects with it.
1380
+ #
1381
+ # @yield [*args] to the block.
1382
+ # @yieldreturn [Object] value
1383
+ # @return [self]
1384
+ def evaluate_to(*args, &block)
1385
+ promise.evaluate_to(*args, block)
1386
+ end
1387
+
1388
+ # Evaluates the block and sets its result as future's value fulfilling, if the block raises
1389
+ # an exception the future rejects with it.
1390
+ #
1391
+ # @yield [*args] to the block.
1392
+ # @yieldreturn [Object] value
1393
+ # @return [self]
1394
+ # @raise [Exception] also raise reason on rejection.
1395
+ def evaluate_to!(*args, &block)
1396
+ promise.evaluate_to(*args, block).wait!
1397
+ end
1398
+
1399
+ # @!macro promises.resolvable.resolve_on_timeout
1400
+ # @param [::Array(true, Object, nil), ::Array(false, nil, Exception), nil] resolve_on_timeout
1401
+ # If it times out and the argument is not nil it will also resolve the future
1402
+ # to the provided resolution.
1403
+
1404
+ # Behaves as {AbstractEventFuture#wait} but has one additional optional argument
1405
+ # resolve_on_timeout.
1406
+ #
1407
+ # @!macro promises.resolvable.resolve_on_timeout
1408
+ # @return [self, true, false]
1409
+ # @see AbstractEventFuture#wait
1410
+ def wait(timeout = nil, resolve_on_timeout = nil)
1411
+ super(timeout) or if resolve_on_timeout
1412
+ # if it fails to resolve it was resolved in the meantime
1413
+ # so return true as if there was no timeout
1414
+ !resolve(*resolve_on_timeout, false)
1415
+ else
1416
+ false
1417
+ end
1418
+ end
1419
+
1420
+ # Behaves as {Future#wait!} but has one additional optional argument
1421
+ # resolve_on_timeout.
1422
+ #
1423
+ # @!macro promises.resolvable.resolve_on_timeout
1424
+ # @return [self, true, false]
1425
+ # @raise [Exception] {#reason} on rejection
1426
+ # @see Future#wait!
1427
+ def wait!(timeout = nil, resolve_on_timeout = nil)
1428
+ super(timeout) or if resolve_on_timeout
1429
+ if resolve(*resolve_on_timeout, false)
1430
+ false
1431
+ else
1432
+ # if it fails to resolve it was resolved in the meantime
1433
+ # so return true as if there was no timeout
1434
+ raise self if rejected?
1435
+ true
1436
+ end
1437
+ else
1438
+ false
1439
+ end
1440
+ end
1441
+
1442
+ # Behaves as {Future#value} but has one additional optional argument
1443
+ # resolve_on_timeout.
1444
+ #
1445
+ # @!macro promises.resolvable.resolve_on_timeout
1446
+ # @return [Object, timeout_value, nil]
1447
+ # @see Future#value
1448
+ def value(timeout = nil, timeout_value = nil, resolve_on_timeout = nil)
1449
+ if wait_until_resolved timeout
1450
+ internal_state.value
1451
+ else
1452
+ if resolve_on_timeout
1453
+ unless resolve(*resolve_on_timeout, false)
1454
+ # if it fails to resolve it was resolved in the meantime
1455
+ # so return value as if there was no timeout
1456
+ return internal_state.value
1457
+ end
1458
+ end
1459
+ timeout_value
1460
+ end
1461
+ end
1462
+
1463
+ # Behaves as {Future#value!} but has one additional optional argument
1464
+ # resolve_on_timeout.
1465
+ #
1466
+ # @!macro promises.resolvable.resolve_on_timeout
1467
+ # @return [Object, timeout_value, nil]
1468
+ # @raise [Exception] {#reason} on rejection
1469
+ # @see Future#value!
1470
+ def value!(timeout = nil, timeout_value = nil, resolve_on_timeout = nil)
1471
+ if wait_until_resolved! timeout
1472
+ internal_state.value
1473
+ else
1474
+ if resolve_on_timeout
1475
+ unless resolve(*resolve_on_timeout, false)
1476
+ # if it fails to resolve it was resolved in the meantime
1477
+ # so return value as if there was no timeout
1478
+ raise self if rejected?
1479
+ return internal_state.value
1480
+ end
1481
+ end
1482
+ timeout_value
1483
+ end
1484
+ end
1485
+
1486
+ # Behaves as {Future#reason} but has one additional optional argument
1487
+ # resolve_on_timeout.
1488
+ #
1489
+ # @!macro promises.resolvable.resolve_on_timeout
1490
+ # @return [Exception, timeout_value, nil]
1491
+ # @see Future#reason
1492
+ def reason(timeout = nil, timeout_value = nil, resolve_on_timeout = nil)
1493
+ if wait_until_resolved timeout
1494
+ internal_state.reason
1495
+ else
1496
+ if resolve_on_timeout
1497
+ unless resolve(*resolve_on_timeout, false)
1498
+ # if it fails to resolve it was resolved in the meantime
1499
+ # so return value as if there was no timeout
1500
+ return internal_state.reason
1501
+ end
1502
+ end
1503
+ timeout_value
1504
+ end
1505
+ end
1506
+
1507
+ # Behaves as {Future#result} but has one additional optional argument
1508
+ # resolve_on_timeout.
1509
+ #
1510
+ # @!macro promises.resolvable.resolve_on_timeout
1511
+ # @return [::Array(Boolean, Object, Exception), nil]
1512
+ # @see Future#result
1513
+ def result(timeout = nil, resolve_on_timeout = nil)
1514
+ if wait_until_resolved timeout
1515
+ internal_state.result
1516
+ else
1517
+ if resolve_on_timeout
1518
+ unless resolve(*resolve_on_timeout, false)
1519
+ # if it fails to resolve it was resolved in the meantime
1520
+ # so return value as if there was no timeout
1521
+ internal_state.result
1522
+ end
1523
+ end
1524
+ # otherwise returns nil
1525
+ end
1526
+ end
1527
+
1528
+ # Creates new future wrapping receiver, effectively hiding the resolve method and similar.
1529
+ #
1530
+ # @return [Future]
1531
+ def with_hidden_resolvable
1532
+ @with_hidden_resolvable ||= FutureWrapperPromise.new_blocked_by1(self, @DefaultExecutor).future
1533
+ end
1534
+ end
1535
+
1536
+ # @abstract
1537
+ # @private
1538
+ class AbstractPromise < Synchronization::Object
1539
+ safe_initialization!
1540
+ include InternalStates
1541
+
1542
+ def initialize(future)
1543
+ super()
1544
+ @Future = future
1545
+ end
1546
+
1547
+ def future
1548
+ @Future
1549
+ end
1550
+
1551
+ alias_method :event, :future
1552
+
1553
+ def default_executor
1554
+ future.default_executor
1555
+ end
1556
+
1557
+ def state
1558
+ future.state
1559
+ end
1560
+
1561
+ def touch
1562
+ end
1563
+
1564
+ def to_s
1565
+ format '%s %s>', super[0..-2], @Future
1566
+ end
1567
+
1568
+ alias_method :inspect, :to_s
1569
+
1570
+ def delayed_because
1571
+ nil
1572
+ end
1573
+
1574
+ private
1575
+
1576
+ def resolve_with(new_state, raise_on_reassign = true)
1577
+ @Future.resolve_with(new_state, raise_on_reassign)
1578
+ end
1579
+
1580
+ # @return [Future]
1581
+ def evaluate_to(*args, block)
1582
+ resolve_with Fulfilled.new(block.call(*args))
1583
+ rescue Exception => error
1584
+ resolve_with Rejected.new(error)
1585
+ raise error unless error.is_a?(StandardError)
1586
+ end
1587
+ end
1588
+
1589
+ class ResolvableEventPromise < AbstractPromise
1590
+ def initialize(default_executor)
1591
+ super ResolvableEvent.new(self, default_executor)
1592
+ end
1593
+ end
1594
+
1595
+ class ResolvableFuturePromise < AbstractPromise
1596
+ def initialize(default_executor)
1597
+ super ResolvableFuture.new(self, default_executor)
1598
+ end
1599
+
1600
+ public :evaluate_to
1601
+ end
1602
+
1603
+ # @abstract
1604
+ class InnerPromise < AbstractPromise
1605
+ end
1606
+
1607
+ # @abstract
1608
+ class BlockedPromise < InnerPromise
1609
+
1610
+ private_class_method :new
1611
+
1612
+ def self.new_blocked_by1(blocker, *args, &block)
1613
+ blocker_delayed = blocker.promise.delayed_because
1614
+ promise = new(blocker_delayed, 1, *args, &block)
1615
+ blocker.add_callback_notify_blocked promise, 0
1616
+ promise
1617
+ end
1618
+
1619
+ def self.new_blocked_by2(blocker1, blocker2, *args, &block)
1620
+ blocker_delayed1 = blocker1.promise.delayed_because
1621
+ blocker_delayed2 = blocker2.promise.delayed_because
1622
+ delayed = if blocker_delayed1 && blocker_delayed2
1623
+ # TODO (pitr-ch 23-Dec-2016): use arrays when we know it will not grow (only flat adds delay)
1624
+ LockFreeStack.of2(blocker_delayed1, blocker_delayed2)
1625
+ else
1626
+ blocker_delayed1 || blocker_delayed2
1627
+ end
1628
+ promise = new(delayed, 2, *args, &block)
1629
+ blocker1.add_callback_notify_blocked promise, 0
1630
+ blocker2.add_callback_notify_blocked promise, 1
1631
+ promise
1632
+ end
1633
+
1634
+ def self.new_blocked_by(blockers, *args, &block)
1635
+ delayed = blockers.reduce(nil) { |d, f| add_delayed d, f.promise.delayed_because }
1636
+ promise = new(delayed, blockers.size, *args, &block)
1637
+ blockers.each_with_index { |f, i| f.add_callback_notify_blocked promise, i }
1638
+ promise
1639
+ end
1640
+
1641
+ def self.add_delayed(delayed1, delayed2)
1642
+ if delayed1 && delayed2
1643
+ delayed1.push delayed2
1644
+ delayed1
1645
+ else
1646
+ delayed1 || delayed2
1647
+ end
1648
+ end
1649
+
1650
+ def initialize(delayed, blockers_count, future)
1651
+ super(future)
1652
+ @Delayed = delayed
1653
+ @Countdown = AtomicFixnum.new blockers_count
1654
+ end
1655
+
1656
+ def on_blocker_resolution(future, index)
1657
+ countdown = process_on_blocker_resolution(future, index)
1658
+ resolvable = resolvable?(countdown, future, index)
1659
+
1660
+ on_resolvable(future, index) if resolvable
1661
+ end
1662
+
1663
+ def delayed_because
1664
+ @Delayed
1665
+ end
1666
+
1667
+ def touch
1668
+ clear_and_propagate_touch
1669
+ end
1670
+
1671
+ # for inspection only
1672
+ def blocked_by
1673
+ blocked_by = []
1674
+ ObjectSpace.each_object(AbstractEventFuture) { |o| blocked_by.push o if o.blocks.include? self }
1675
+ blocked_by
1676
+ end
1677
+
1678
+ private
1679
+
1680
+ def clear_and_propagate_touch(stack_or_element = @Delayed)
1681
+ return if stack_or_element.nil?
1682
+
1683
+ if stack_or_element.is_a? LockFreeStack
1684
+ stack_or_element.clear_each { |element| clear_and_propagate_touch element }
1685
+ else
1686
+ stack_or_element.touch unless stack_or_element.nil? # if still present
1687
+ end
1688
+ end
1689
+
1690
+ # @return [true,false] if resolvable
1691
+ def resolvable?(countdown, future, index)
1692
+ countdown.zero?
1693
+ end
1694
+
1695
+ def process_on_blocker_resolution(future, index)
1696
+ @Countdown.decrement
1697
+ end
1698
+
1699
+ def on_resolvable(resolved_future, index)
1700
+ raise NotImplementedError
1701
+ end
1702
+ end
1703
+
1704
+ # @abstract
1705
+ class BlockedTaskPromise < BlockedPromise
1706
+ def initialize(delayed, blockers_count, default_executor, executor, args, &task)
1707
+ raise ArgumentError, 'no block given' unless block_given?
1708
+ super delayed, 1, Future.new(self, default_executor)
1709
+ @Executor = executor
1710
+ @Task = task
1711
+ @Args = args
1712
+ end
1713
+
1714
+ def executor
1715
+ @Executor
1716
+ end
1717
+ end
1718
+
1719
+ class ThenPromise < BlockedTaskPromise
1720
+ private
1721
+
1722
+ def initialize(delayed, blockers_count, default_executor, executor, args, &task)
1723
+ super delayed, blockers_count, default_executor, executor, args, &task
1724
+ end
1725
+
1726
+ def on_resolvable(resolved_future, index)
1727
+ if resolved_future.fulfilled?
1728
+ Concurrent.executor(@Executor).post(resolved_future, @Args, @Task) do |future, args, task|
1729
+ evaluate_to lambda { future.apply args, task }
1730
+ end
1731
+ else
1732
+ resolve_with resolved_future.internal_state
1733
+ end
1734
+ end
1735
+ end
1736
+
1737
+ class RescuePromise < BlockedTaskPromise
1738
+ private
1739
+
1740
+ def initialize(delayed, blockers_count, default_executor, executor, args, &task)
1741
+ super delayed, blockers_count, default_executor, executor, args, &task
1742
+ end
1743
+
1744
+ def on_resolvable(resolved_future, index)
1745
+ if resolved_future.rejected?
1746
+ Concurrent.executor(@Executor).post(resolved_future, @Args, @Task) do |future, args, task|
1747
+ evaluate_to lambda { future.apply args, task }
1748
+ end
1749
+ else
1750
+ resolve_with resolved_future.internal_state
1751
+ end
1752
+ end
1753
+ end
1754
+
1755
+ class ChainPromise < BlockedTaskPromise
1756
+ private
1757
+
1758
+ def on_resolvable(resolved_future, index)
1759
+ if Future === resolved_future
1760
+ Concurrent.executor(@Executor).post(resolved_future, @Args, @Task) do |future, args, task|
1761
+ evaluate_to(*future.result, *args, task)
1762
+ end
1763
+ else
1764
+ Concurrent.executor(@Executor).post(@Args, @Task) do |args, task|
1765
+ evaluate_to(*args, task)
1766
+ end
1767
+ end
1768
+ end
1769
+ end
1770
+
1771
+ # will be immediately resolved
1772
+ class ImmediateEventPromise < InnerPromise
1773
+ def initialize(default_executor)
1774
+ super Event.new(self, default_executor).resolve_with(RESOLVED)
1775
+ end
1776
+ end
1777
+
1778
+ class ImmediateFuturePromise < InnerPromise
1779
+ def initialize(default_executor, fulfilled, value, reason)
1780
+ super Future.new(self, default_executor).
1781
+ resolve_with(fulfilled ? Fulfilled.new(value) : Rejected.new(reason))
1782
+ end
1783
+ end
1784
+
1785
+ class AbstractFlatPromise < BlockedPromise
1786
+
1787
+ def initialize(delayed_because, blockers_count, event_or_future)
1788
+ delayed = LockFreeStack.of1(self)
1789
+ super(delayed, blockers_count, event_or_future)
1790
+ # noinspection RubyArgCount
1791
+ @Touched = AtomicBoolean.new false
1792
+ @DelayedBecause = delayed_because || LockFreeStack.new
1793
+
1794
+ event_or_future.add_callback_clear_delayed_node delayed.peek
1795
+ end
1796
+
1797
+ def touch
1798
+ if @Touched.make_true
1799
+ clear_and_propagate_touch @DelayedBecause
1800
+ end
1801
+ end
1802
+
1803
+ private
1804
+
1805
+ def touched?
1806
+ @Touched.value
1807
+ end
1808
+
1809
+ def on_resolvable(resolved_future, index)
1810
+ resolve_with resolved_future.internal_state
1811
+ end
1812
+
1813
+ def resolvable?(countdown, future, index)
1814
+ !@Future.internal_state.resolved? && super(countdown, future, index)
1815
+ end
1816
+
1817
+ def add_delayed_of(future)
1818
+ delayed = future.promise.delayed_because
1819
+ if touched?
1820
+ clear_and_propagate_touch delayed
1821
+ else
1822
+ BlockedPromise.add_delayed @DelayedBecause, delayed
1823
+ clear_and_propagate_touch @DelayedBecause if touched?
1824
+ end
1825
+ end
1826
+
1827
+ end
1828
+
1829
+ class FlatEventPromise < AbstractFlatPromise
1830
+
1831
+ private
1832
+
1833
+ def initialize(delayed, blockers_count, default_executor)
1834
+ super delayed, 2, Event.new(self, default_executor)
1835
+ end
1836
+
1837
+ def process_on_blocker_resolution(future, index)
1838
+ countdown = super(future, index)
1839
+ if countdown.nonzero?
1840
+ internal_state = future.internal_state
1841
+
1842
+ unless internal_state.fulfilled?
1843
+ resolve_with RESOLVED
1844
+ return countdown
1845
+ end
1846
+
1847
+ value = internal_state.value
1848
+ case value
1849
+ when AbstractEventFuture
1850
+ add_delayed_of value
1851
+ value.add_callback_notify_blocked self, nil
1852
+ countdown
1853
+ else
1854
+ resolve_with RESOLVED
1855
+ end
1856
+ end
1857
+ countdown
1858
+ end
1859
+
1860
+ end
1861
+
1862
+ class FlatFuturePromise < AbstractFlatPromise
1863
+
1864
+ private
1865
+
1866
+ def initialize(delayed, blockers_count, levels, default_executor)
1867
+ raise ArgumentError, 'levels has to be higher than 0' if levels < 1
1868
+ # flat promise may result to a future having delayed futures, therefore we have to have empty stack
1869
+ # to be able to add new delayed futures
1870
+ super delayed || LockFreeStack.new, 1 + levels, Future.new(self, default_executor)
1871
+ end
1872
+
1873
+ def process_on_blocker_resolution(future, index)
1874
+ countdown = super(future, index)
1875
+ if countdown.nonzero?
1876
+ internal_state = future.internal_state
1877
+
1878
+ unless internal_state.fulfilled?
1879
+ resolve_with internal_state
1880
+ return countdown
1881
+ end
1882
+
1883
+ value = internal_state.value
1884
+ case value
1885
+ when AbstractEventFuture
1886
+ add_delayed_of value
1887
+ value.add_callback_notify_blocked self, nil
1888
+ countdown
1889
+ else
1890
+ evaluate_to(lambda { raise TypeError, "returned value #{value.inspect} is not a Future" })
1891
+ end
1892
+ end
1893
+ countdown
1894
+ end
1895
+
1896
+ end
1897
+
1898
+ class RunFuturePromise < AbstractFlatPromise
1899
+
1900
+ private
1901
+
1902
+ def initialize(delayed, blockers_count, default_executor, run_test)
1903
+ super delayed, 1, Future.new(self, default_executor)
1904
+ @RunTest = run_test
1905
+ end
1906
+
1907
+ def process_on_blocker_resolution(future, index)
1908
+ internal_state = future.internal_state
1909
+
1910
+ unless internal_state.fulfilled?
1911
+ resolve_with internal_state
1912
+ return 0
1913
+ end
1914
+
1915
+ value = internal_state.value
1916
+ continuation_future = @RunTest.call value
1917
+
1918
+ if continuation_future
1919
+ add_delayed_of continuation_future
1920
+ continuation_future.add_callback_notify_blocked self, nil
1921
+ else
1922
+ resolve_with internal_state
1923
+ end
1924
+
1925
+ 1
1926
+ end
1927
+ end
1928
+
1929
+ class ZipEventEventPromise < BlockedPromise
1930
+ def initialize(delayed, blockers_count, default_executor)
1931
+ super delayed, 2, Event.new(self, default_executor)
1932
+ end
1933
+
1934
+ private
1935
+
1936
+ def on_resolvable(resolved_future, index)
1937
+ resolve_with RESOLVED
1938
+ end
1939
+ end
1940
+
1941
+ class ZipFutureEventPromise < BlockedPromise
1942
+ def initialize(delayed, blockers_count, default_executor)
1943
+ super delayed, 2, Future.new(self, default_executor)
1944
+ @result = nil
1945
+ end
1946
+
1947
+ private
1948
+
1949
+ def process_on_blocker_resolution(future, index)
1950
+ # first blocking is future, take its result
1951
+ @result = future.internal_state if index == 0
1952
+ # super has to be called after above to piggyback on volatile @Countdown
1953
+ super future, index
1954
+ end
1955
+
1956
+ def on_resolvable(resolved_future, index)
1957
+ resolve_with @result
1958
+ end
1959
+ end
1960
+
1961
+ class EventWrapperPromise < BlockedPromise
1962
+ def initialize(delayed, blockers_count, default_executor)
1963
+ super delayed, 1, Event.new(self, default_executor)
1964
+ end
1965
+
1966
+ private
1967
+
1968
+ def on_resolvable(resolved_future, index)
1969
+ resolve_with RESOLVED
1970
+ end
1971
+ end
1972
+
1973
+ class FutureWrapperPromise < BlockedPromise
1974
+ def initialize(delayed, blockers_count, default_executor)
1975
+ super delayed, 1, Future.new(self, default_executor)
1976
+ end
1977
+
1978
+ private
1979
+
1980
+ def on_resolvable(resolved_future, index)
1981
+ resolve_with resolved_future.internal_state
1982
+ end
1983
+ end
1984
+
1985
+ class ZipFuturesPromise < BlockedPromise
1986
+
1987
+ private
1988
+
1989
+ def initialize(delayed, blockers_count, default_executor)
1990
+ super(delayed, blockers_count, Future.new(self, default_executor))
1991
+ @Resolutions = ::Array.new(blockers_count, nil)
1992
+
1993
+ on_resolvable nil, nil if blockers_count == 0
1994
+ end
1995
+
1996
+ def process_on_blocker_resolution(future, index)
1997
+ # TODO (pitr-ch 18-Dec-2016): Can we assume that array will never break under parallel access when never re-sized?
1998
+ @Resolutions[index] = future.internal_state # has to be set before countdown in super
1999
+ super future, index
2000
+ end
2001
+
2002
+ def on_resolvable(resolved_future, index)
2003
+ all_fulfilled = true
2004
+ values = ::Array.new(@Resolutions.size)
2005
+ reasons = ::Array.new(@Resolutions.size)
2006
+
2007
+ @Resolutions.each_with_index do |internal_state, i|
2008
+ fulfilled, values[i], reasons[i] = internal_state.result
2009
+ all_fulfilled &&= fulfilled
2010
+ end
2011
+
2012
+ if all_fulfilled
2013
+ resolve_with FulfilledArray.new(values)
2014
+ else
2015
+ resolve_with PartiallyRejected.new(values, reasons)
2016
+ end
2017
+ end
2018
+ end
2019
+
2020
+ class ZipEventsPromise < BlockedPromise
2021
+
2022
+ private
2023
+
2024
+ def initialize(delayed, blockers_count, default_executor)
2025
+ super delayed, blockers_count, Event.new(self, default_executor)
2026
+
2027
+ on_resolvable nil, nil if blockers_count == 0
2028
+ end
2029
+
2030
+ def on_resolvable(resolved_future, index)
2031
+ resolve_with RESOLVED
2032
+ end
2033
+ end
2034
+
2035
+ # @abstract
2036
+ class AbstractAnyPromise < BlockedPromise
2037
+ end
2038
+
2039
+ class AnyResolvedEventPromise < AbstractAnyPromise
2040
+
2041
+ private
2042
+
2043
+ def initialize(delayed, blockers_count, default_executor)
2044
+ super delayed, blockers_count, Event.new(self, default_executor)
2045
+ end
2046
+
2047
+ def resolvable?(countdown, future, index)
2048
+ true
2049
+ end
2050
+
2051
+ def on_resolvable(resolved_future, index)
2052
+ resolve_with RESOLVED, false
2053
+ end
2054
+ end
2055
+
2056
+ class AnyResolvedFuturePromise < AbstractAnyPromise
2057
+
2058
+ private
2059
+
2060
+ def initialize(delayed, blockers_count, default_executor)
2061
+ super delayed, blockers_count, Future.new(self, default_executor)
2062
+ end
2063
+
2064
+ def resolvable?(countdown, future, index)
2065
+ true
2066
+ end
2067
+
2068
+ def on_resolvable(resolved_future, index)
2069
+ resolve_with resolved_future.internal_state, false
2070
+ end
2071
+ end
2072
+
2073
+ class AnyFulfilledFuturePromise < AnyResolvedFuturePromise
2074
+
2075
+ private
2076
+
2077
+ def resolvable?(countdown, future, index)
2078
+ future.fulfilled? ||
2079
+ # inlined super from BlockedPromise
2080
+ countdown.zero?
2081
+ end
2082
+ end
2083
+
2084
+ class DelayPromise < InnerPromise
2085
+
2086
+ def initialize(default_executor)
2087
+ event = Event.new(self, default_executor)
2088
+ @Delayed = LockFreeStack.of1(self)
2089
+ super event
2090
+ event.add_callback_clear_delayed_node @Delayed.peek
2091
+ end
2092
+
2093
+ def touch
2094
+ @Future.resolve_with RESOLVED
2095
+ end
2096
+
2097
+ def delayed_because
2098
+ @Delayed
2099
+ end
2100
+
2101
+ end
2102
+
2103
+ class ScheduledPromise < InnerPromise
2104
+ def intended_time
2105
+ @IntendedTime
2106
+ end
2107
+
2108
+ def inspect
2109
+ "#{to_s[0..-2]} intended_time: #{@IntendedTime}>"
2110
+ end
2111
+
2112
+ private
2113
+
2114
+ def initialize(default_executor, intended_time)
2115
+ super Event.new(self, default_executor)
2116
+
2117
+ @IntendedTime = intended_time
2118
+
2119
+ in_seconds = begin
2120
+ now = Time.now
2121
+ schedule_time = if @IntendedTime.is_a? Time
2122
+ @IntendedTime
2123
+ else
2124
+ now + @IntendedTime
2125
+ end
2126
+ [0, schedule_time.to_f - now.to_f].max
2127
+ end
2128
+
2129
+ Concurrent.global_timer_set.post(in_seconds) do
2130
+ @Future.resolve_with RESOLVED
2131
+ end
2132
+ end
2133
+ end
2134
+
2135
+ extend FactoryMethods
2136
+
2137
+ private_constant :AbstractPromise,
2138
+ :ResolvableEventPromise,
2139
+ :ResolvableFuturePromise,
2140
+ :InnerPromise,
2141
+ :BlockedPromise,
2142
+ :BlockedTaskPromise,
2143
+ :ThenPromise,
2144
+ :RescuePromise,
2145
+ :ChainPromise,
2146
+ :ImmediateEventPromise,
2147
+ :ImmediateFuturePromise,
2148
+ :AbstractFlatPromise,
2149
+ :FlatFuturePromise,
2150
+ :FlatEventPromise,
2151
+ :RunFuturePromise,
2152
+ :ZipEventEventPromise,
2153
+ :ZipFutureEventPromise,
2154
+ :EventWrapperPromise,
2155
+ :FutureWrapperPromise,
2156
+ :ZipFuturesPromise,
2157
+ :ZipEventsPromise,
2158
+ :AbstractAnyPromise,
2159
+ :AnyResolvedFuturePromise,
2160
+ :AnyFulfilledFuturePromise,
2161
+ :AnyResolvedEventPromise,
2162
+ :DelayPromise,
2163
+ :ScheduledPromise
2164
+
2165
+
2166
+ end
2167
+ end