ArFuture

Futures in ARCore.

Futures in ARCore

Futures represent the eventual completion of an asynchronous operation. A future has one of three states, ArFutureState, which can be obtained with ArFuture_getState:

• 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.
• AR_FUTURE_STATE_DONE - The operation is complete, and a result is available.
• AR_FUTURE_STATE_CANCELLED - The operation has been cancelled.

An ArFuture starts in the AR_FUTURE_STATE_PENDING state and transitions to AR_FUTURE_STATE_DONE upon completion. If the future is cancelled using ArFuture_cancel, then its state may become AR_FUTURE_STATE_CANCELLED (see cancelling a future for caveats).

Futures must eventually be released using ArFuture_release. (reference type, long-lived).

Obtaining results from a Future

There are two ways of obtaining results from an ArFuture:

Polling a Future

When the ArFuture is created, its ArFutureState is set to AR_FUTURE_STATE_PENDING. You may poll the future using ArFuture_getState to query the state of the asynchronous operation. When its state is AR_FUTURE_STATE_DONE, you can obtain the operation's result. The future must eventually be released using 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 ArFuture_cancel. This callback will be invoked on the main thread.

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 ArFuture_cancel successfully cancels the callback.

Cancelling a Future

You can try to cancel an ArFuture by calling 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 will never be called. It is a best practice to free context memory provided to the callback, if any.

Summary

Enumerations

 ArFutureState

Typedefs

struct ArFuture_ ArFuture

Functions

void ArFuture_cancel(
  const ArSession *session,
  ArFuture *future,
  int32_t *out_was_cancelled
)

void ArFuture_getState(
  const ArSession *session,
  const ArFuture *future,
  ArFutureState *out_state
)

void ArFuture_release(
  ArFuture *future
)