kotlinx-coroutines-guava/kotlinx.coroutines.guava/future

future

fun <T> CoroutineScope.future(context: CoroutineContext = EmptyCoroutineContext, start: CoroutineStart = CoroutineStart.DEFAULT, block: suspend CoroutineScope.() -> T): ListenableFuture<T>(source)

Starts block in a new coroutine and returns a ListenableFuture pointing to its result.

The coroutine is started immediately. Passing CoroutineStart.LAZY to start throws IllegalArgumentException, because Futures don't have a way to start lazily.

When the created coroutine isCompleted, it will try to synchronously complete the returned Future with the same outcome. This will succeed, barring a race with external cancellation of returned ListenableFuture.

Cancellation is propagated bidirectionally.

CoroutineContext is inherited from this CoroutineScope. Additional context elements can be added/overlaid by passing context.

If the context does not have a CoroutineDispatcher, nor any other ContinuationInterceptor member, Dispatchers.Default is used.

The parent job is inherited from this CoroutineScope, and can be overridden by passing a Job in context.

See newCoroutineContext for a description of debugging facilities.

Note that the error and cancellation semantics of future are different than async's. In contrast to Deferred, Future doesn't have an intermediate Cancelling state. If the returned Future is successfully cancelled, and block throws afterward, the thrown error is dropped, and getting the Future's value will throw a CancellationException with no cause. This is to match the specification and behavior of java.util.concurrent.FutureTask.

Parameters

context

added overlaying CoroutineScope.coroutineContext to form the new context.

start

coroutine start option. The default value is CoroutineStart.DEFAULT.

block

the code to execute.

fun <T> CoroutineScope.future(context: Job, start: CoroutineStart = CoroutineStart.DEFAULT, block: suspend CoroutineScope.() -> T): ListenableFuture<T>(source)

Deprecated

Passing a Job to coroutine builders breaks structured concurrency, leading to hard-to-diagnose errors. This pattern should be avoided. This overload will be deprecated with an error in the future.

Deprecated version of future that accepts a Job.

See the documentation for the non-deprecated future function to learn about the functionality of this function.

See the documentation for the deprecated async overload accepting a Job for an explanation of the reason this pattern is deprecated and the list of possible alternatives.