Funzione CloseThreadpoolCleanupGroupMembers (threadpoolapiset.h)

Articolo
08/26/2023

Rilascia i membri del gruppo di pulizia specificato, attende il completamento di tutte le funzioni di callback e, facoltativamente, annulla tutte le funzioni di callback in sospeso.

Sintassi

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

Parametri

[in, out] ptpcg

Puntatore a una struttura TP_CLEANUP_GROUP che definisce il gruppo di pulizia. La funzione CreateThreadpoolCleanupGroup restituisce questo puntatore.

[in] fCancelPendingCallbacks

Se questo parametro è TRUE, la funzione annulla i callback in sospeso non ancora avviati. Se questo parametro è FALSE, la funzione attende il completamento delle funzioni di callback in sospeso.

[in, out, optional] pvCleanupContext

Dati definiti dall'applicazione da passare alla funzione di callback del gruppo di pulizia dell'applicazione. È possibile specificare la funzione di callback quando si chiama SetThreadpoolCallbackCleanupGroup.

Valore restituito

nessuno

Osservazioni

La funzione CloseThreadpoolCleanupGroupMembers semplifica la pulizia degli oggetti di callback del pool di thread rilasciando, in un'unica operazione, tutti gli oggetti di lavoro, gli oggetti wait e gli oggetti timer membri del gruppo di pulizia. Un oggetto diventa un membro di un gruppo di pulizia quando l'oggetto viene creato con l'ambiente di callback del pool di thread specificato al momento della creazione del gruppo di pulizia. Per altre informazioni, vedere CreateThreadpoolCleanupGroup.

La funzione CloseThreadpoolCleanupGroupMembers si blocca fino al termine di tutte le funzioni di callback in esecuzione. Se fCancelPendingCallbacks è TRUE, i callback in sospeso vengono annullati; in caso contrario, la funzione si blocca fino al completamento di tutti i callback in sospeso. Al termine della funzione CloseThreadpoolCleanupGroupMembers , un'applicazione non deve usare alcun oggetto membro del gruppo di pulizia al momento della chiamata a CloseThreadpoolCleanupGroupMembers . Inoltre, un'applicazione non deve rilasciare alcun oggetto singolarmente chiamando una funzione come CloseThreadpoolWork, perché gli oggetti sono già stati rilasciati.

La funzione CloseThreadpoolCleanupGroupMembers non chiude il gruppo di pulizia stesso. Il gruppo di pulizia viene invece mantenuto finché non viene chiamata la funzione CloseThreadpoolCleanupGroup . Inoltre, la chiusura di un gruppo di pulizia non influisce sull'ambiente di callback del pool di thread associato. L'ambiente di callback persiste finché non viene eliminato definitivamente chiamando DestroyThreadpoolEnvironment.

Finché un gruppo di pulizia persiste, i nuovi oggetti creati con l'ambiente di callback del pool di thread del gruppo di pulizia vengono aggiunti al gruppo di pulizia. Ciò consente a un'applicazione di riutilizzare il gruppo di pulizia. Tuttavia, può causare errori se l'applicazione non sincronizza il codice che chiama CloseThreadpoolCleanupGroupMembers con codice che crea nuovi oggetti. Si supponga, ad esempio, che un thread crei due oggetti di lavoro del pool di thread, Work1 e Work2. Un altro thread chiama CloseThreadpoolCleanupGroupMembers. A seconda del momento in cui vengono eseguiti i thread, potrebbe verificarsi una delle operazioni seguenti:

Work1 e Work2 vengono aggiunti al gruppo di pulizia dopo il rilascio dei relativi membri esistenti. Il codice che invia Work1 e Work2 avrà esito positivo.
Work1 viene aggiunto al gruppo di pulizia prima del rilascio dei relativi membri esistenti, causando il rilascio di Work1 insieme ad altri membri. Viene quindi aggiunto Work2. Il codice che invia Work1 genererà un'eccezione; codice che invia Work2 avrà esito positivo.
Work1 e Work2 vengono aggiunti al gruppo di pulizia prima del rilascio dei relativi membri esistenti, causando il rilascio di Work1 e Work2. Il codice che invia Work1 o Work2 genererà un'eccezione.

Per attendere o annullare semplicemente gli elementi di lavoro in sospeso senza rilasciarli, usare una delle funzioni di callback del pool di thread: WaitForThreadpoolIoCallbacks, WaitForThreadpoolTimerCallbacks, WaitForThreadpoolWaitCallbacks o WaitForThreadpoolWorkCallbacks.

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0600 o versione successiva.

Esempio

Per un esempio, vedere Uso delle funzioni del pool di thread.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	threadpoolapiset.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll