Meta Developers

Many asynchronous methods in the Core SDK return an awaitable OVRTask<TResult>. The methods in this class provide functionality to combine multiple tasks (see WhenAll<T1,T2>) and create your own OVRTask<TResult> (see Create<TResult>). For more information on tasks, see Asynchronous Tasks.

The OVRTask<TResult> struct is a task-like object which supports the await pattern. Typically, you do not need to create or use this object directly. Instead, you can either:

await a method which returns an object of type OVRTask<TResult>, which will eventually return a TResult
poll the IsCompleted property and then call GetResult
pass a delegate by calling ContinueWith(Action<TResult>). Note that an additional state object can get passed in and added as a parameter of the callback, see ContinueWith<T>

Note this requires the main thread to complete the await contract; therefore, blocking on an OVRTask can result in an infinite loop.

You can also:

Combine multiple tasks (OVRTask.WhenAll<T1,T2>)
Create your own task (OVRTask.Create<TResult>)

For more details, including code samples, see Asynchronous Tasks.

Others

TResult

The type of result being awaited.

Properties

bool IsCompleted[Get]

Indicates whether the task has completed.

Choose only one pattern out of the three proposed way of awaiting for the task completion: Polling,async/await or ContinueWith(Action<TResult>) as all three patterns will end up calling the GetResult which can only be called once.

Returns

True if the task has completed. GetResult can be called.

bool IsFaulted[Get]

Whether the task completed due to an unhandled exception.

If the task is in a faulted state, then you can extract the exception with GetException.

bool HasResult[Get]

Whether there is a result available.

This property is true when the OVRTask<TResult> is complete (IsCompleted is true) and GetResult has not already been called.Note that GetResult is called implicitly when using await or ContinueWith.

See Also:

GetResult, TryGetResult

Static Member Functions

static OVRTask< TResult[]> WhenAll< TResult >

( IEnumerable< OVRTask< TResult > > tasks )

Creates a task that completes when all of the supplied tasks have completed.

This can be used to combine multiple tasks into a single task. The returned task completes when all tasks in tasks complete.The result of the returned task is an array containing the results of each individual task. The results are arranged in the same order as the original tasks list.

Parameters

tasks

The tasks to combine

Others

TResult

The type of the result produced by the tasks .

Returns

Returns a new task which is completed when all tasks have completed.

Exceptions

ArgumentNullException

Thrown if tasks is null.

See Also:

OVRTask

static OVRTask< List< TResult > > WhenAll< TResult >

( IEnumerable< OVRTask< TResult > > tasks,

List< TResult > results )

Creates a task that completes when all of the supplied tasks have completed.

This can be used to combine multiple tasks into a single task. The returned task completes when all tasks in tasks complete.The result of each task in tasks is added to results . The results are in the same order as tasks .The list in the combined task is a reference to results . This allows the caller to own (and potentially reuse) the memory for the list of results. It is undefined behavior to access results before the returned task completes.

Parameters

tasks

The tasks to combine

results

A list to store the results in. The list is cleared before adding any results to it.

Others

TResult

The type of the result produced by the tasks .

Returns

Returns a new task which completes when all tasks are complete.

Exceptions

ArgumentNullException

Thrown if tasks is null.

ArgumentNullException

Thrown if results is null.

See Also:

OVRTask

static OVRTask< TResult > FromResult< TResult >

( TResult result )

Creates an already-complete task.

This creates a completed task whose result is result .

Parameters

result

The result of the task.

Others

TResult

The type of the result.

Returns

Returns a new, completed task-like object whose result is result .

static void SetResult< TResult >

( Guid id,

TResult result )

Sets the result of a pending task.

Set the result of a task previously created with Create<TResult>. When this method returns, OVRTask<TResult>.IsCompleted will be true.This allows you to await on MyOpAsync:

OVRTask\<int\> MyOpAsync() {
  _id = Guid.NewGuid();
  var task = OVRTask.Create\<int\>(id);
return task;
}
// later, when the task completes:
void Update() {
if (operationComplete) {
    OVRTask.SetResult(_id, result);
  }
}

async void OnButtonPressed() {
  var result = await MyOpAsync();
}

Parameters

The task's unique id.

result

The result the task should have.

Others

TResult

The type of the result.

Exceptions

InvalidOperationException

Thrown if the task with id id already has a result.

static OVRTask< TResult > Create< TResult >

( Guid taskId )

Creates a new task.

This method creates a new pending task. When the task completes, set its result with SetResult<TResult>.The returned task is in a pending state; that is, OVRTask<TResult>.IsCompleted is false until you later set its result with SetResult<TResult>.The taskId must be unique to the new task. You may use any Guid as long as it has not previously been used to create a task. Use

