wire-signals/com.wire.signals/CancellableFuture

CancellableFuture

abstract class CancellableFuture[+T](ec: ExecutionContext) extends Awaitable[T]

CancellableFuture is an object that for all practical uses works like a future but enables the user to cancel the operation. A cancelled future fails with CancellableFuture.CancelException so the subscriber can differentiate between this and other failure reasons. It is impossible to cancel a future if it is already completed or if it is uncancellable.

CancellableFuture is an object that for all practical uses works like a future but enables the user to cancel the operation. A cancelled future fails with CancellableFuture.CancelException so the subscriber can differentiate between this and other failure reasons. It is impossible to cancel a future if it is already completed or if it is uncancellable.

See also

Uncancellable for details on uncancellable futures

Companion
object
trait Awaitable[T]
class Object
trait Matchable
class Any
class Cancellable[T]
class Uncancellable[T]

Value members

Abstract methods

def fail(th: Throwable): Boolean

Tries to fails the future with the given exception as the failure's reason.

Tries to fails the future with the given exception as the failure's reason.

Value Params
th

The reason for the failure

Returns

true if the future was cancelled, false if it was not possible to cancel it

def future: Future[T]

Gives direct access to the underlying future.

Gives direct access to the underlying future.

def isCancellable: Boolean

Returns if the future is actually cancellable (not completed and not uncancellable)

Returns if the future is actually cancellable (not completed and not uncancellable)

See also

Uncancellable for details on uncancellable futures

def toUncancellable: CancellableFuture[T]

Creates a copy of this future that cannot be cancelled

Creates a copy of this future that cannot be cancelled

See also

Uncancellable for details on uncancellable futures

Concrete methods

final def addTimeout(timeout: FiniteDuration): CancellableFuture[T]

If the future is actually cancellable, adds a timeout after which this future will be cancelled. In theory, it's possible to add more than one timeout - the shortest one will cancel all others. Returns the reference to itself so it can be chained with other CancellableFuture methods.

If the future is actually cancellable, adds a timeout after which this future will be cancelled. In theory, it's possible to add more than one timeout - the shortest one will cancel all others. Returns the reference to itself so it can be chained with other CancellableFuture methods.

Value Params
timeout

A time interval after which this future is cancelled if it's cancellable

Returns

The reference to itself

def cancel(): Boolean

Tries to cancel the future. If successful, the future fails with CancellableFuture.CancelException

Tries to cancel the future. If successful, the future fails with CancellableFuture.CancelException

Returns

true if the future was cancelled, false if it was not possible to cancel it

final def collect[U](pf: PartialFunction[T, U])(executor: ExecutionContext): CancellableFuture[U]

Creates a new cancellable future by mapping the value of the current one, if the given partial function is defined at that value. Otherwise, the resulting cancellable future will fail with a NoSuchElementException.

Creates a new cancellable future by mapping the value of the current one, if the given partial function is defined at that value. Otherwise, the resulting cancellable future will fail with a NoSuchElementException.

Type Params
U

The result type of the partial function pf

Value Params
executor

The execution context in which the new future will be executed, by default it will be the execution context of this future

pf

A partial function which will be applied to the result of the original future if that result belongs to a subset for which the partial function is defined

Returns

A new cancellable future that will finish with success only if the partial function is applied

See also

Future.collect for more - this is its equivalent for CancellableFuture

final def filter(p: T => Boolean)(executor: ExecutionContext): CancellableFuture[T]

Creates a new cancellable future by applying the predicate p to the current one. If the original future completes with success, but the result does not satisfies the predicate, the resulting future will fail with a NoSuchElementException.

Creates a new cancellable future by applying the predicate p to the current one. If the original future completes with success, but the result does not satisfies the predicate, the resulting future will fail with a NoSuchElementException.

Value Params
executor

The execution context in which the new future will be executed, by default it will be the execution context of this future

p

a predicate function returning a boolean

Returns

a new cancellable future that will finish with success only if the predicate is satisfied

See also

Future.filter for more - this is its equivalent for CancellableFuture

final def flatMap[U](f: T => CancellableFuture[U])(executor: ExecutionContext): CancellableFuture[U]

