API reference
OVRTask Class
Extends IEquatable< OVRTask< TResult > >, IDisposable
Static methods related to OVRTask<TResult>.
Represents an awaitable task.
The static class OVRTask provides some utilities for working with tasks.
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
Static Member Functions
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
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
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
id
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 to generate a random task id.
Guid.NewGuid()
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.
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.
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.
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 For example,
ValueTuple\<T1, T2\>
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.
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 For example,
ValueTuple\<T1, T2, T3\>
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.
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 For example,
ValueTuple\<T1, T2, T3, T4\>
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.
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 For example,
ValueTuple\<T1, T2, T3, T4, T5\>
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.
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 For example,
ValueTuple\<T1, T2, T3, T4, T5, T6\>
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.
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 For example,
ValueTuple\<T1, T2, T3, T4, T5, T6, T7\>
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.
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 For example,
ValueTuple\<T1, T2, T3, T4, T5, T6, T7, T8\>
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
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.
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>>)
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., Or, more commonly: Requires the main thread to complete the await contract - blocking can result in an infinite loop.
// Something that returns an OVRTask\<T\>
var task = GetResultAsync();
// compiler uses GetAwaiter here
var result = await task;
var result = await GetResultAsync();
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, 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.
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!");});
}
Parameters
onCompleted
A delegate to be invoked when this task completes. If the task is already complete, onCompleted is invoked immediately.
See Also
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
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.
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).
See Also
Did you find this page helpful?
Virtual reality / Meta Horizon
Support and legal
Virtual reality / Meta Horizon
Support and legal
Virtual reality / Meta Horizon
Support and legal
English (US)
© 2025 Meta