Guid.NewGuid()

to generate a random task id.

Parameters

taskId

The id used to assign the new task.

Others

TResult

The type of the result.

Returns

Returns a new task which completes when you call SetResult<TResult>.

Exceptions

ArgumentException

Thrown if taskId refers to an existing task.

static bool operator==

( OVRTask< TResult > lhs,

OVRTask< TResult > rhs )

Compares two tasks for equality.

This is the same equality test as Equals(OVRTask<TResult>).

Parameters

lhs

The task to compare with rhs .

rhs

The task to compare with lhs .

Returns

Returns true if lhs is equal to rhs , otherwise false.

static bool operator!=

( OVRTask< TResult > lhs,

OVRTask< TResult > rhs )

Compares two tasks for inequality.

This is the logical negation of Equals(OVRTask<TResult>).

Parameters

lhs

The task to compare with rhs .

rhs

The task to compare with lhs .

Returns

Returns true if lhs is not equal to rhs , otherwise false.

static OVRTask<(T1, T2)> WhenAll< T1, T2 >

( OVRTask< T1 > task1,

OVRTask< T2 > task2 )

Creates a new task that will complete when all of the given tasks have completed.

This method can be used to combine multiple tasks into a single task that depends on all of them. When the returned task completes, the results of all combined tasks can be accessed through the result of the returned task. The type of the result is a tuple containing the result types of each input task, that is

ValueTuple\<T1, T2\>

For example,

var (result1, result2) = await OVRTask.Combine(task1, task2);

Parameters

task1

The first task to combine

task2

The second task to combine

Returns

Returns a task that represents the completion of all input tasks.

static OVRTask<(T1, T2, T3)> WhenAll< T1, T2, T3 >

( OVRTask< T1 > task1,

OVRTask< T2 > task2,

OVRTask< T3 > task3 )

Creates a new task that will complete when all of the given tasks have completed.

ValueTuple\<T1, T2, T3\>

For example,

var (result1, result2, result3) = await OVRTask.Combine(task1, task2, task3);

Parameters

task1

The first task to combine

task2

The second task to combine

task3

The third task to combine

Returns

Returns a task that represents the completion of all input tasks.

static OVRTask<(T1, T2, T3, T4)> WhenAll< T1, T2, T3, T4 >

( OVRTask< T1 > task1,

OVRTask< T2 > task2,

OVRTask< T3 > task3,

OVRTask< T4 > task4 )

Creates a new task that will complete when all of the given tasks have completed.

ValueTuple\<T1, T2, T3, T4\>

For example,

var (result1, result2, result3, result4) = await OVRTask.Combine(task1, task2, task3, task4);

Parameters

task1

The first task to combine

task2

The second task to combine

task3

The third task to combine

task4

The forth task to combine

Returns

Returns a task that represents the completion of all input tasks.

static OVRTask<(T1, T2, T3, T4, T5)> WhenAll< T1, T2, T3, T4, T5 >

( OVRTask< T1 > task1,

OVRTask< T2 > task2,

OVRTask< T3 > task3,

OVRTask< T4 > task4,

OVRTask< T5 > task5 )

Creates a new task that will complete when all of the given tasks have completed.

ValueTuple\<T1, T2, T3, T4, T5\>

For example,

var (result1, result2, result3, result4, result5) = await OVRTask.Combine(task1, task2, task3, task4, task5);

Parameters

task1

The first task to combine

task2

The second task to combine

task3

The third task to combine

task4

The forth task to combine

task5

The fifth task to combine

Returns

Returns a task that represents the completion of all input tasks.

static OVRTask<(T1, T2, T3, T4, T5, T6)> WhenAll< T1, T2, T3, T4, T5, T6 >

( OVRTask< T1 > task1,

OVRTask< T2 > task2,

OVRTask< T3 > task3,

OVRTask< T4 > task4,

OVRTask< T5 > task5,

OVRTask< T6 > task6 )

Creates a new task that will complete when all of the given tasks have completed.

ValueTuple\<T1, T2, T3, T4, T5, T6\>

For example,

var (result1, result2, result3, result4, result5, result6) = await OVRTask.Combine(task1, task2, task3, task4, task5, task6);

Parameters

task1

The first task to combine

task2

The second task to combine

task3

The third task to combine

task4

The forth task to combine

task5

The fifth task to combine

task6

The sixth task to combine

Returns

Returns a task that represents the completion of all input tasks.

static OVRTask<(T1, T2, T3, T4, T5, T6, T7)> WhenAll< T1, T2, T3, T4, T5, T6, T7 >