Creates a new cancellable future by applying a function to the successful result of this future, and returns the result of the function as the new future. If this future fails or is cancelled, the cancel operation and the result is carried over.

Creates a new cancellable future by applying a function to the successful result of this future, and returns the result of the function as the new future. If this future fails or is cancelled, the cancel operation and the result is carried over.

Type Params
U

The result type of the function f

Value Params
executor

The execution context in which the new future will be executed, by default it will be the execution context of this future

f

A function which will be applied to the result of the original future if that result belongs to a subset for which the partial function is defined

Returns

A new cancellable future that will finish with success only if the partial function is applied

See also

Future.flatMap for more - this is its equivalent for CancellableFuture

@inline
final def flatten[U](evidence: T <:< CancellableFuture[U], executor: ExecutionContext): CancellableFuture[U]

Flattens a nested cancellable future. If we have a cancellable future val cf: CancellableFuture[ CancellableFuture[U] ] with the result of cf is another cancellable future - i.e. after executing the original one we will get another future and then we will execute that, and only then get the result of type U - then we can use CancellableFuture.flatten to merge these two steps into one. As a result, we will have one cancellable future which after successful execution will give us a result of type U.

Flattens a nested cancellable future. If we have a cancellable future val cf: CancellableFuture[ CancellableFuture[U] ] with the result of cf is another cancellable future - i.e. after executing the original one we will get another future and then we will execute that, and only then get the result of type U - then we can use CancellableFuture.flatten to merge these two steps into one. As a result, we will have one cancellable future which after successful execution will give us a result of type U.

Type Params
U

The result type of the nested future and the result type of the resulting future

Value Params
executor

The execution context in which the new future will be executed, by default it will be the execution context of this future

Returns

A new cancellable future made from flattening the original one

See also

Future.flatten for more - this is its equivalent for CancellableFuture

@inline
final def foreach[U](pf: T => U)(executor: ExecutionContext): Unit

Same as Future.foreach.

Same as Future.foreach.

Type Params
U

The result type of pf

Value Params
executor

The execution context in which pf will be executed, by default it will be the execution context of this future

pf

The partial function which will be executed when this future is completed with success

See also

Future

final def map[U](f: T => U)(executor: ExecutionContext): CancellableFuture[U]

Creates a new cancellable future by applying the f function to the successful result of this one. If this future is completed with an exception then the new future will also contain this exception. If the operation after the cancelling was provided, it will be carried over to the new cancellable future. If you cancel this future,

Creates a new cancellable future by applying the f function to the successful result of this one. If this future is completed with an exception then the new future will also contain this exception. If the operation after the cancelling was provided, it will be carried over to the new cancellable future. If you cancel this future,

Type Params
U

The result type of f

Value Params
executor

The execution context in which the new future will be executed, by default it will be the execution context of this future

f

The function transforming the result type of this future into the result type of the new one

Returns

A new cancellable future with the result type U being the outcome of the function f applied to the result type of this future

See also

Future.map for more - this is its equivalent for CancellableFuture

def onCancel(body: => Unit): CancellableFuture[T]

Adds a callback for when the future is cancelled (but not failed for any other reason). There can be more than one onCancel callback. Returns the reference to itself so it can be chained with other CancellableFuture methods.

Adds a callback for when the future is cancelled (but not failed for any other reason). There can be more than one onCancel callback. Returns the reference to itself so it can be chained with other CancellableFuture methods.

Value Params
body

The callback code

Returns

The reference to itself

@inline
final def onComplete[U](f: Try[T] => U)(executor: ExecutionContext): Unit

Same as Future.onComplete.

Same as Future.onComplete.

Type Params
U

The result type of f

Value Params
executor

The execution context in which f will be executed, by default it will be the execution context of this future

f

The function which will be executed when this future is completed

See also

Future

@throws(scala.throws.$lessinit$greater$default$1[scala.InterruptedException]) @throws(scala.throws.$lessinit$greater$default$1[scala.concurrent.TimeoutException])
final override def ready(atMost: Duration)(permit: CanAwait): CancellableFuture[T]

Same as Future.ready. '''''This method should not be called directly; use Await.ready instead.'''''

Same as Future.ready. '''''This method should not be called directly; use Await.ready instead.'''''

