Class: Concurrent::Promises::Future

Inherits:
AbstractEventFuture
  • Object
show all
Defined in:
lib/concurrent-ruby/concurrent/promises.rb

Overview

Represents a value which will become available in future. May reject with a reason instead, e.g. when the tasks raises an exception.

Direct Known Subclasses

ResolvableFuture

Instance Method Summary collapse

Methods inherited from AbstractEventFuture

#chain, #chain_on, #chain_resolvable, #default_executor, #internal_state, #on_resolution, #on_resolution!, #on_resolution_using, #pending?, #resolved?, #state, #touch, #wait

Instance Method Details

#any(event_or_future) ⇒ Future Also known as: |

Creates a new event which will be resolved when the first of receiver, ‘event_or_future` resolves. Returning future will have value nil if event_or_future is event and resolves first.

Returns:



1085
1086
1087
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1085

def any(event_or_future)
  AnyResolvedFuturePromise.new_blocked_by2(self, event_or_future, @DefaultExecutor).future
end

#delay ⇒ Future

Creates new future dependent on receiver which will not evaluate until touched, see AbstractEventFuture#touch. In other words, it inserts delay into the chain of Futures making rest of it lazy evaluated.

Returns:



1095
1096
1097
1098
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1095

def delay
  event = DelayPromise.new(@DefaultExecutor).event
  ZipFutureEventPromise.new_blocked_by2(self, event, @DefaultExecutor).future
end

#exception(*args) ⇒ Exception

Allows rejected Future to be risen with ‘raise` method. If the reason is not an exception `Runtime.new(reason)` is returned.

Examples:

raise Promises.rejected_future(StandardError.new("boom"))
raise Promises.rejected_future("or just boom")

Returns:

  • (Exception)

Raises:



1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1013

def exception(*args)
  raise Concurrent::Error, 'it is not rejected' unless rejected?
  raise ArgumentError unless args.size <= 1
  reason = Array(internal_state.reason).flatten.compact
  if reason.size > 1
    ex = Concurrent::MultipleErrors.new reason
    ex.set_backtrace(caller)
    ex
  else
    ex = if reason[0].respond_to? :exception
           reason[0].exception(*args)
         else
           RuntimeError.new(reason[0]).exception(*args)
         end
    ex.set_backtrace Array(ex.backtrace) + caller
    ex
  end
end

#flat_event ⇒ Event

Creates new event which will be resolved when the returned event by receiver is. Be careful if the receiver rejects it will just resolve since Event does not hold reason.

Returns:



1130
1131
1132
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1130

def flat_event
  FlatEventPromise.new_blocked_by1(self, @DefaultExecutor).event
end

#flat_future(level = 1) ⇒ Future Also known as: flat

Creates new future which will have result of the future returned by receiver. If receiver rejects it will have its rejection.

Parameters:

  • level (Integer) (defaults to: 1) —

    how many levels of futures should flatten

Returns:



1120
1121
1122
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1120

def flat_future(level = 1)
  FlatFuturePromise.new_blocked_by1(self, level, @DefaultExecutor).future
end

#fulfilled? ⇒ Boolean

Is it in fulfilled state?

Returns:

  • (Boolean) 


921
922
923
924
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 921

def fulfilled?
  state = internal_state
  state.resolved? && state.fulfilled?
end

#on_fulfillment(*args, &callback) ⇒ self

Shortcut of #on_fulfillment_using with default ‘:io` executor supplied.

Returns:

  • (self)

See Also:



1136
1137
1138
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1136

def on_fulfillment(*args, &callback)
  on_fulfillment_using @DefaultExecutor, *args, &callback
end

#on_fulfillment!(*args) {|value, *args| ... } ⇒ self

Stores the callback to be executed synchronously on resolving thread after it is fulfilled. Does nothing on rejection.

Parameters:

  • args (Object) —

    arguments which are passed to the task when it’s executed. (It might be prepended with other arguments, see the @yield section).

Yields:

  • (value, *args) —

    to the callback.

Yield Returns:

  • is forgotten.

Returns:

  • (self) 


1147
1148
1149
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1147

def on_fulfillment!(*args, &callback)
  add_callback :callback_on_fulfillment, args, callback
