wire-signals/com.wire.signals/Cancellable

Cancellable

class Cancellable[+T](promise: Promise[T])(ec: ExecutionContext) extends CancellableFuture[T]

A subclass of CancellableFuture which represents a subset of cancellable futures which are actually cancellable. I know it means the name of the parent class is misleading, since not all cancellable futures are cancellable, but, well, naming is a hard problem in computer science. The reasoning here goes like this: An actually cancellable CancellableFuture is a wrapper over a Promise, not a Future. We create a promise and try to fulfill it with the code given to us in one of the constructor methods. If we succeed, the cancellable future will behave just as a regular one. But thanks to that we hold a promise, we are able to cancel the ongoing execution of that piece of code by calling tryFailure on the promise.

A subclass of CancellableFuture which represents a subset of cancellable futures which are actually cancellable. I know it means the name of the parent class is misleading, since not all cancellable futures are cancellable, but, well, naming is a hard problem in computer science. The reasoning here goes like this: An actually cancellable CancellableFuture is a wrapper over a Promise, not a Future. We create a promise and try to fulfill it with the code given to us in one of the constructor methods. If we succeed, the cancellable future will behave just as a regular one. But thanks to that we hold a promise, we are able to cancel the ongoing execution of that piece of code by calling tryFailure on the promise.

However, in some situations cancelling will not be possible. One is of course that the future may already be completed - with success or with failure (including that it might have been already cancelled). This is why the cancel method returns a boolean - we can't be always 100% sure that calling it will actually cancel the future.

But there is also another possibility. Because of how ubiquitous futures are in the Scala standard library, it makes sense to be able to wrap them in cancellable futures so that they can be used in the same code with the actually cancellable futures. After all, if we're on the happy path, the two behave the same. The only difference appears only when we try to cancel such a "cancellable" future - we don't have access to the parent promise of that future, so we can't cancel it. Calling cancel on such a future will always return false, a callback registered with onCancel will be ignored, etc.

The last case is an inverse of the second one: Sometimes we have an actually cancellable future but we want to make sure that it won't be cancelled in a given piece of code. Imagine a situation when we wait for a result of complex computations which are modelled as a cancellable future. The computations may be cancelled by one class that manages the computations, but we also give a reference to that cancellable future to a few other classes in the program, so that when the computations finish, those classes will be immediately informed, get the result, and use it. But they shouldn't be able to cancel the original computations - even if the given class becomes disinterested in the result, it should not be able to stop the computations for all others. In such case, we can use the method toUncancellable - it will give us an Uncancellable wrapped over the promise.future of our original Cancellable future.

Type Params
T

The result type of the cancellable future

Value Params
ec

The execution context in which the future will be executed. By default it's the default context set in the Threading class

promise

The promise a new cancellable future wraps around

trait Awaitable[T]
class Object
trait Matchable
class Any

Value members

Concrete methods

override def fail(ex: Throwable): Boolean
Definition Classes
override def isCancellable: Boolean
Definition Classes
override def toUncancellable: CancellableFuture[T]
Definition Classes

Inherited 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

Inherited from
CancellableFuture
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

Inherited from
CancellableFuture
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

Inherited from
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

Inherited from
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

Inherited from
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

Inherited from
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

Inherited from
CancellableFuture
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

Inherited from
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

Inherited from
CancellableFuture
@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

Inherited from
CancellableFuture
@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): Cancellable[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
CancellableFuture -> Awaitable
Inherited from
CancellableFuture
@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

Inherited from
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

Inherited from
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
CancellableFuture -> Awaitable
Inherited from
CancellableFuture
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

Inherited from
CancellableFuture
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.

Inherited from
CancellableFuture
@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

Inherited from
CancellableFuture

Concrete fields

override val future: Future[T]