Definition Classes
Awaitable
@inline
final def recover[U >: T](pf: PartialFunction[Throwable, U])(executor: ExecutionContext): CancellableFuture[U]

Creates a new cancellable future that will handle any matching throwable that this future might contain. If there is no match, or if this future contains a valid result then the new future will contain the same. Works also if the current future is cancelled.

Creates a new cancellable future that will handle any matching throwable that this future might contain. If there is no match, or if this future contains a valid result then the new future will contain the same. Works also if the current future is cancelled.

Type Params
U

The result type of the partial function pf and the result type of the new future if pf is defined for the Throwable returned by the original future

Value Params
executor

The execution context in which the new future will be executed, by default it will be the execution context of this future

pf

A partial function which will be applied to the Throwable returned as the failure reason of the original future if that result belongs to a subset for which the partial function is defined. (For example, you can define a partial function that works only on a specific type of exception, i.e. on a subclass of Throwable, and for other exceptions the future should really fail).

Returns

A new cancellable future that will finish with success only if the partial function is applied

See also

Future.recover for more - this is its equivalent for CancellableFuture

final def recoverWith[U >: T](pf: PartialFunction[Throwable, CancellableFuture[U]])(executor: ExecutionContext): CancellableFuture[U]

Creates a new cancellable future that will handle any matching throwable that the current one might contain by assigning it a value of another future. Works also if the current future is cancelled. If there is no match, or if this cancellable future contains a valid result, then the new future will contain the same result.

Creates a new cancellable future that will handle any matching throwable that the current one might contain by assigning it a value of another future. Works also if the current future is cancelled. If there is no match, or if this cancellable future contains a valid result, then the new future will contain the same result.

Type Params
U

The result type of the partial function pf and the result type of the new future if pf is defined for the Throwable returned by the original future

Value Params
executor

The execution context in which the new future will be executed, by default it will be the execution context of this future

pf

A partial function which will be applied to the Throwable returned as the failure reason of the original future if that result belongs to a subset for which the partial function is defined. (For example, you can define a partial function that works only on a specific type of exception, i.e. on a subclass of Throwable, and for other exceptions the future should really fail).

Returns

A new cancellable future that will finish with success only if the partial function is applied

See also

Future.recoverWith for more - this is its equivalent for CancellableFuture

@throws(scala.throws.$lessinit$greater$default$1[scala.Exception])
final override def result(atMost: Duration)(permit: CanAwait): T

Same as Future.result. '''''This method should not be called directly; use Await.result instead.'''''

Same as Future.result. '''''This method should not be called directly; use Await.result instead.'''''

Definition Classes
Awaitable
final def withAutoCanceling(eventContext: EventContext): Subscription

Registers the cancellable future in the given event context. When the event context is stopped, the future will be cancelled. The subscription is also returned so it can be managed manually.

Registers the cancellable future in the given event context. When the event context is stopped, the future will be cancelled. The subscription is also returned so it can be managed manually.

Value Params
eventContext

The event context which this future will be subscribed to

Returns

A Subscription representing the connection between the event context and the future. You can use it to cancel the future manually, even if the event context hasn't stopped yet.

See also

EventContext

final def withFilter(p: T => Boolean)(executor: ExecutionContext): CancellableFuture[T]

An alias for filter, used by for-comprehensions.

An alias for filter, used by for-comprehensions.

@inline
final def zip[U](other: CancellableFuture[U])(executor: ExecutionContext): CancellableFuture[(T, U)]

Creates a new CancellableFuture from the current one and the provided one. The new future completes with success only if both original futures complete with success. If any of the fails or is cancelled, the resulting future fails or is cancelled as well. If the user cancels the resulting future, both original futures are cancelled.

Creates a new CancellableFuture from the current one and the provided one. The new future completes with success only if both original futures complete with success. If any of the fails or is cancelled, the resulting future fails or is cancelled as well. If the user cancels the resulting future, both original futures are cancelled.

Type Params
U

the result type of the other future

Value Params
executor

The execution context in which the new future will be executed, by default it will be the execution context of this future

other

The other cancellable future, with the result of the type U, that will be zipped with this one

Returns

A new cancellable future with the result type being a tuple (T, U) where T is the result type of this future

See also

Future.zip for more - this is its equivalent for CancellableFuture