Función RegisterWaitForSingleObject (winbase.h)

Artículo
08/27/2023

Dirige un subproceso de espera en el grupo de subprocesos para que espere en el objeto . El subproceso de espera pone en cola la función de devolución de llamada especificada al grupo de subprocesos cuando se produce una de las siguientes acciones:

El objeto especificado está en estado señalado.
El intervalo de tiempo de espera transcurre.

Sintaxis

BOOL RegisterWaitForSingleObject(
  [out]          PHANDLE             phNewWaitObject,
  [in]           HANDLE              hObject,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Context,
  [in]           ULONG               dwMilliseconds,
  [in]           ULONG               dwFlags
);

Parámetros

[out] phNewWaitObject

Puntero a una variable que recibe un identificador de espera al devolver. Tenga en cuenta que no se puede usar un identificador de espera en funciones que requieran un identificador de objeto, como CloseHandle.

[in] hObject

Identificador del objeto . Para obtener una lista de los tipos de objeto cuyos identificadores se pueden especificar, vea la sección Comentarios siguiente.

Si se cierra este identificador mientras la espera sigue pendiente, el comportamiento de la función no está definido.

Los identificadores deben tener el derecho de acceso SYNCHRONIZE . Para obtener más información, consulte Derechos de acceso estándar.

[in] Callback

Puntero a la función definida por la aplicación del tipo WAITORTIMERCALLBACK que se va a ejecutar cuando hObject está en estado señalado o dwMilliseconds transcurre. Para obtener más información, vea WaitOrTimerCallback.

[in, optional] Context

Valor único que se pasa a la función de devolución de llamada.

[in] dwMilliseconds

El intervalo de tiempo de espera en milisegundos. La función devuelve si transcurre el intervalo, incluso si el estado del objeto no tiene signo. Si dwMilliseconds es cero, la función prueba el estado del objeto y devuelve inmediatamente. Si dwMilliseconds es INFINITE, el intervalo de tiempo de espera de la función nunca transcurre.

[in] dwFlags

Este parámetro puede ser uno o más de los siguientes valores.

Para obtener información sobre cómo usar estos valores con objetos que permanecen señalados, vea la sección Comentarios.

Valor	Significado
WT_EXECUTEDEFAULT 0x00000000	De forma predeterminada, la función de devolución de llamada se pone en cola en un subproceso de trabajo que no es de E/S.
WT_EXECUTEINIOTHREAD 0x00000001	Esta marca no se usa. Windows Server 2003 y Windows XP: La función de devolución de llamada se pone en cola en un subproceso de trabajo de E/S. Esta marca se debe usar si la función debe ejecutarse en un subproceso que espera en un estado de alerta. Los subprocesos de trabajo de E/S se quitaron a partir de Windows Vista y Windows Server 2008.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	La función de devolución de llamada se pone en cola en un subproceso que nunca finaliza. No garantiza que se use el mismo subproceso cada vez. Esta marca solo se debe usar para tareas cortas o podría afectar a otras operaciones de espera. Esta marca debe establecerse si el subproceso llama a funciones que usan API. Para obtener más información, vea Llamadas asincrónicas a procedimientos. Tenga en cuenta que actualmente no hay ningún subproceso de trabajo realmente persistente, aunque ningún subproceso de trabajo finalizará si hay solicitudes de E/S pendientes.
WT_EXECUTEINWAITTHREAD 0x00000004	El propio subproceso de espera invoca la función de devolución de llamada. Esta marca solo se debe usar para tareas cortas o podría afectar a otras operaciones de espera. Los interbloqueos pueden producirse si algún otro subproceso adquiere un bloqueo exclusivo y llama a la función UnregisterWait o UnregisterWaitEx mientras la función de devolución de llamada intenta adquirir el mismo bloqueo.
WT_EXECUTELONGFUNCTION 0x00000010	La función de devolución de llamada puede realizar una larga espera. Esta marca ayuda al sistema a decidir si debe crear un subproceso nuevo.
WT_EXECUTEONLYONCE 0x00000008	El subproceso ya no esperará en el identificador después de llamar a la función de devolución de llamada una vez. De lo contrario, el temporizador se restablece cada vez que se completa la operación de espera hasta que se cancela la operación de espera.
WT_TRANSFER_IMPERSONATION 0x00000100	Las funciones de devolución de llamada usarán el token de acceso actual, ya sea un token de proceso o suplantación. Si no se especifica esta marca, las funciones de devolución de llamada solo se ejecutan con el token de proceso. Windows XP: Esta marca no se admite hasta Windows XP con SP2 y Windows Server 2003.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a
GetLastError.

