Función FsRtlCancellableWaitForMultipleObjects (ntifs.h)

Artículo
08/07/2023

La rutina FsRtlCancellableWaitForMultipleObjects ejecuta una operación de espera cancelable (una espera que se puede finalizar) en uno o varios objetos distribuidores.

Sintaxis

NTSTATUS FsRtlCancellableWaitForMultipleObjects(
  [in]           ULONG          Count,
  [in]           PVOID []       ObjectArray,
  [in]           WAIT_TYPE      WaitType,
  [in, optional] PLARGE_INTEGER Timeout,
  [in, optional] PKWAIT_BLOCK   WaitBlockArray,
  [in, optional] PIRP           Irp
);

Parámetros

[in] Count

Número de objetos en los que se va a esperar.

[in] ObjectArray

Puntero a una matriz de punteros a objetos de distribuidor (eventos, exclusiones mutuas, semáforos, subprocesos y temporizadores) para los que el autor de la llamada proporciona el almacenamiento.

[in] WaitType

WaitAll, que indica que todos los objetos especificados deben alcanzar un estado señalado antes de que se cumpla la espera; o WaitAny, que indica que cualquiera de los objetos debe alcanzar un estado señalado antes de que se cumpla la espera.

[in, optional] Timeout

Puntero a un valor de tiempo de espera opcional. Este parámetro especifica el tiempo absoluto o relativo, en 100 unidades nanosegundas, en las que se va a completar la espera.

Si Timeout apunta a un valor cero (es decir, *Timeout == 0), la rutina devuelve sin esperar. Si el autor de la llamada proporciona un puntero NULL (es decir, Timeout == NULL), la rutina espera indefinidamente hasta que cualquiera o todos los objetos del distribuidor se establecen en el estado señalado.

Un valor positivo especifica una hora absoluta, relativa al 1 de enero de 1601. Un valor negativo especifica un intervalo relativo a la hora actual. Los tiempos de expiración absolutos realizan un seguimiento de los cambios en la hora del sistema; los tiempos de expiración relativos no se ven afectados por los cambios de hora del sistema.

Si se especifica Timeout , la espera se cumplirá automáticamente si no se cumple ninguna de las condiciones de espera especificadas cuando expire el intervalo especificado.

Un valor de tiempo de espera de cero (es decir, *Timeout == 0) permite probar un conjunto de condiciones de espera y realizar condicionalmente cualquier acción adicional si la espera se puede satisfacer inmediatamente, como en la adquisición de una exclusión mutua.

[in, optional] WaitBlockArray

Si Count<= THREAD_WAIT_OBJECTS, WaitBlockArray puede ser NULL. De lo contrario, este parámetro debe apuntar a un búfer de memoria de sizeof(KWAIT_BLOCK * Count) bytes. La rutina usa este búfer para mantener registros mientras se realiza la operación de espera.

[in, optional] Irp

Puntero al IRP original que corresponde a la operación de E/S emitida por el usuario y que el usuario puede cancelar. El autor de la llamada debe asegurarse de que el IRP seguirá siendo válido durante esta rutina y que el IRP no debe tener un conjunto de rutinas de cancelación (por ejemplo, no se debe haber llamado a IoSetCancelRoutine en el IRP). Tenga en cuenta que el IRP debe ser mantenido por el autor de la llamada, no se puede pasar a un controlador de nivel inferior.

Valor devuelto

FsRtlCancellableWaitForMultipleObjects puede devolver uno de los valores siguientes:

Código devuelto	Descripción
STATUS_SUCCESS	El llamador especificó WaitAll para el parámetro WaitType y todos los objetos distribuidores de la matriz ObjectArray se han establecido en el estado señalado.
STATUS_TIMEOUT	Se agotó el tiempo de espera antes de que se cumpla el conjunto especificado de condiciones de espera. Este valor se puede devolver cuando no se puede cumplir inmediatamente el conjunto especificado de condiciones de espera y Timeout se establece en cero.
STATUS_WAIT_0 a través de STATUS_WAIT_63	El autor de la llamada especificó WaitAny para WaitType y uno de los objetos dispatcher de la matriz ObjectArray se ha establecido en el estado señalado. Los seis bits inferiores del valor devuelto codifican el índice de base cero del objeto que satisface la espera.
STATUS_ABANDONED_WAIT_0 a través de STATUS_ABANDONED_WAIT_63	El autor de la llamada intentó esperar una exclusión mutua que se ha abandonado. Los seis bits inferiores del valor devuelto codifican el índice de base cero de la exclusión mutua en la matriz ObjectArray .
STATUS_CANCELLED	La espera se interrumpió mediante una solicitud de cancelación pendiente en el IRP especificado. Tenga en cuenta que este valor solo se devuelve si se pasa un IRP válido a FsRtlCancellableWaitForMultipleObjects y CancelSynchronousIo canceló el IRP.
STATUS_THREAD_IS_TERMINATING	La espera se interrumpió porque una aplicación o el usuario han terminado el subproceso.

El valor devuelto solo indica el estado de la espera. Si procede, el estado real de la solicitud de E/S debe obtenerse directamente de otro IRP generado en el proceso de control del IRP en modo de usuario original.

Tenga en cuenta que la macro de NT_SUCCESS devuelve FALSE ("error") para los valores de STATUS_CANCELLED y STATUS_THREAD_IS_TERMINATING estado y TRUE ("correcto") para todos los demás valores de estado.

Comentarios

La rutina FsRtlCancellableWaitForMultipleObjects ejecuta una operación de espera cancelable en objetos de distribuidor. Si el usuario o la aplicación finalizan el subproceso, o si CancelSynchronousIo publica una solicitud de cancelación en un IRP subproceso (IRP sincrónico) asociado al subproceso, se cancela la espera.

La rutina FsRtlCancellableWaitForMultipleObjects se diseñó para admitir las directrices de finalización o cancelación de E/ S a partir de Windows Vista. El objetivo de estas directrices es permitir que los usuarios (o aplicaciones) finalicen rápidamente las aplicaciones. Esto, a su vez, requiere que las aplicaciones tengan la capacidad de finalizar rápidamente los subprocesos que ejecutan E/S, así como las operaciones de E/S actuales. Esta rutina proporciona una manera de bloquear los subprocesos de usuario (es decir, esperar) en el kernel para la finalización de E/S, los objetos de distribuidor o las variables de sincronización de una manera que permita que la espera se cancele fácilmente. Esta rutina también permite que la espera del subproceso finalice si un usuario o una aplicación finalizan el subproceso.

Por ejemplo, un redirector puede necesitar crear uno o varios IRP secundarios para procesar un IRP en modo de usuario y esperar sincrónicamente a que se completen los IRP secundarios. Una manera de hacerlo es configurar un evento que se señalará mediante la rutina de finalización del IRP secundario y, a continuación, esperar a que se señale el evento. A continuación, para realizar una operación de espera cancelable, se llama A FsRtlCancellableWaitForMultipleObjects pasando el evento asociado al IRP secundario, así como al IRP en modo de usuario original. La espera del subproceso para que se indique el evento se cancela si se produce un evento de finalización pendiente o si se cancela el IRP en modo de usuario original.

Tenga en cuenta que la finalización de la espera no cancela automáticamente ninguna operación de E/S emitida por el autor de la llamada, que el autor de la llamada debe controlar por separado.

Cada objeto de subproceso tiene una matriz integrada de bloques de espera que se pueden usar para esperar varios objetos simultáneamente. Siempre que sea posible, la matriz integrada de bloques de espera debe usarse en una operación wait-multiple, ya que no es necesario asignar ningún almacenamiento de bloque de espera adicional y desasignarse más adelante. Sin embargo, si el número de objetos que se deben esperar simultáneamente es mayor que el número de bloques de espera integrados, use el parámetro WaitBlockArray para especificar un conjunto alternativo de bloques de espera que se usarán en la operación de espera. Los controladores solo necesitan asignar un búfer de memoria suficientemente grande para WaitBlockArray. No es necesario inicializar el búfer y los controladores pueden tratarlo como una estructura opaca. El búfer se puede liberar una vez que se devuelve la rutina.

Si Count es mayor que MAXIMUM_WAIT_OBJECTS o si WaitBlockArray es NULL y Count es mayor que THREAD_WAIT_OBJECTS, el sistema emite la comprobación de errores 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.

Se aplica una consideración especial cuando el parámetro ObjectArray pasado a FsRtlCancellableWaitForMultipleObjects es una exclusión mutua. Si el objeto distribuidor en el que se espera es una exclusión mutua, la entrega de APC es la misma que para todos los demás objetos de distribuidor durante la espera. Sin embargo, una vez que FsRtlCancellableWaitForMultipleObjects devuelve con STATUS_SUCCESS y el subproceso contiene realmente la exclusión mutua, solo se entregan las API de modo kernel especiales. La entrega de todas las demás API, tanto en modo kernel como en modo de usuario, está deshabilitada. Esta restricción en la entrega de LAS API persiste hasta que se libera la exclusión mutua.

Una exclusión mutua solo se puede adquirir de forma recursiva solo las veces minLONG. Si se supera este límite, la rutina genera una excepción de STATUS_MUTANT_LIMIT_EXCEEDED.

Se debe llamar a FsRtlCancellableWaitForMultipleObjects en IRQL PASSIVE_LEVEL si el parámetro Irp opcional apunta a un IRP válido. Si no se usa el parámetro Irp , se puede llamar a la rutina en IRQL menor o igual que APC_LEVEL. El autor de la llamada puede deshabilitar las API de kernel normales, si es necesario, mediante una llamada a las rutinas KeEnterCriticalRegion o FsRtlEnterFileSystem . Sin embargo, las API de kernel especiales no deben estar deshabilitadas.

FsRtlCancellableWaitForMultipleObjects se validará en las compilaciones de depuración si irQL es mayor o igual que APC_LEVEL y el parámetro Irp apunta a un IRP válido.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	vea la sección Comentarios.
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm), SpNoWait(storport)