( OVRTask< T1 > task1,

OVRTask< T2 > task2,

OVRTask< T3 > task3,

OVRTask< T4 > task4,

OVRTask< T5 > task5,

OVRTask< T6 > task6,

OVRTask< T7 > task7 )

Creates a new task that will complete when all of the given tasks have completed.

ValueTuple\<T1, T2, T3, T4, T5, T6, T7\>

For example,

var (result1, result2, result3, result4, result5, result6, result7) = await OVRTask.Combine(task1, task2, task3, task4, task5, task6, task7);

Parameters

task1

The first task to combine

task2

The second task to combine

task3

The third task to combine

task4

The forth task to combine

task5

The fifth task to combine

task6

The sixth task to combine

task7

The seventh task to combine

Returns

Returns a task that represents the completion of all input tasks.

static OVRTask<(T1, T2, T3, T4, T5, T6, T7, T8)> WhenAll< T1, T2, T3, T4, T5, T6, T7, T8 >

( OVRTask< T1 > task1,

OVRTask< T2 > task2,

OVRTask< T3 > task3,

OVRTask< T4 > task4,

OVRTask< T5 > task5,

OVRTask< T6 > task6,

OVRTask< T7 > task7,

OVRTask< T8 > task8 )

Creates a new task that will complete when all of the given tasks have completed.

ValueTuple\<T1, T2, T3, T4, T5, T6, T7, T8\>

For example,

var (result1, result2, result3, result4, result5, result6, result7, result8) = await OVRTask.Combine(task1, task2, task3, task4, task5, task6, task7, task8);

Parameters

task1

The first task to combine

task2

The second task to combine

task3

The third task to combine

task4

The forth task to combine

task5

The fifth task to combine

task6

The sixth task to combine

task7

The seventh task to combine

task8

The eighth task to combine

Returns

Returns a task that represents the completion of all input tasks.

Member Functions

Exception GetException ( )

Get the exception if the task is in a faulted state.

If IsFaulted is true, then this method gets the exception associated with this method. Similar to GetResult, you can only get the exception once and throws if there is no exception.When using await or ContinueWith, you do not need to explicitly get the exception. Use this method when you have an exception when it is implicitly created by the compiler and you query the task object directly, as in the following example:

async OVRTask\<bool\> DoSomethingAsync() {
  var anchor = await OVRAnchor.CreateSpatialAnchorAsync(pose); // \<\– implicitly generated OVRTask\<bool\>
  SomeMethodThatThrows();
returntrue;
}
OVRTask\<bool\> task = DoSomethingAsync();
// later...
if (task.IsFaulted) {
throw task.GetException();
}

Returns

Returns the Exception associated with the task.

Exceptions

InvalidOperationException

Thrown if IsFaulted is false.

TResult GetResult ( )

Gets the result of the asynchronous operation.

This method should only be called once IsCompleted is true. Calling it multiple times will throw InvalidOperationException.Note that GetResult is called implicitly when using await or ContinueWith. You should not call this method explicitly when using one of those mechanisms.

Returns

Returns the result of type TResult .

Exceptions

InvalidOperationException

Thrown when the task doesn't have any available result. This could happen if the method is called before IsCompleted is true, after the task has been disposed of, if this method has already been called once, or if an exception was thrown during the task's execution.

See Also:

HasResult, TryGetResult

bool TryGetResult

( out TResult result )

Tries to get the result of the asynchronous operation.

This method may safely be called at any time. It tests whether the operation is both complete (IsCompleted is true) and the result has not already been retrieved with GetResult (HasResult is true).If the result is available, result is set to the result and this method returns true. This method is equivalent to (though more efficient than) the following:

if (task.HasResult) {
  result = task.GetResult();
returntrue;
} else {
  result = default;
returnfalse;
}

Parameters

result

Set to the result of the task, if one is available. Otherwise, it is set to the default value for TResult .

Returns

true if this task is complete and a result is available.

Exceptions

InvalidOperationException

Thrown when the task doesn't have any available result. This could happen if the method is called before IsCompleted is true, after the task has been disposed of or if this method has already been called once.

See Also:

HasResult, GetResult

ValueTask< TResult > ToValueTask ( )

Converts the task to a ValueTask.

This method converts this OVRTask<TResult> to a ValueTask.A ValueTask is similar to an OVRTask. Key differences:

A ValueTask does not support ContinueWith
A ValueTask does not support WhenAll(System.Collections.Generic.IEnumerable<OVRTask<TResult>>)

The above are only supported on the Task object.Invoking this method also invalidates this OVRTask<TResult>. It is invalid to continue using an OVRTask<TResult> after calling ToValueTask.

Returns

Returns a new ValueTask that completes when the asynchronous operation completes.

Exceptions

InvalidOperationException

