Funzione RegisterWaitForSingleObject (winbase.h)

Articolo
03/08/2023

Indirizza un thread di attesa nel pool di thread per attendere l'oggetto. Il thread di attesa accoda la funzione di callback specificata al pool di thread quando si verifica una delle operazioni seguenti:

L'oggetto specificato si trova nello stato segnalato.
L'intervallo di timeout trascorso.

Sintassi

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

Parametri

[out] phNewWaitObject

Puntatore a una variabile che riceve un handle di attesa sul ritorno. Si noti che un handle di attesa non può essere usato nelle funzioni che richiedono un handle di oggetti, ad esempio CloseHandle.

[in] hObject

Handle per l'oggetto. Per un elenco dei tipi di oggetto i cui handle possono essere specificati, vedere la sezione Osservazioni seguente.

Se questo handle viene chiuso mentre l'attesa è ancora in sospeso, il comportamento della funzione non è definito.

Gli handle devono avere il diritto di accesso SYNC . Per altre informazioni, vedere Diritti di accesso standard.

[in] Callback

Puntatore alla funzione definita dall'applicazione di tipo WAITORTIMERCALLBACK da eseguire quando hObject si trova nello stato segnalato o viene trascorso dwMilliseconds . Per altre informazioni, vedere WaitOrTimerCallback.

[in, optional] Context

Valore singolo passato alla funzione di callback.

[in] dwMilliseconds

Intervallo di timeout, in millisecondi. La funzione restituisce se l'intervallo viene trascorso, anche se lo stato dell'oggetto non è assegnato. Se dwMilliseconds è zero, la funzione verifica lo stato dell'oggetto e restituisce immediatamente. Se dwMilliseconds è INFINITE, l'intervallo di timeout della funzione non scade mai.

[in] dwFlags

Questo parametro può essere uno o più dei valori seguenti.

Per informazioni sull'uso di questi valori con oggetti che rimangono segnalati, vedere la sezione Osservazioni.

Valore	Significato
WT_EXECUTEDEFAULT 0x00000000	Per impostazione predefinita, la funzione di callback viene accodata a un thread di lavoro non I/O.
WT_EXECUTEINIOTHREAD 0x00000001	Questo flag non viene usato. Windows Server 2003 e Windows XP: La funzione di callback viene accodata a un thread di lavoro di I/O. Questo flag deve essere usato se la funzione deve essere eseguita in un thread che attende in uno stato avvisabile. I thread di lavoro di I/O sono stati rimossi a partire da Windows Vista e Windows Server 2008.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	La funzione di callback viene accodata a un thread che non termina mai. Non garantisce che lo stesso thread venga usato ogni volta. Questo flag deve essere usato solo per le attività brevi o potrebbe influire su altre operazioni di attesa. Questo flag deve essere impostato se il thread chiama le funzioni che usano le API. Per altre informazioni, vedere Chiamate di procedura asincrone. Si noti che attualmente nessun thread di lavoro è veramente persistente, anche se nessun thread di lavoro termina se sono presenti richieste di I/O in sospeso.
WT_EXECUTEINWAITTHREAD 0x00000004	La funzione di callback viene richiamata dal thread di attesa stesso. Questo flag deve essere usato solo per le attività brevi o potrebbe influire su altre operazioni di attesa. I deadlock possono verificarsi se un altro thread acquisisce un blocco esclusivo e chiama la funzione UnregisterWait o UnregisterWaitEx mentre la funzione di callback sta tentando di acquisire lo stesso blocco.
WT_EXECUTELONGFUNCTION 0x00000010	La funzione di callback può eseguire una lunga attesa. Questo flag consente al sistema di decidere se deve creare un nuovo thread.
WT_EXECUTEONLYONCE 0x00000008	Il thread non attenderà più l'handle dopo che la funzione di callback è stata chiamata una volta. In caso contrario, il timer viene reimpostato ogni volta che l'operazione di attesa viene completata fino all'annullamento dell'operazione di attesa.
WT_TRANSFER_IMPERSONATION 0x00000100	Le funzioni di callback useranno il token di accesso corrente, ovvero un processo o un token di rappresentazione. Se questo flag non è specificato, le funzioni di callback vengono eseguite solo con il token di processo. Windows XP: Questo flag non è supportato fino a quando Windows XP con SP2 e Windows Server 2003.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni sull'errore estese, chiamare
GetLastError.

Commenti

Quando necessario, i nuovi thread di attesa vengono creati automaticamente. L'operazione di attesa viene eseguita da un thread di attesa dal pool di thread. La routine di callback viene eseguita da un thread di lavoro quando lo stato dell'oggetto viene segnalato o trascorso l'intervallo di timeout. Se dwFlags non è WT_EXECUTEONLYONCE, il timer viene reimpostato ogni volta che l'evento viene segnalato o l'intervallo di timeout trascorso.

Al termine dell'attesa, è necessario chiamare la funzione UnregisterWait o UnregisterWaitEx per annullare l'operazione di attesa. Le operazioni di attesa che usano WT_EXECUTEONLYONCE devono essere annullate. Non effettuare una chiamata di blocco a una di queste funzioni dall'interno della funzione di callback.

Si noti che non è necessario eseguire l'impulso di un oggetto evento passato a RegisterWaitForSingleObject, perché il thread di attesa potrebbe non rilevare che l'evento viene segnalato prima della reimpostazione. Non è consigliabile registrare un oggetto che rimane segnalato ,ad esempio un evento di reimpostazione manuale o un processo terminato, a meno che non si imposta il flag di WT_EXECUTEONLYONCE o di WT_EXECUTEINWAITTHREAD . Per altri flag, la funzione di callback potrebbe essere chiamata troppo volte prima che l'evento venga reimpostato.

La funzione modifica lo stato di alcuni tipi di oggetti di sincronizzazione. La modifica si verifica solo per l'oggetto lo stato segnalato ha causato l'soddisfatta della condizione di attesa. Ad esempio, il conteggio di un oggetto semaforo è ridotto di uno.

La funzione RegisterWaitForSingleObject può attendere gli oggetti seguenti:

Notifica di modifica
Input della console
Evento
Notifica delle risorse di memoria
Mutex
Processo
Semaphore
Thread
Timer attendebile

Per altre informazioni, vedere Oggetti di sincronizzazione.

Per impostazione predefinita, il pool di thread ha un massimo di 500 thread. Per aumentare questo limite, usare la macro WT_SET_MAX_THREADPOOL_THREAD definita in WinNT.h.

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

Usare questa macro quando si specifica il parametro dwFlags . I parametri della macro sono i flag desiderati e il nuovo limite (fino a (2<<16)-1 thread. Si noti tuttavia che l'applicazione può migliorare le prestazioni mantenendo basso il numero di thread di lavoro.

L'elemento di lavoro e tutte le funzioni chiamate devono essere thread-pool safe. Pertanto, non è possibile chiamare una chiamata asincrona che richiede un thread persistente, ad esempio la funzione RegNotifyChangeKeyValue , dall'ambiente di callback predefinito. Impostare invece il valore massimo del pool di thread uguale al pool di thread usando la funzione SetThreadPoolThreadMaximum e SetThreadpoolThreadMinimum oppure creare un thread personalizzato usando la funzione CreateThread . Per l'API del pool di thread originale, specificare WT_EXECUTEINPERSISTENTTHREAD usando la funzione QueueUserWorkItem .

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0500 o versione successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll