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:

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{
  AR_FUTURE_STATE_PENDING = 0,
  AR_FUTURE_STATE_CANCELLED = 1,
  AR_FUTURE_STATE_DONE = 2
} 		enum
The state of an asynchronous operation.

Typedefs
ArFuture typedef
struct ArFuture_
Base type for asynchronous operations.

Functions
ArFuture_cancel(const ArSession *session, ArFuture *future, int32_t *out_was_cancelled)
void
Tries to cancel execution of this operation.
ArFuture_getState(const ArSession *session, const ArFuture *future, ArFutureState *out_state)
void
Gets the state of an asynchronous operation.
ArFuture_release(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 ArFuture_getState and ArFuture_cancel.

Typedefs

ArFuture

struct ArFuture_ ArFuture

Base type for asynchronous operations.

See Futures in ARCore for more details.

An acquired future must eventually be released using ArFuture_release. (reference type, long-lived).

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, 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 ArFutureState and 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.

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