# SuspendToFutureAdapter

Artifact: [androidx.concurrent:concurrent-futures](https://developer.android.com/jetpack/androidx/releases/concurrent) [View Source](https://cs.android.com/search?q=file:androidx/concurrent/futures/SuspendToFutureAdapter.kt+class:androidx.concurrent.futures.SuspendToFutureAdapter) Added in [1.4.0-alpha01](https://developer.android.com/jetpack/androidx/releases/concurrent#1.4.0-alpha01)

*** ** * ** ***

<br />

```
object SuspendToFutureAdapter
```

<br />

*** ** * ** ***

A utility for launching suspending calls scoped and managed by a returned `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html`, used for adapting Kotlin suspending APIs to be callable from the Java programming language.

## Summary

| ### Public functions |
|---|---|
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<T>` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)( context: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html, launchUndispatched: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, block: suspend https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html.() -> T )` Launch `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` in `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)`, returning a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` to manage the launched operation. |

## Public functions

### launchFuture

Added in [1.4.0-alpha01](https://developer.android.com/jetpack/androidx/releases/concurrent#1.4.0-alpha01)

```
fun <T : Any?> launchFuture(
    context: CoroutineContext = EmptyCoroutineContext,
    launchUndispatched: Boolean = true,
    block: suspend CoroutineScope.() -> T
): ListenableFuture<T>
```

Launch `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` in `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)`, returning a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` to manage the launched operation. `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` will run **synchronously** to its first suspend point, behaving as `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-start/-u-n-d-i-s-p-a-t-c-h-e-d/index.html` by default; set `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` to false to override and behave as `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-start/-d-e-f-a-u-l-t/index.html`.

`https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` can be used to write adapters for calling suspending functions from the Java programming language, e.g.

```kotlin
@file:JvmName("FancyServices")

fun FancyService.requestAsync(
    args: FancyServiceArgs
): ListenableFuture<FancyResult> = SuspendToFutureAdapter.launchFuture {
    request(args)
}
```

which can be called from Java language source code as follows:

```kotlin
final ListenableFuture<FancyResult> result = FancyServices.requestAsync(service, args);
```

If no `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-dispatcher/index.html` is provided in `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)`, `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-main.html` is used as the default. `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html#get()` should not be called from the main thread prior to the future's completion (whether it was obtained from `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter` or not) as any operation performed in the process of completing the future may require main thread event processing in order to proceed, leading to potential main thread deadlock.

If the operation performed by `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` is known to be safe for potentially reentrant continuation resumption, immediate dispatchers such as `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-unconfined.html` may be used as part of `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` to avoid additional thread dispatch latency. This should not be used as a means of supporting clients blocking the main thread using `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html#get()`; this support can be broken by valid internal implementation changes to any transitive dependencies of the operation performed by `https://developer.android.com/reference/kotlin/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)`.