Thrown if the task is not pending (IsCompleted is true) and does not have a result (HasResult is false)

InvalidOperationException

Thrown if the task has already been awaited.

InvalidOperationException

Thrown if ContinueWith has already been called.

Awaiter GetAwaiter ( )

Gets an awaiter that satisfies the await contract.

This allows an OVRTask<TResult> to be awaited using the await keyword. Typically, you should not call this directly; instead, it is invoked by the compiler, e.g.,

// Something that returns an OVRTask\<T\>
var task = GetResultAsync();
// compiler uses GetAwaiter here
var result = await task;

Or, more commonly:

var result = await GetResultAsync();

Requires the main thread to complete the await contract - blocking can result in an infinite loop.

Returns

Returns an Awaiter-like object that satisfies the await pattern.

void ContinueWith

( Action< TResult > onCompleted )

Registers a delegate to be invoked on completion of the task.

The delegate will be invoked with the TResult result as parameter.Do not use in conjunction with any other methods (await or calling GetResult).Note: If the task throws an exception during execution, there is no way to catch it in when using ContinueWith. Most Meta XR Core SDK calls that return an OVRTask do not throw, but it is possible to return an OVRTask<TResult> from your own async method, which can still throw. For example,

async OVRTask\<OVRAnchor\> DoSomethingAsync() {
  var anchor = await OVRAnchor.CreateSpatialAnchorAsync(pose); // doesn't throw
thrownew Exception(); // Cannot be caught if using ContinueWith
return anchor;
}
async void MethodA() {
try {
    var anchor = await DoSomethingAsync();
  } catch (Exception e) {
// okay; exception caught!
  }
}
void MethodB() {
  DoSomethingAsync().ContinueWith(anchor =\> {
    Debug.Log($"Anchor {anchor} created!");
  });
}

In the above example, the exception generated by DoSomethingAsync is caught in MethodA, but there is no way to catch it in MethodB because it uses ContinueWith rather than await. The exception is still thrown, however.

Parameters

onCompleted

A delegate to be invoked when this task completes. If the task is already complete, onCompleted is invoked immediately.

See Also:

ContinueWith<T>

Exceptions

ArgumentNullException

Thrown if onCompleted is null.

InvalidOperationException

Thrown if this task is already being awaited.

InvalidOperationException

Thrown if this task is already used in another ContinueWith.

InvalidOperationException

Thrown if this task is already used as a ValueTask (ToValueTask).

InvalidOperationException

Thrown if this task is already used or as an Awaitable. (ToAwaitable, only available in Unity 2023.1+).

void ContinueWith< T >

( Action< TResult, T > onCompleted,

T state )

Registers a delegate that will get called on completion of the task.

The delegate will be invoked with state and the TResult result as parameters. Do not use in conjunction with any other methods (await or calling GetResult).Note: If the task throws an exception during execution, there is no way to catch it in when using a callback. See ContinueWith(Action<TResult>) for more details.

Parameters

onCompleted

A delegate to be invoked when this task completes. If the task is already complete, onCompleted is invoked immediately.

state

An object to store and pass to onCompleted .

See Also:

ContinueWith(Action<TResult>)

Exceptions

ArgumentNullException

Thrown if onCompleted is null.

InvalidOperationException

Thrown if this task is already being awaited.

InvalidOperationException

Thrown if this task is already used in another ContinueWith.

InvalidOperationException

Thrown if this task is already used as a ValueTask (ToValueTask).

InvalidOperationException

Thrown if this task is already used or as an Awaitable. (ToAwaitable, only available in Unity 2023.1+).

void Dispose ( )

Disposes of the task.

Invalidate this object but does not cancel the task. In the case where the result will not actually be consumed, it must be called to prevent a memory leak. You can not call GetResult nor use await on a disposed task.

bool Equals

( OVRTask< TResult > other )

Compares for equality with another task.

Parameters

other

The OVRTask<TResult> to compare for equality with this task.

Returns

Returns true if the two task objects represent the same task, otherwise false.

override bool Equals

( object obj )

Compares for equality with an object.

Parameters

obj

The object to compare for equality with this task.

Returns

Returns true if obj is an OVRTask<TResult> and represents the same task as this one, otherwise false.

override int GetHashCode ( )

Generates a hash code suitable for use in a Dictionary or HashSet

Returns

Returns a hash code suitable for use in a Dictionary or HashSet

override string ToString ( )

Generates a string representation of this task, based on its internal id.

Internally, tasks are identified by a System.Guid. This method should only be used for debugging purposes. The implementation or behavior may change in future versions, so you should not rely on the format of this string for other uses.

Returns

Returns the stringification of this task's unique identifier (Guid).