end

#on_fulfillment_using(executor, *args) {|value, *args| ... } ⇒ self

Stores the callback to be executed asynchronously on executor after it is fulfilled. Does nothing on rejection.

Parameters:

  • executor (Executor, :io, :fast) —

    Instance of an executor or a name of the global executor. The task is executed on it, default executor remains unchanged.

  • args (Object) —

    arguments which are passed to the task when it’s executed. (It might be prepended with other arguments, see the @yield section).

Yields:

  • (value, *args) —

    to the callback.

Yield Returns:

  • is forgotten.

Returns:

  • (self) 


1159
1160
1161
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1159

def on_fulfillment_using(executor, *args, &callback)
  add_callback :async_callback_on_fulfillment, executor, args, callback
end

#on_rejection(*args, &callback) ⇒ self

Shortcut of #on_rejection_using with default ‘:io` executor supplied.

Returns:

  • (self)

See Also:



1165
1166
1167
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1165

def on_rejection(*args, &callback)
  on_rejection_using @DefaultExecutor, *args, &callback
end

#on_rejection!(*args) {|reason, *args| ... } ⇒ self

Stores the callback to be executed synchronously on resolving thread after it is rejected. Does nothing on fulfillment.

Parameters:

  • args (Object) —

    arguments which are passed to the task when it’s executed. (It might be prepended with other arguments, see the @yield section).

Yields:

  • (reason, *args) —

    to the callback.

Yield Returns:

  • is forgotten.

Returns:

  • (self) 


1176
1177
1178
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1176

def on_rejection!(*args, &callback)
  add_callback :callback_on_rejection, args, callback
end

#on_rejection_using(executor, *args) {|reason, *args| ... } ⇒ self

Stores the callback to be executed asynchronously on executor after it is rejected. Does nothing on fulfillment.

Parameters:

  • executor (Executor, :io, :fast) —

    Instance of an executor or a name of the global executor. The task is executed on it, default executor remains unchanged.

  • args (Object) —

    arguments which are passed to the task when it’s executed. (It might be prepended with other arguments, see the @yield section).

Yields:

  • (reason, *args) —

    to the callback.

Yield Returns:

  • is forgotten.

Returns:

  • (self) 


1188
1189
1190
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1188

def on_rejection_using(executor, *args, &callback)
  add_callback :async_callback_on_rejection, executor, args, callback
end

#reason(timeout = nil, timeout_value = nil) ⇒ Object, timeout_value

Note:

This function potentially blocks current thread until the Future is resolved. Be careful it can deadlock. Try to chain instead.

Note:

Make sure returned ‘nil` is not confused with timeout, no value when rejected, no reason when fulfilled, etc. Use more exact methods if needed, like AbstractEventFuture#wait, #value!, #result, etc.

Returns reason of future’s rejection. Calls AbstractEventFuture#touch.

Parameters:

  • timeout (Numeric) (defaults to: nil) —

    the maximum time in second to wait.

  • timeout_value (Object) (defaults to: nil) —

    a value returned by the method when it times out

Returns:

  • (Object, timeout_value) —

    the reason, or timeout_value on timeout, or nil on fulfillment.



966
967
968
969
970
971
972
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 966

def reason(timeout = nil, timeout_value = nil)
  if wait_until_resolved timeout
    internal_state.reason
  else
    timeout_value
  end
end

#rejected? ⇒ Boolean

Is it in rejected state?

Returns:

  • (Boolean) 


928
929
930
931
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 928

def rejected?
  state = internal_state
  state.resolved? && !state.fulfilled?
end

#rescue(*args, &task) ⇒ Future

Shortcut of #rescue_on with default ‘:io` executor supplied.

Returns:

See Also:



1052
1053
1054
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1052

def rescue(*args, &task)
  rescue_on @DefaultExecutor, *args, &task
end

#rescue_on(executor, *args) {|reason, *args| ... } ⇒ Future

Chains the task to be executed asynchronously on executor after it rejects. Does not run the task if it fulfills. It will resolve though, triggering any dependent futures.

