# 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 />

```
public static class 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 fields |
|---|---|
| `static @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/concurrent/futures/SuspendToFutureAdapter` | `https://developer.android.com/reference/androidx/concurrent/futures/SuspendToFutureAdapter#INSTANCE()` |

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<@https://developer.android.com/reference/androidx/annotation/NonNull T>` | `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html context, boolean launchUndispatched, @https://developer.android.com/reference/androidx/annotation/NonNull SuspendFunction1<@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html, @https://developer.android.com/reference/androidx/annotation/NonNull T> block )` Launch `https://developer.android.com/reference/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` in `https://developer.android.com/reference/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 fields

### INSTANCE

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

```
public static @NonNull SuspendToFutureAdapter INSTANCE
```

## Public methods

### launchFuture

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

```
public final @NonNull ListenableFuture<@NonNull T> <T extends Object> launchFuture(
    @NonNull CoroutineContext context,
    boolean launchUndispatched,
    @NonNull SuspendFunction1<@NonNull CoroutineScope, @NonNull T> block
)
```

Launch `https://developer.android.com/reference/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)` in `https://developer.android.com/reference/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/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/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/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.

```
@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:

```
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/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/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/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/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/androidx/concurrent/futures/SuspendToFutureAdapter#launchFuture(kotlin.coroutines.CoroutineContext,kotlin.Boolean,kotlin.coroutines.SuspendFunction1)`.