XTaskQueueCreate

호출을 큐에 넣고 디스패치하기 위해 사용될 수 있는 작업 큐를 생성합니다.

구문

HRESULT XTaskQueueCreate(  
         XTaskQueueDispatchMode workDispatchMode,  
         XTaskQueueDispatchMode completionDispatchMode,  
         XTaskQueueHandle* queue  
)  

매개 변수

workDispatchMode _In_
형식: XTaskQueueDispatchMode

큐의 '작업' 포트에 대한 디스패치 모드입니다.

completionDispatchMode _In_
형식: XTaskQueueDispatchMode

큐의 '완료' 포트에 대한 디스패치 모드입니다.

queue _Out_
형식: XTaskQueueHandle*

새로 생성된 큐입니다.

반환 값

형식: HRESULT

HRESULT 성공 또는 오류 코드입니다.

비고

참고 항목

이 함수는 시간에 민감한 스레드에서 호출하는 것이 안전하지 않습니다. 자세한 내용은 시간에 민감한 스레드를 참조하세요.

작업 큐는 참조 계산된 개체입니다. XTaskQueueCloseHandle을 호출하여 참조를 릴리스합니다.

작업 큐에는 작업 및 완료 포트가 포함되며, 작업은 어느 포트로도 큐에 넣을 수 있습니다. 각 포트는 고유 디스패치 모드로 구성될 수 있습니다.

대부분의 시나리오에서는 XTaskQueueCreate API를 사용하여 작업 큐를 생성합니다. 하지만 여러 비동기 호출을 하나로 연결할 경우, XTaskQueueCreateComposite를 통해 복합 큐를 생성하는 것이 유용할 수 있습니다. 해당 구현이 작업 큐를 사용하는 다른 API를 호출해야 하는 API를 고려해보세요. 호출자의 완료 스레드에 고정되지 않도록 API의 완료 콜백을 리디렉션해야 할 수 있습니다. 이 경우 해당 작업 및 완료 포트가 다른 큐의 작업 포트로부터 작성되는 복합 작업 큐를 생성할 수 있습니다.

다음 예에서는 시스템 스레드 풀에서 작업 및 완료 콜백을 모두 디스패치하는 작업 큐를 생성합니다.

참고 항목

SubmitCallback 은 XTaskQueueSubmitCallback 함수의 코드 예제에 정의된 도우미 함수입니다.

void CreatingTaskQueue()
{
    XTaskQueueHandle queue;
    HRESULT hr = XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::ThreadPool, &queue);
    if (FAILED(hr))
    {
        printf("Creating queue failed: 0x%x\r\n", hr);
        return;
    }

    SubmitCallbacks(queue);

    // Wait a while for the callbacks to run
    Sleep(1000);

    XTaskQueueTerminate(queue, true, nullptr, nullptr);
}

다음 예에서는 수동으로 펌핑되는 작업 큐를 생성합니다. 작업 및 완료 포트 모두에 대해 호출을 발송하는 2개의 STL 스레드를 생성합니다.

참고 항목

SubmitCallback 은 XTaskQueueSubmitCallback 함수의 코드 예제에 정의된 도우미 함수입니다.

void CreatingTaskQueueWithManualThreads()
{
    // Create a manual task queue
    XTaskQueueHandle queue;
    HRESULT hr = XTaskQueueCreate(XTaskQueueDispatchMode::Manual, XTaskQueueDispatchMode::Manual, &queue);
    if (FAILED(hr))
    {
        printf("Creating queue failed: 0x%x\r\n", hr);
        return;
    }

    // We create threads to pump the queue: one for the work port
    // and one for the completion port.
    std::thread workThread([queue]
    {
        while (XTaskQueueDispatch(queue, XTaskQueuePort::Work, INFINITE));
    });

    std::thread completionThread([queue]
    {
        while (XTaskQueueDispatch(queue, XTaskQueuePort::Completion, INFINITE));
    });

    SubmitCallbacks(queue);

    // Wait a while for the callbacks to run
    Sleep(1000);

    // Terminating the queue will cause a waiting DispatchTaskQueue to return
    // false.  
    XTaskQueueTerminate(queue, true, nullptr, nullptr);

    workThread.join();
    completionThread.join();
}

요구 사항

헤더: XTaskQueue.h

라이브러리: xgameruntime.lib

지원되는 플랫폼: Windows, Xbox One 패밀리 콘솔 및 Xbox Series 콘솔

참고 항목

XTaskQueue 멤버
비동기 프로그래밍 모델
비동기 작업 큐 디자인