# GARFuture

### Futures in ARCore

Futures represent the eventual completion of an asynchronous operation. A future has one of three states, `GARFutureState`, which can be obtained with `https://developers.google.com/ar/reference/ios/interface/GARFuture#state`:


- `https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestatepending` - 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/ios/group/GARFutureState#garfuturestatedone` - The operation is complete, and a result is available.
- `https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestatecancelled` - The operation has been cancelled.

<br />

A `https://developers.google.com/ar/reference/ios/interface/GARFuture#interface_g_a_r_future` starts in the `https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestatepending` state and transitions to `https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestatedone` upon completion. If the future is cancelled using `https://developers.google.com/ar/reference/ios/interface/GARFuture#cancel`, then its state may become `https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestatecancelled` (see [cancelling a future](https://developers.google.com/ar/reference/ios/interface/GARFuture-1future#cancelling-a-future) for caveats).

### Obtaining results from a Future

There are two ways of obtaining results from a `https://developers.google.com/ar/reference/ios/interface/GARFuture#interface_g_a_r_future`:

### Polling a Future

When the `https://developers.google.com/ar/reference/ios/interface/GARFuture#interface_g_a_r_future` is created, its `GARFutureState` is set to `https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestatepending`. You may poll the future using `https://developers.google.com/ar/reference/ios/interface/GARFuture#state` to query the state of the asynchronous operation. When its state is `https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestatedone`, you can obtain the operation's result.

### Using a completion handler to obtain Future results

The operation's result can be reported via a `completionHandler`. When providing a `completionHandler`, ARCore will invoke the given block when the operation is complete, unless the future has been cancelled using `https://developers.google.com/ar/reference/ios/interface/GARFuture#cancel`. This `completionHandler` will be called on the Main thread.

### Cancelling a Future

You can try to cancel a `https://developers.google.com/ar/reference/ios/interface/GARFuture#interface_g_a_r_future` by calling `https://developers.google.com/ar/reference/ios/interface/GARFuture#cancel`. Due to multi-threading, it is possible that the cancel operation is not successful. The return value indicates if the cancellation was successful.

If the cancellation is successful, then any [associated completion handler](https://developers.google.com/ar/reference/ios/interface/GARFuture-1future#using-a-completion-handler-to-obtain-future-results) will never be called.

## Summary

### Inheritance

Inherits from: `NSObject`  
Direct Known Subclasses: [`GARCreateAnchorOnRooftopFuture`](https://developers.google.com/ar/reference/ios/interface/GARCreateAnchorOnRooftopFuture), [`GARCreateAnchorOnTerrainFuture`](https://developers.google.com/ar/reference/ios/interface/GARCreateAnchorOnTerrainFuture), [`GARHostCloudAnchorFuture`](https://developers.google.com/ar/reference/ios/interface/GARHostCloudAnchorFuture), [`GARResolveCloudAnchorFuture`](https://developers.google.com/ar/reference/ios/interface/GARResolveCloudAnchorFuture), [`GARVPSAvailabilityFuture`](https://developers.google.com/ar/reference/ios/interface/GARVPSAvailabilityFuture)

| ### Properties ||
|---|---|
| `https://developers.google.com/ar/reference/ios/interface/GARFuture#state` | `https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestate` The current future state. |

| ### Public methods ||
|---|---|
| `https://developers.google.com/ar/reference/ios/interface/GARFuture#cancel` | `BOOL` Cancels the async operation if it's still pending. |

## Properties

### state

```
@property(nonatomic, readonly) https://developers.google.com/ar/reference/ios/group/GARFutureState#garfuturestate https://developers.google.com/ar/reference/ios/interface/GARFuture#state;
```
The current future state.

## Public methods

### cancel

```
- (BOOL)cancel
```
Cancels the async operation if it's still pending.

If the operation was cancelled by this invocation, this method returns true and the callback (if any) will never be invoked.