Parameters:

  • executor (Executor, :io, :fast) —

    Instance of an executor or a name of the global executor. The task is executed on it, default executor remains unchanged.

  • args (Object) —

    arguments which are passed to the task when it’s executed. (It might be prepended with other arguments, see the @yield section).

Yields:

  • (reason, *args) —

    to the task.

Yield Returns:

  • will become result of the returned Future. Its returned value becomes #value fulfilling it, raised exception becomes #reason rejecting it.

Returns:



1064
1065
1066
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1064

def rescue_on(executor, *args, &task)
  RescuePromise.new_blocked_by1(self, executor, executor, args, &task).future
end

#result(timeout = nil) ⇒ Array(Boolean, Object, Object)?

Note:

This function potentially blocks current thread until the Future is resolved. Be careful it can deadlock. Try to chain instead.

Returns triplet fulfilled?, value, reason. Calls AbstractEventFuture#touch.

Parameters:

  • timeout (Numeric) (defaults to: nil) —

    the maximum time in second to wait.

Returns:

  • (Array(Boolean, Object, Object), nil) —

    triplet of fulfilled?, value, reason, or nil on timeout.



981
982
983
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 981

def result(timeout = nil)
  internal_state.result if wait_until_resolved timeout
end

#run(run_test = method(:run_test)) ⇒ Future

Allows to use futures as green threads. The receiver has to evaluate to a future which represents what should be done next. It basically flattens indefinitely until non Future values is returned which becomes result of the returned future. Any encountered exception will become reason of the returned future.

Examples:

body = lambda do |v|
  v += 1
  v < 5 ? Promises.future(v, &body) : v
end
Promises.future(0, &body).run.value! # => 5

