Função CloseThreadpoolCleanupGroupMembers (threadpoolapiset.h)

Artigo
03/08/2023

Libera os membros do grupo de limpeza especificado, aguarda a conclusão de todas as funções de retorno de chamada e, opcionalmente, cancela quaisquer funções de retorno de chamada pendentes.

Sintaxe

void CloseThreadpoolCleanupGroupMembers(
  [in, out]           PTP_CLEANUP_GROUP ptpcg,
  [in]                BOOL              fCancelPendingCallbacks,
  [in, out, optional] PVOID             pvCleanupContext
);

Parâmetros

[in, out] ptpcg

Um ponteiro para uma estrutura TP_CLEANUP_GROUP que define o grupo de limpeza. A função CreateThreadpoolCleanupGroup retorna esse ponteiro.

[in] fCancelPendingCallbacks

Se esse parâmetro for TRUE, a função cancelará retornos de chamada pendentes que ainda não foram iniciados. Se esse parâmetro for FALSE, a função aguardará a conclusão das funções de retorno de chamada pendentes.

[in, out, optional] pvCleanupContext

Os dados definidos pelo aplicativo a serem passados para a função de retorno de chamada do grupo de limpeza do aplicativo. Você pode especificar a função de retorno de chamada ao chamar SetThreadpoolCallbackCleanupGroup.

Retornar valor

Nenhum

Comentários

A função CloseThreadpoolCleanupGroupMembers simplifica a limpeza de objetos de retorno de chamada do pool de threads liberando, em uma única operação, todos os objetos de trabalho, objetos de espera e objetos de temporizador que são membros do grupo de limpeza. Um objeto torna-se membro de um grupo de limpeza quando o objeto é criado com o ambiente de retorno de chamada do threadpool que foi especificado quando o grupo de limpeza foi criado. Para obter mais informações, consulte CreateThreadpoolCleanupGroup.

A função CloseThreadpoolCleanupGroupMembers é bloqueada até que todas as funções de retorno de chamada em execução no momento sejam concluídas. Se fCancelPendingCallbacks for TRUE, os retornos de chamada pendentes serão cancelados; caso contrário, a função será bloqueada até que todos os retornos de chamada pendentes também sejam concluídos. Depois que a função CloseThreadpoolCleanupGroupMembers retornar, um aplicativo não deve usar nenhum objeto que fosse membro do grupo de limpeza no momento em que CloseThreadpoolCleanupGroupMembers foi chamado. Além disso, um aplicativo não deve liberar nenhum dos objetos individualmente chamando uma função como CloseThreadpoolWork, porque os objetos já foram liberados.

A função CloseThreadpoolCleanupGroupMembers não fecha o próprio grupo de limpeza. Em vez disso, o grupo de limpeza persiste até que a função CloseThreadpoolCleanupGroup seja chamada. Além disso, fechar um grupo de limpeza não afeta o ambiente de retorno de chamada do threadpool associado. O ambiente de retorno de chamada persiste até ser destruído chamando DestroyThreadpoolEnvironment.

Enquanto um grupo de limpeza persistir, novos objetos criados com o ambiente de retorno de chamada do threadpool associado do grupo de limpeza serão adicionados ao grupo de limpeza. Isso permite que um aplicativo reutilize o grupo de limpeza. No entanto, isso poderá levar a erros se o aplicativo não sincronizar o código que chama CloseThreadpoolCleanupGroupMembers com código que cria novos objetos. Por exemplo, suponha que um thread crie dois objetos de trabalho de threadpool, Work1 e Work2. Outro thread chama CloseThreadpoolCleanupGroupMembers. Dependendo de quando os threads são executados, qualquer um dos seguintes pode ocorrer:

Work1 e Work2 são adicionados ao grupo de limpeza depois que seus membros existentes foram liberados. O código que envia Work1 e Work2 terá êxito.
O Work1 é adicionado ao grupo de limpeza antes que seus membros existentes sejam lançados, fazendo com que o Work1 seja lançado junto com outros membros. Em seguida, o Work2 é adicionado. O código que envia o Work1 gerará uma exceção; O código que envia Work2 terá êxito.
O Work1 e o Work2 são adicionados ao grupo de limpeza antes de seus membros existentes serem lançados, fazendo com que o Work1 e o Work2 sejam lançados. O código que envia Work1 ou Work2 gerará uma exceção.

Para simplesmente aguardar ou cancelar itens de trabalho pendentes sem liberá-los, use uma das funções de retorno de chamada do threadpool: WaitForThreadpoolIoCallbacks, WaitForThreadpoolTimerCallbacks, WaitForThreadpoolWaitCallbacks ou WaitForThreadpoolWorkCallbacks.

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0600 ou superior.

Exemplos

Para obter um exemplo, consulte Usando as funções do pool de threads.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	threadpoolapiset.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll