XAsyncBegin

Article
06/22/2023

Initializes an XAsyncBlock and begins asynchronous work by an asynchronous provider.

Syntax

HRESULT XAsyncBegin(  
         XAsyncBlock* asyncBlock,  
         void* context,  
         const void* identity,  
         const char* identityName,  
         XAsyncProvider* provider  
)

Parameters

asyncBlock _Inout_
Type: XAsyncBlock*

A pointer to the XAsyncBlock that holds data for the asynchronous call.

context _In_opt_
Type: void*

Optional. A context pointer to be stored in the XAsyncProviderData object passed to the XAsyncProvider callback function.

identity _In_opt_
Type: void*

Optional. A pointer to an arbitrary token that can be used to identify the asynchronous call.

identityName _In_opt_
Type: char*

Optional. An string that names the function providing the asynchronous call. The value of this parameter is typically set to the __FUNCTION__ compiler macro.

provider _In_
Type: XAsyncProvider*

A pointer to the XAsyncProvider callback function to invoke for the asynchronous call.

Return value

Type: HRESULT

Returns S_OK if successful; otherwise, returns an error code. For a list of error codes, see Error Codes.

Remarks

XAsyncBegin is invoked to indicate that the asynchronous provider should begin asynchronous work. After XAsyncBegin is invoked, other XAsyncProvider functions, such as XAsyncGetResult will provide meaningful data.

When XAsyncBegin is invoked, the callback function specified in provider is invoked, specifying XAsyncOp::Begin in the op parameter of XAsyncProvider. If the callback function implements this operation code, it should start its asynchronous work by either calling XAsyncSchedule or through exterior means. After XAsyncBegin returns, it is assumed that the callback function has started asynchronous work on a system-defined thread.

Note

The callback function specified in provider is processed synchronously in the XAsyncBegin call chain. Asynchronous work performed by the callback function must not block the thread.

You can use the identity and identityName parameters to identify and manage mismatched XAsyncOp::Begin and XAsyncOp::GetResult calls to the callback function. Typically, the value of identity is set to the function pointer of the function that invoked XAsyncBegin, and the value of identityName is set to the __FUNCTION__ compiler macro.

Requirements

Header: XAsyncProvider.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via