# ArFuture

Futures in ARCore.

### Futures in ARCore

Futures represent the eventual completion of an asynchronous operation. A future has one of three states, `https://developers.google.com/ar/reference/c/group/ar-future#arfuturestate`, which can be obtained with `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_getstate:`


- `https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_pending` - The operation is still pending. The result of the operation isn't available yet and any associated callback hasn't yet been invoked.
- `https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_done` - The operation is complete, and a result is available.
- `https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_cancelled` - The operation has been cancelled.

<br />

An `https://developers.google.com/ar/reference/c/group/ar-future#arfuture` starts in the `https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_pending` state and transitions to `https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_done` upon completion. If the future is cancelled using `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_cancel`, then its state may become `https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_cancelled` (see [cancelling a future](https://developers.google.com/ar/reference/c/group/ar-future-1future#cancelling-a-future) for caveats).

Futures must eventually be released using `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_release`. ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).

### Obtaining results from a Future

There are two ways of obtaining results from an `https://developers.google.com/ar/reference/c/group/ar-future#arfuture:`

### Polling a Future

When the `https://developers.google.com/ar/reference/c/group/ar-future#arfuture` is created, its `https://developers.google.com/ar/reference/c/group/ar-future#arfuturestate` is set to `https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_pending`. You may poll the future using `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_getstate` to query the state of the asynchronous operation. When its state is `https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_done`, you can obtain the operation's result. The future must eventually be released using `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_release`.

### Using a callback to obtain Future results

The operation's result can be reported via a callback. When providing a callback, ARCore will invoke the given function when the operation is complete, unless the future has been cancelled using `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_cancel`. This callback will be invoked on the [main thread](https://developer.android.com/guide/components/processes-and-threads#Threads).

When providing a callback, you may provide a `context`, which will be passed as the first parameter to the callback. It is a best practice to free the memory of `context` at the end of the callback and when `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_cancel` successfully cancels the callback.

### Cancelling a Future

You can try to cancel an `https://developers.google.com/ar/reference/c/group/ar-future#arfuture` by calling `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_cancel`. Due to multi-threading, it is possible that the cancel operation is not successful. The `out_was_cancelled` parameter indicates if the cancellation was successful.

If the cancellation is successful, then any [associated callback](https://developers.google.com/ar/reference/c/group/ar-future-1future#using-a-callback-to-obtain-future-results) will never be called. It is a best practice to free context memory provided to the callback, if any.

## Summary

| ### Enumerations ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-future#arfuturestate{ https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_pending = 0, https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_cancelled = 1, https://developers.google.com/ar/reference/c/group/ar-future#ar_future_state_done = 2 }` | enumThe state of an asynchronous operation. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-future#arfuture` | typedef `struct ArFuture_` Base type for asynchronous operations. |

| ### Functions ||
|---|---|
| `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_cancel(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, https://developers.google.com/ar/reference/c/group/ar-future#arfuture *future, int32_t *out_was_cancelled)` | `void` Tries to cancel execution of this operation. |
| `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_getstate(const https://developers.google.com/ar/reference/c/group/ar-session#arsession *session, const https://developers.google.com/ar/reference/c/group/ar-future#arfuture *future, https://developers.google.com/ar/reference/c/group/ar-future#arfuturestate *out_state)` | `void` Gets the state of an asynchronous operation. |
| `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_release(https://developers.google.com/ar/reference/c/group/ar-future#arfuture *future)` | `void` Releases a reference to a future. |

## Enumerations

### ArFutureState

```
 ArFutureState
```
The state of an asynchronous operation.

| Properties ||
|---|---|
| `AR_FUTURE_STATE_CANCELLED` | The operation has been cancelled. Any associated callback will never be invoked. |
| `AR_FUTURE_STATE_DONE` | The operation is complete and the result is available. If a callback was associated with this future, it will soon be invoked with the result on the main thread, if it hasn't been invoked already. |
| `AR_FUTURE_STATE_PENDING` | The operation is still pending. The result of the operation isn't available yet and any associated callback hasn't yet been dispatched or invoked. Do not use this to check if the operation can be cancelled as the state can change from another thread between the calls to `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_getstate` and `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_cancel`. |

## Typedefs

### ArFuture

```
struct ArFuture_ ArFuture
```
Base type for asynchronous operations.

See [Futures in ARCore](https://developers.google.com/ar/reference/c/group/ar-future-1future#futures-in-arcore) for more details.

An acquired future must eventually be released using `https://developers.google.com/ar/reference/c/group/ar-future#arfuture_release`. ([reference type, long-lived](https://developers.google.com/ar/reference/c/group/concepts#object-ownership)).

## Functions

### ArFuture_cancel

```
void ArFuture_cancel(
  const ArSession *session,
  ArFuture *future,
  int32_t *out_was_cancelled
)
```
Tries to cancel execution of this operation.

`out_was_cancelled` will be set to 1 if the operation was cancelled by this invocation, and in that case it is a best practice to free `context` memory provided to the [callback](https://developers.google.com/ar/reference/c/group/ar-future-1future#using-a-callback-to-obtain-future-results), if any.


Details Parameters `session` The ARCore session. `future` The handle for the asynchronous operation. `out_was_cancelled` Set to 1 if this invocation successfully cancelled the operation, 0 otherwise. You may pass `NULL`.

### ArFuture_getState

```
void ArFuture_getState(
  const ArSession *session,
  const ArFuture *future,
  ArFutureState *out_state
)
```
Gets the state of an asynchronous operation.

See `https://developers.google.com/ar/reference/c/group/ar-future#arfuturestate` and [Futures in ARCore](https://developers.google.com/ar/reference/c/group/ar-future-1future#futures-in-arcore) for more details.


Details Parameters `session` The ARCore session. `future` The handle for the asynchronous operation. `out_state` The state of the operation.

### ArFuture_release

```
void ArFuture_release(
  ArFuture *future
)
```
Releases a reference to a future.

This does not mean that the operation will be terminated - see [cancelling a future](https://developers.google.com/ar/reference/c/group/ar-future-1future#cancelling-a-future).

This function may safely be called with `NULL` - it will do nothing.