Skip to main content

XTaskQueueTerminate

Encerra uma fila de tarefas cancelando todos os itens pendentes e impedindo que novos itens sejam enfileirados.

Sintaxe

Parâmetros

queue   _In_
Tipo: XTaskQueueHandle
A fila a ser encerrada. wait   _In_
Tipo: bool
True para aguardar a conclusão do encerramento. callbackContext   _In_opt_
Tipo: void*
Um ponteiro de contexto opcional a ser passado para o retorno de chamada. callback   _In_opt_
Tipo: XTaskQueueTerminatedCallback*
Um retorno de chamada opcional que será chamado quando a fila for encerrada.

Valor retornado

Tipo: HRESULT Código de sucesso ou de erro HRESULT.

Comentários

Não é seguro chamar esta função em um thread sensível ao tempo. Para obter mais informações, consulte Threads sensíveis ao tempo.
XTaskQueueCloseHandle simplesmente decrementa uma contagem de referências interna no objeto da fila de tarefas. Se ainda houver retornos de chamada na fila, esses retornos de chamada mantêm uma referência ao objeto da fila e ainda podem ser chamados. Isso pode ser um problema no desligamento do aplicativo. Quando um aplicativo é desligado, ele precisa garantir que nenhum retorno de chamada indesejado seja executado após a limpeza. XTaskQueue fornece a API XTaskQueueTerminate para executar um encerramento controlado de uma fila. Encerrar uma fila de tarefas executa as seguintes operações:
  1. Todos os retornos de chamada das duas portas serão invocados com o parâmetro canceled definido como true.
  2. Todos os retornos de chamada pendentes na porta de trabalho serão expedidos. O envio de novos retornos de chamada para a porta de trabalho falhará com E_ABORT.
  3. Todos os retornos de chamada pendentes na porta de conclusão serão expedidos. O envio de novos retornos de chamada para a porta de conclusão falhará com E_ABORT.
Após a conclusão desse processo, XTaskQueueTerminate retornará se wait for true. Se wait for false, o encerramento ocorrerá de forma assíncrona. Se você fornecer um retorno de chamada de encerramento, ele será invocado a partir do thread de conclusão no final do encerramento.
  • XTaskQueueTerminate não fecha o identificador da fila. Após o encerramento, você ainda precisa chamar XTaskQueueCloseHandle.
  • Se você chamar XTaskQueueTerminate em um thread que está atendendo retornos de chamada da fila chamando XTaskQueueDispatch, não passe true para o parâmetro wait, ou seu código poderá entrar em deadlock.
O exemplo a seguir demonstra como encerrar uma fila de tarefas criada anteriormente.
SubmitCallback é uma função auxiliar definida no exemplo de código da função XTaskQueueSubmitCallback.
Uma fila de tarefas pode ser integrada a um thread de interface do usuário. Normalmente, você desejaria que os retornos de chamada enfileirados na porta de conclusão fossem executados no thread de interface do usuário. Este exemplo usa o pool de threads para o trabalho, mas integra os retornos de chamada da porta de conclusão a um Window Proc do Win32. Ele também demonstra o encerramento correto de uma fila de tarefas ao integrá-la a outro modelo de threading.

Requisitos

Cabeçalho: XTaskQueue.h Biblioteca: xgameruntime.lib Plataformas compatíveis: Windows, consoles da família XBOX One e consoles XBOX Series

Documentação conceitual

Confira também

Membros de XTaskQueue
Modelo de programação assíncrona
Design da fila de tarefas assíncrona
Last modified on October 6, 2026