Comentarios

Los nuevos subprocesos de espera se crean automáticamente cuando es necesario. La operación de espera se realiza mediante un subproceso de espera del grupo de subprocesos. El subproceso de trabajo ejecuta la rutina de devolución de llamada cuando el estado del objeto se señala o transcurre el intervalo de tiempo de espera. Si dwFlags no es WT_EXECUTEONLYONCE, el temporizador se restablece cada vez que se señala el evento o transcurre el intervalo de tiempo de espera.

Cuando se complete la espera, debe llamar a la función UnregisterWait o UnregisterWaitEx para cancelar la operación de espera. (Incluso las operaciones de espera que usan WT_EXECUTEONLYONCE deben cancelarse). No realice una llamada de bloqueo a ninguna de estas funciones desde dentro de la función de devolución de llamada.

Tenga en cuenta que no debe pulsar un objeto de evento pasado a RegisterWaitForSingleObject, ya que es posible que el subproceso de espera no detecte que el evento se señala antes de que se restablezca. No debe registrar un objeto que permanezca señalado (por ejemplo, un evento de restablecimiento manual o un proceso finalizado), a menos que establezca la marca WT_EXECUTEONLYONCE o WT_EXECUTEINWAITTHREAD . En el caso de otras marcas, es posible que se llame a la función de devolución de llamada demasiadas veces antes de restablecer el evento.

La función modifica el estado de algunos tipos de objetos de sincronización. La modificación solo se produce para el objeto cuyo estado señalado ha provocado que se cumpla la condición de espera. Por ejemplo, el recuento de un objeto de semáforo se reduce en uno.

La función RegisterWaitForSingleObject puede esperar los siguientes objetos:

Notificación de cambios
Entrada de la consola
Evento
Notificación de recursos de memoria
Mutex
Proceso
Semaphore
Thread
Temporizador de espera

Para obtener más información, vea Objetos de sincronización.

De forma predeterminada, el grupo de subprocesos tiene un máximo de 500 subprocesos. Para aumentar este límite, use la macro WT_SET_MAX_THREADPOOL_THREAD definida en WinNT.h.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)&lt;&lt;16)

Use esta macro al especificar el parámetro dwFlags . Los parámetros de macro son las marcas deseadas y el nuevo límite (hasta (2<<16)-1 subprocesos). Sin embargo, tenga en cuenta que la aplicación puede mejorar su rendimiento manteniendo el número de subprocesos de trabajo bajos.

El elemento de trabajo y todas las funciones a las que llama deben ser seguros para el grupo de subprocesos. Por lo tanto, no se puede llamar a una llamada asincrónica que requiera un subproceso persistente, como la función RegNotifyChangeKeyValue , desde el entorno de devolución de llamada predeterminado. En su lugar, establezca el máximo del grupo de subprocesos igual al mínimo del grupo de subprocesos mediante las funciones SetThreadPoolThreadMaximum y SetThreadMinimum , o cree su propio subproceso mediante la función CreateThread . (Para la API del grupo de subprocesos original, especifique WT_EXECUTEINPERSISTENTTHREAD mediante la función QueueUserWorkItem ).

Para compilar una aplicación que usa esta función, defina _WIN32_WINNT como 0x0500 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll