Register a FutureEventListener to be invoked when the computation completes.
Register a FutureEventListener to be invoked when the computation completes. This method is typically used by Java programs because it avoids the use of small Function objects.
Compare this method to transformedBy. The difference is that
addEventListener is used to perform a simple action when a
computation completes, such as recording data in a log-file. It
analogous to a void method in Java: it has side-effects and no
return value. transformedBy, on the other hand, is used to
transform values from one type to another, or to chain a series
of asynchronous calls and return the result. It is analogous to
methods in Java that have a return-type. Note that
transformedBy and addEventListener are not mutually
exclusive and may be profitably combined.
Become the other promise.
Become the other promise. become declares an equivalence
relation: this and other are the same.
By becoming other, its waitlists are now merged into this's,
and this becomes canonical. The same is true of interrupt
handlers: other's interrupt handler becomes active, but is
stored canonically by this - further references are forwarded.
Note that this must be unsatisfied at the time of the call,
and not race with any other setters. become is a form of
satisfying the promise.
This has the combined effect of compressing the other into
this, effectively providing a form of tail-call elimination
when used in recursion constructs. transform (and thus any
other combinator) use this to compress Futures, freeing them
from space leaks when used with recursive constructions.
Note: do not use become with cyclic graphs of futures: the
behavior of racing a.become(b) with b.become(a) is undefined
(where a and b may resolve as such transitively).
Invoked regardless of whether the computation completed successfully or unsuccessfully.
Invoked regardless of whether the computation completed successfully or unsuccessfully.
Implemented in terms of respond so that subclasses control evaluation order. Returns a
chained Future.
If this, the original future, succeeds, run f on the result.
If this, the original future, succeeds, run f on the result.
The returned result is a Future that is satisfied when the original future and the callback, f, are done. If the original future fails, this one will also fail, without executing f.
map()
Converts a Future[Future[B]] into a Future[B]
Converts a Future[Future[B]] into a Future[B]
Invoke the callback only if the Future returns successfully.
Invoke the callback only if the Future returns successfully. Useful for Scala for
comprehensions. Use onSuccess instead of this method for more readable code.
Forward interrupts to another future.
Forward interrupts to another future.
the Future to which interrupts are forwarded.
Is the result of the Future available yet?
Is the result of the Future available yet?
Returns this promise's interrupt if it is interrupted.
Combines two Futures into one Future of the Tuple of the two results.
Combines two Futures into one Future of the Tuple of the two results.
If this, the original future, succeeds, run f on the result.
If this, the original future, succeeds, run f on the result.
The returned result is a Future that is satisfied when the original future and the callback, f, are done. If the original future fails, this one will also fail, without executing f.
flatMap()
Invoke the function on the error, if the computation was unsuccessful.
Invoke the function on the error, if the computation was
unsuccessful. Returns a chained Future as in respond.
chained Future
Invoke the function on the result, if the computation was successful.
Invoke the function on the result, if the computation was
successful. Returns a chained Future as in respond.
chained Future
A synonym for select(): Choose the first Future to succeed.
A synonym for select(): Choose the first Future to succeed.
Polls for an available result.
Send updates from this Future to the other.
Send updates from this Future to the other.
other must not yet be satisfied.
Raise the given throwable as an interrupt.
Raise the given throwable as an interrupt. Interrupts are
one-shot and latest-interrupt wins. That is, the last interrupt
to have been raised is delivered exactly once to the Promise
responsible for making progress on the future (multiple such
promises may be involved in flatMap chains).
Raising an interrupt does not alter the externally observable state of the Future. They are used to signal to the producer of the future's value that the result is no longer desired (for whatever reason given in the passed Throwable).
Support for Await.ready.
Note: exceptions in responds are monitored.
Support for Await.result.
Choose the first Future to succeed.
Choose the first Future to succeed.
another Future
a new Future whose result is that of the first of this and other to return
Populate the Promise with the given exception.
Populate the Promise with the given exception.
if the Promise is already populated
(Re)sets the interrupt handler.
(Re)sets the interrupt handler. There is only one active interrupt handler.
the new interrupt handler
Populate the Promise with the given result.
Populate the Promise with the given result.
if the Promise is already populated
Convert a Twitter Future to a Java native Future.
Convert a Twitter Future to a Java native Future. This should match the semantics of a Java Future as closely as possible to avoid issues with the way another API might use them. See:
http://download.oracle.com/javase/6/docs/api/java/util/concurrent/Future.html#cancel(boolean)
An offer for this future.
An offer for this future. The offer is activated when the future is satisfied.
Transform the Future[A] into a Future[B] using the FutureTransformer.
Transform the Future[A] into a Future[B] using the FutureTransformer. The FutureTransformer handles both success (Return) and failure (Throw) values by implementing map/flatMap and handle/rescue. This method is typically used by Java programs because it avoids the use of small Function objects.
Compare this method to addEventListener. The difference is
that addEventListener is used to perform a simple action when
a computation completes, such as recording data in a log-file.
It analogous to a void method in Java: it has side-effects and
no return value. transformedBy, on the other hand, is used to
transform values from one type to another, or to chain a series
of asynchronous calls and return the result. It is analogous to
methods in Java that have a return-type. Note that
transformedBy and addEventListener are not mutually
exclusive and may be profitably combined.
Note: The FutureTransformer must implement either flatMap
or map and may optionally implement handle. Failing to
implement a method will result in a run-time (AbstractMethod)
error.
Convert this Future[A] to a Future[Unit] by discarding the result.
Convert this Future[A] to a Future[Unit] by discarding the result.
Populate the Promise with the given Try.
Populate the Promise with the given Try. The try can either be a value or an exception. setValue and setException are generally more readable methods to use.
if the Promise is already populated
Populate the Promise with the given Try.
Populate the Promise with the given Try. The try can either be a value or an exception. setValue and setException are generally more readable methods to use.
true only if the result is updated, false if it was already set.
Convert this Future[A] to a Future[Void] by discarding the result.
Convert this Future[A] to a Future[Void] by discarding the result.
Returns a Future[Boolean] indicating whether two Futures are equivalent.
Returns a Future[Boolean] indicating whether two Futures are equivalent. Note that Future.exception(e).willEqual(Future.exception(e)) == Future.value(true).
Returns a new Future that will error if this Future does not return in time.
Returns a new Future that will error if this Future does not return in time.
Note: On timeout, the underlying future is not interrupted.
indicates how long you are willing to wait for the result to be available.
Same as the other within, but with an implicit timer.
Same as the other within, but with an implicit timer. Sometimes this is more convenient.
Block, but only as long as the given Timeout.
Block, but only as long as the given Timeout.
(Since version 6.2.x) Use Await.result
Block indefinitely, wait for the result of the Future to be available.
Block indefinitely, wait for the result of the Future to be available.
(Since version 6.2.x) Use Await.result
(Since version 6.0.0) Provided for API compatibility; use raise() instead.
Demands that the result of the future be available within
timeout.
Demands that the result of the future be available within
timeout. The result is a Return[_] or Throw[_] depending upon
whether the computation finished in time.
(Since version 6.2.x) Use Await.result
Alias for apply().
Alias for apply().
(Since version 6.2.x) Use Await.result
(Since version 6.2.x) Use Await.result
(Since version 6.2.x) Use Await.result
(Since version 5.x) 'void' is a reserved word in javac.
A writeable com.twitter.util.Future that supports merging. Callbacks (responders) of Promises are scheduled with com.twitter.concurrent.Scheduler.
Implementation details
A Promise is in one of five states:
Waiting,Interruptible,Interrupted,DoneandLinkedwhereInterruptibleandInterruptedare variants ofWaitingto deal with future interrupts. Promises are concurrency-safe, using lock-free operations throughout. Callback dispatch is scheduled with com.twitter.concurrent.Scheduler.Waiters are stored as a com.twitter.util.Promise.K.
Ks (mnemonic: continuation) specifies adepth. This is used to implement Promise chaining: a callback with depthdis invoked only after all callbacks with depth <dhave already been invoked.Promise.becomemerges two promises: they are declared equivalent.becomemerges the states of the two promises, and links one to the other. Thus promises support the analog to tail-call eliminination: no space leak is incurred fromflatMapin the tail position since intermediate promises are merged into the root promise.A number of optimizations are employed to conserve space: we pay particular heed to the JVM's object representation, in particular for OpenJDK (HotSpot) version 7 running on 64-bit architectures with compressed OOPS. See comments on com.twitter.util.Promise.State for details.