XTaskQueueRegisterWaiter

タスク キューに待機ハンドルを登録します。

構文

HRESULT XTaskQueueRegisterWaiter(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         HANDLE waitHandle,  
         void* callbackContext,  
         XTaskQueueCallback* callback,  
         XTaskQueueRegistrationToken* token  
)  

パラメーター

queue _In_
型: XTaskQueueHandle

コールバックの送信先のキュー。

port _In_
型: XTaskQueuePort

コールバックの送信先のポート。 コールバックは、処理ポートまたは完了ポートに割り当てることができます。

waitHandle _In_
型: HANDLE

監視するハンドル。

注意

これは、通知されるとコールバックが呼び出される待機ハンドルです。 待機ハンドルは、通常、自動または手動リセット イベントです。 待機ハンドルが手動リセットの場合、イベントが通知される限り、コールバックが繰り返し呼び出されます。 そうしたくない場合は、コールバックの間にイベントをリセットするか、または待機コールバックを登録解除します。

callbackContext _In_opt_
型: void*

コールバックに渡されるオプションのコンテキスト ポインター。

callback _In_
型: XTaskQueueCallback*

コールバック関数に対するポインター。

token _Out_
型: XTaskQueueRegistrationToken*

登録トークン。 これを XTaskQueueUnregisterWaiter に渡して、待機の登録を解除できます。

戻り値

型: HRESULT

HRESULT 成功またはエラー コード。

解説

注意

この関数は、時間依存のスレッドで呼び出すのに安全ではありません。 詳細については、「時間依存のスレッド」を参照してください。

待機ハンドルが満たされると、タスク キューは指定されたコールバックを呼び出します。 これにより、ハンドルが通知されたらタスク キューに項目を追加する効率的な方法が提供されます。

次の例では、タスク キューに Win32 カーネル ハンドルを登録します。 ハンドルが通知されると、コールバックがキューに送信されます。 通常は、通知に使用する自動リセット イベントを作成します。 ハンドルが自動リセットされない場合は、ハンドルが通知されている限り、現在のコールバックが完了したときに新しいコールバックが送信されます。

void CreatingTaskQueueWaiter()
{
    HANDLE waitEvent = CreateEvent(nullptr, FALSE, FALSE, nullptr);
    if (waitEvent == nullptr)
    {
        printf("Error creating wait handle: %d\r\n", GetLastError());
        return;
    }

    XTaskQueueHandle queue;

    HRESULT hr = XTaskQueueCreate(
        XTaskQueueDispatchMode::ThreadPool,
        XTaskQueueDispatchMode::ThreadPool, 
        &queue);

    if (FAILED(hr))
    {
        printf("Error creating task queue: %x\n", hr);
        CloseHandle(waitEvent);
        return;
    }

    auto callback = [](void*, bool)
    {
        printf("Callback invoked.\r\n");
    };

    XTaskQueueRegistrationToken token;

    hr = XTaskQueueRegisterWaiter(
        queue, 
        XTaskQueuePort::Completion, 
        waitEvent, 
        nullptr, 
        callback, 
        &token);

    if (FAILED(hr))
    {
        printf("Error registering task queue waiter: %x\n", hr);
        CloseHandle(waitEvent);
        XTaskQueueCloseHandle(queue);
        return;
    }

    // Now, whenever our wait event becomes signaled the callback will be called.
    for (uint32_t i = 0; i < 5; i++)
    {
        SetEvent(waitEvent);
        Sleep(100);
    }

    // Note: unregistering the waiter is optional
    XTaskQueueUnregisterWaiter(queue, token);
    XTaskQueueCloseHandle(queue);
    CloseHandle(waitEvent);
}

要件

ヘッダー: XTaskQueue.h

ライブラリ: xgameruntime.lib

サポートされているプラットフォーム: Windows、Xbox One ファミリー本体、Xbox Series 本体

関連項目

XTaskQueue のメンバー
非同期プログラミング モデル
非同期タスク キューの設計