Funzione RegisterWaitForSingleObject (winbase.h)

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 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 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)<<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

Vedere anche

Funzioni di sincronizzazione

Pooling dei thread

Annulla registrazioneWait

UnregisterWaitEx

Funzioni wait

Waitortimercallback