Función CloseThreadpoolCleanupGroupMembers (threadpoolapiset.h)

Artículo
03/02/2024

Libera los miembros del grupo de limpieza especificado, espera a que se completen todas las funciones de devolución de llamada y, opcionalmente, cancela las funciones de devolución de llamada pendientes.

Sintaxis

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

Parámetros

[in, out] ptpcg

Puntero a una estructura de TP_CLEANUP_GROUP que define el grupo de limpieza. La función CreateThreadpoolCleanupGroup devuelve este puntero.

[in] fCancelPendingCallbacks

Si este parámetro es TRUE, la función cancela devoluciones de llamada pendientes que aún no se han iniciado. Si este parámetro es FALSE, la función espera a que se completen las funciones de devolución de llamada pendientes.

[in, out, optional] pvCleanupContext

Los datos definidos por la aplicación que se van a pasar a la función de devolución de llamada del grupo de limpieza de la aplicación. Puede especificar la función de devolución de llamada al llamar a SetThreadpoolCallbackCleanupGroup.

Valor devuelto

None

Observaciones

La función CloseThreadpoolCleanupGroupMembers simplifica la limpieza de los objetos de devolución de llamada del grupo de subprocesos liberando, en una sola operación, todos los objetos de trabajo, objetos de espera y objetos de temporizador que son miembros del grupo de limpieza. Un objeto se convierte en miembro de un grupo de limpieza cuando se crea el objeto con el entorno de devolución de llamada de grupo de subprocesos que se especificó cuando se creó el grupo de limpieza. Para obtener más información, vea CreateThreadpoolCleanupGroup.

La función CloseThreadpoolCleanupGroupMembers se bloquea hasta que finalicen todas las funciones de devolución de llamada que se están ejecutando actualmente. Si fCancelPendingCallbacks es TRUE, se cancelan las devoluciones de llamada pendientes; de lo contrario, la función se bloquea hasta que también finalicen todas las devoluciones de llamada pendientes. Una vez que se devuelve la función CloseThreadpoolCleanupGroupMembers , una aplicación no debe usar ningún objeto que fuera miembro del grupo de limpieza en el momento en que se llamó a CloseThreadpoolCleanupGroupMembers . Además, una aplicación no debe liberar ninguno de los objetos individualmente mediante una llamada a una función como CloseThreadpoolWork, ya que los objetos ya se han liberado.

La función CloseThreadpoolCleanupGroupMembers no cierra el propio grupo de limpieza. En su lugar, el grupo de limpieza persiste hasta que se llama a la función CloseThreadpoolCleanupGroup . Además, cerrar un grupo de limpieza no afecta al entorno de devolución de llamada del grupo de subprocesos asociado. El entorno de devolución de llamada persiste hasta que se destruye mediante una llamada a DestroyThreadpoolEnvironment.

Siempre que un grupo de limpieza persista, se agregan nuevos objetos creados con el entorno de devolución de llamada de grupo de subprocesos asociado del grupo de limpieza. Esto permite que una aplicación reutilice el grupo de limpieza. Sin embargo, puede provocar errores si la aplicación no sincroniza el código que llama a CloseThreadpoolCleanupGroupMembers con código que crea nuevos objetos. Por ejemplo, supongamos que un subproceso crea dos objetos de trabajo de grupo de subprocesos, Work1 y Work2. Otro subproceso llama a CloseThreadpoolCleanupGroupMembers. Dependiendo de cuándo se ejecuten los subprocesos, puede producirse cualquiera de las siguientes acciones:

Work1 y Work2 se agregan al grupo de limpieza después de que se publiquen sus miembros existentes. El código que envía Work1 y Work2 se realizará correctamente.
Work1 se agrega al grupo de limpieza antes de que se publiquen sus miembros existentes, lo que hace que Work1 se publique junto con otros miembros. A continuación, se agrega Work2. El código que envía Work1 generará una excepción; el código que envía Work2 se realizará correctamente.
Work1 y Work2 se agregan al grupo de limpieza antes de que se publiquen sus miembros existentes, lo que hace que work1 y Work2 se publiquen. El código que envía Work1 o Work2 generará una excepción.

Para esperar o cancelar elementos de trabajo pendientes sin liberarlos, use una de las funciones de devolución de llamada del grupo de subprocesos: WaitForThreadpoolIoCallbacks, WaitForThreadpoolTimerCallbacks, WaitForThreadpoolWaitCallbacks o WaitForThreadpoolWorkCallbacks.

Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0600 o superior.

Ejemplos

Para obtener un ejemplo, consulte Uso de las funciones del grupo de subprocesos.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	threadpoolapiset.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll