Funzione SleepEx (synchapi.h)

Articolo
08/26/2023

Sospende il thread corrente fino a quando non viene soddisfatta la condizione specificata. L'esecuzione riprende quando si verifica una delle operazioni seguenti:

Viene chiamata una funzione di callback di completamento I/O.
Una chiamata di procedura asincrona (APC) viene accodata al thread.
Intervallo di timeout trascorso.

Sintassi

DWORD SleepEx(
  [in] DWORD dwMilliseconds,
  [in] BOOL  bAlertable
);

Parametri

[in] dwMilliseconds

Intervallo di tempo per il quale l'esecuzione deve essere sospesa, in millisecondi.

Un valore pari a zero fa sì che il thread rinunci al resto della sezione temporale a qualsiasi altro thread pronto per l'esecuzione. Se non sono disponibili altri thread pronti per l'esecuzione, la funzione viene restituita immediatamente e il thread continua l'esecuzione. Windows XP: Il valore zero fa sì che il thread rinunci al resto della sezione temporale a qualsiasi altro thread di uguale priorità pronto per l'esecuzione. Se non sono presenti altri thread con priorità uguale pronti per l'esecuzione, la funzione restituisce immediatamente e il thread continua l'esecuzione. Questo comportamento è cambiato a partire da Windows Server 2003.

Il valore INFINITE indica che la sospensione non deve scadere.

[in] bAlertable

Se questo parametro è FALSE, la funzione non restituisce finché non è trascorso il periodo di timeout. Se si verifica un callback di completamento di I/O, la funzione non restituisce immediatamente e la funzione di completamento di I/O non viene eseguita. Se un APC viene accodato al thread, la funzione non restituisce immediatamente e la funzione APC non viene eseguita.

Se il parametro è TRUE e il thread che ha chiamato questa funzione è lo stesso thread che ha chiamato la funzione di I/O estesa (ReadFileEx o WriteFileEx), la funzione restituisce quando è trascorso il periodo di timeout o quando si verifica una funzione di callback di completamento I/O. Se si verifica un callback di completamento di I/O, viene chiamata la funzione di completamento di I/O. Se un APC viene accodato al thread (QueueUserAPC), la funzione restituisce quando è trascorso il periodo di timeout o quando viene chiamata la funzione APC.

Valore restituito

Il valore restituito è zero se l'intervallo di tempo specificato è scaduto.

Il valore restituito è WAIT_IO_COMPLETION se la funzione restituita a causa di una o più funzioni di callback di completamento I/O. Questa situazione può verificarsi solo se bAlertable è TRUE e se il thread che ha chiamato la funzione SleepEx è lo stesso thread che ha chiamato la funzione di I/O estesa.

Commenti

Questa funzione fa sì che un thread rinunci al resto della sezione temporale e diventi non eseguibile per un intervallo in base al valore di dwMilliseconds. Dopo aver superato l'intervallo di sospensione, il thread è pronto per l'esecuzione. Si noti che non è garantito l'esecuzione immediata di un thread pronto. Di conseguenza, il thread non verrà eseguito fino a quando non è trascorso un certo tempo arbitrario dopo l'intervallo di sospensione, in base alla frequenza di "tick" del sistema e al fattore di carico di altri processi. L'orologio di sistema "ticks" a una frequenza costante. Per aumentare l'accuratezza dell'intervallo di sospensione, chiamare la funzione timeGetDevCaps per determinare la risoluzione minima del timer supportata e la funzione timeBeginPeriod per impostare la risoluzione del timer sul valore minimo. Prestare attenzione quando si chiama timeBeginPeriod, poiché le chiamate frequenti possono influire in modo significativo sull'orologio di sistema, sull'utilizzo dell'alimentazione del sistema e sull'utilità di pianificazione. Se si chiama timeBeginPeriod, chiamarlo una volta all'inizio dell'applicazione e assicurarsi di chiamare la funzione timeEndPeriod alla fine dell'applicazione. Se si specificano 0 millisecondi, il thread rinuncerà al resto del periodo di tempo ma rimarrà pronto. Per altre informazioni, vedere Pianificazione delle priorità.

Questa funzione può essere usata con le funzioni ReadFileEx o WriteFileEx per sospendere un thread fino al completamento di un'operazione di I/O. Queste funzioni specificano una routine di completamento da eseguire al termine dell'operazione di I/O. Affinché venga eseguita la routine di completamento, il thread che ha chiamato la funzione di I/O deve trovarsi in uno stato di attesa avvisabile quando si verifica la funzione di callback di completamento. Un thread entra in uno stato di attesa avvisabile chiamando SleepEx, MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx o WaitForMultipleObjectsEx, con il parametro bAlertable della funzione impostato su TRUE.

Prestare attenzione quando si usa SleepEx negli scenari seguenti:

Codice che crea direttamente o indirettamente finestre (ad esempio, DDE e COM CoInitialize). Se un thread crea finestre, deve elaborare i messaggi. Le trasmissioni dei messaggi vengono inviate a tutte le finestre del sistema. Se si dispone di un thread che usa SleepEx con ritardo infinito, il sistema eseguirà il deadlock.
Thread sotto il controllo della concorrenza. Ad esempio, una porta di completamento I/O o un pool di thread limita il numero di thread associati che possono essere eseguiti. Se il numero massimo di thread è già in esecuzione, nessun thread associato aggiuntivo può essere eseguito fino al termine di un thread in esecuzione. Se un thread usa SleepEx con un intervallo pari a zero per attendere che uno dei thread associati aggiuntivi eselabori alcune operazioni, il processo potrebbe causare un deadlock.

Per questi scenari, usare MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, anziché SleepEx.

Windows Phone 8.1: questa funzione è supportata per Windows Phone app dello Store in Windows Phone 8.1 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	synchapi.h (include Windows.h in Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Libreria	Kernel32.lib; WindowsPhoneCore.lib in Windows Phone 8.1
DLL	KernelBase.dll Windows Phone 8,1; Kernel32.dll