Parameters:

  • run_test (#call(value)) (defaults to: method(:run_test)) —

    an object which when called returns either Future to keep running with or nil, then the run completes with the value. The run_test can be used to extract the Future from deeper structure, or to distinguish Future which is a resulting value from a future which is suppose to continue running.

Returns:



1210
1211
1212
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1210

def run(run_test = method(:run_test))
  RunFuturePromise.new_blocked_by1(self, @DefaultExecutor, run_test).future
end

#schedule(intended_time) ⇒ Future

Creates new event dependent on receiver scheduled to execute on/in intended_time. In time is interpreted from the moment the receiver is resolved, therefore it inserts delay into the chain.

Parameters:

  • intended_time (Numeric, Time) —

    ‘Numeric` means to run in `intended_time` seconds. `Time` means to run on `intended_time`.

Returns:



1102
1103
1104
1105
1106
1107
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1102

def schedule(intended_time)
  chain do
    event = ScheduledPromise.new(@DefaultExecutor, intended_time).event
    ZipFutureEventPromise.new_blocked_by2(self, event, @DefaultExecutor).future
  end.flat
end

#then(*args, &task) ⇒ Future

Shortcut of #then_on with default ‘:io` executor supplied.

Returns:

See Also:



1034
1035
1036
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1034

def then(*args, &task)
  then_on @DefaultExecutor, *args, &task
end

#then_on(executor, *args) {|value, *args| ... } ⇒ Future

Chains the task to be executed asynchronously on executor after it fulfills. Does not run the task if it rejects. It will resolve though, triggering any dependent futures.

Parameters:

  • executor (Executor, :io, :fast) —

    Instance of an executor or a name of the global executor. The task is executed on it, default executor remains unchanged.

  • args (Object) —

    arguments which are passed to the task when it’s executed. (It might be prepended with other arguments, see the @yield section).

Yields:

  • (value, *args) —

    to the task.

Yield Returns:

  • will become result of the returned Future. Its returned value becomes #value fulfilling it, raised exception becomes #reason rejecting it.

Returns:



1046
1047
1048
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1046

def then_on(executor, *args, &task)
  ThenPromise.new_blocked_by1(self, executor, executor, args, &task).future
end

#to_event ⇒ Event

Converts future to event which is resolved when future is resolved by fulfillment or rejection.

Returns:



1222
1223
1224
1225
1226
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1222

def to_event
  event = Promises.resolvable_event
ensure
  chain_resolvable(event)
end

#to_future ⇒ Future

Returns self, since this is a future

Returns:



1230
1231
1232
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1230

def to_future
  self
end

#to_s ⇒ String Also known as: inspect

Returns Short string representation.

Returns:

  • (String) —

    Short string representation.



1235
1236
1237
1238
1239
1240
1241
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1235

def to_s
  if resolved?
    format '%s with %s>', super[0..-2], (fulfilled? ? value : reason).inspect
  else
    super
  end
end

#value(timeout = nil, timeout_value = nil) ⇒ Object, ...

Note:

This function potentially blocks current thread until the Future is resolved. Be careful it can deadlock. Try to chain instead.

Note:

Make sure returned ‘nil` is not confused with timeout, no value when rejected, no reason when fulfilled, etc. Use more exact methods if needed, like AbstractEventFuture#wait, #value!, #result, etc.

Return value of the future. Calls AbstractEventFuture#touch.

Parameters:

  • timeout (Numeric) (defaults to: nil) —

    the maximum time in second to wait.

  • timeout_value (Object) (defaults to: nil) —

    a value returned by the method when it times out

Returns:

  • (Object, nil, timeout_value) —

    the value of the Future when fulfilled, timeout_value on timeout, nil on rejection.



950
951
952
953
954
955
956
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 950

def value(timeout = nil, timeout_value = nil)
  if wait_until_resolved timeout
    internal_state.value
  else
    timeout_value
  end
end

#value!(timeout = nil, timeout_value = nil) ⇒ Object, ...

Note:

This function potentially blocks current thread until the Future is resolved. Be careful it can deadlock. Try to chain instead.

Note:

Make sure returned ‘nil` is not confused with timeout, no value when rejected, no reason when fulfilled, etc. Use more exact methods if needed, like AbstractEventFuture#wait, #value!, #result, etc.

Return value of the future. Calls AbstractEventFuture#touch.

Parameters:

  • timeout (Numeric) (defaults to: nil) —

    the maximum time in second to wait.

  • timeout_value (Object) (defaults to: nil) —

    a value returned by the method when it times out

Returns:

  • (Object, nil, timeout_value) —

    the value of the Future when fulfilled, or nil on rejection, or timeout_value on timeout.

Raises:

  • (Exception) —

    #reason on rejection



997
998
999
1000
1001
1002
1003
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 997

def value!(timeout = nil, timeout_value = nil)
  if wait_until_resolved! timeout
    internal_state.value
  else
    timeout_value
  end
end

#wait!(timeout = nil) ⇒ self, ...

Note:

This function potentially blocks current thread until the Future is resolved. Be careful it can deadlock. Try to chain instead.

Wait (block the Thread) until receiver is AbstractEventFuture#resolved?. Calls AbstractEventFuture#touch.

Parameters:

  • timeout (Numeric) (defaults to: nil) —

    the maximum time in second to wait.

Returns:

  • (self, true, false) —

    self implies timeout was not used, true implies timeout was used and it was resolved, false implies it was not resolved within timeout.

Raises:

  • (Exception) —

    #reason on rejection



987
988
989
990
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 987

def wait!(timeout = nil)
  result = wait_until_resolved!(timeout)
  timeout ? result : self
end

#with_default_executor(executor) ⇒ Future

Crates new object with same class with the executor set as its new default executor. Any futures depending on it will use the new default executor.

Returns:



1111
1112
1113
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1111

def with_default_executor(executor)
  FutureWrapperPromise.new_blocked_by1(self, executor).future
end

#zip(other) ⇒ Future Also known as: &

Creates a new event or a future which will be resolved when receiver and other are. Returns an event if receiver and other are events, otherwise returns a future. If just one of the parties is Future then the result of the returned future is equal to the result of the supplied future. If both are futures then the result is as described in Concurrent::Promises::FactoryMethods#zip_futures_on.

Returns:



1070
1071
1072
1073
1074
1075
1076
 
# File 'lib/concurrent-ruby/concurrent/promises.rb', line 1070

def zip(other)
  if other.is_a?(Future)
    ZipFuturesPromise.new_blocked_by2(self, other, @DefaultExecutor).future
  else
    ZipFutureEventPromise.new_blocked_by2(self, other, @DefaultExecutor).future
  end
end