Funzione KeReleaseSemaphore (wdm.h)
La routine KeReleaseSemaphore rilascia l'oggetto semaforo specificato.
Sintassi
LONG KeReleaseSemaphore(
[in, out] PRKSEMAPHORE Semaphore,
[in] KPRIORITY Increment,
[in] LONG Adjustment,
[in] BOOLEAN Wait
);
Parametri
[in, out] Semaphore
Puntatore a un oggetto semaforo inizializzato per il quale il chiamante fornisce la risorsa di archiviazione.
[in] Increment
Specifica l'incremento di priorità da applicare se il rilascio del semaforo determina la soddisfazione di un'attesa.
[in] Adjustment
Specifica un valore da aggiungere al conteggio del semaforo corrente. Questo valore deve essere positivo.
[in] Wait
Specifica se la chiamata a KeReleaseSemaphore deve essere seguita immediatamente da una chiamata a una delle routine KeWaitXxx. Se TRUE, la chiamata KeReleaseSemaphore deve essere seguita da una chiamata a KeWaitForMultipleObjects, KeWaitForMutexObjecto KeWaitForSingleObject. Per altre informazioni, vedere la sezione Osservazioni seguente.
Valore restituito
Se il valore restituito è zero, lo stato precedente dell'oggetto semaforo non viene segnalato.
Osservazioni
KeReleaseSemaphore fornisce un aumento della priorità di runtime per i thread in attesa. Se questa chiamata imposta il semaforo sullo stato segnalato, il conteggio dei semafori viene incrementato dal valore specificato. Il chiamante può anche specificare se chiamerà una delle routine KeWaitXxx non appena KeReleaseSemaphore restituisce il controllo.
Il rilascio di un oggetto semaforo determina l'aumento del numero di semafori dal valore del parametro Adjustment. Se il valore risultante è maggiore del limite dell'oggetto semaforo, il conteggio non viene modificato e viene generata un'eccezione, STATUS_SEMAPHORE_LIMIT_EXCEEDED.
Aumentando il conteggio degli oggetti semaforo, il semaforo raggiunge uno stato segnalato e viene effettuato un tentativo di soddisfare il maggior numero possibile di attese sull'oggetto semaforo.
La routine KeReleaseSemaphore potrebbe generare temporaneamente irQL. Se il parametro wait è FALSE, la routine, prima che venga restituita, ripristina il runtime di integrazione sul valore originale che aveva all'inizio della chiamata.
Se Wait = TRUE, la routine restituisce senza abbassare irQL. In questo caso, la chiamata keReleaseSemaphore deve essere seguita immediatamente da una chiamata KeWaitXxx. Impostando Wait = TRUE, il chiamante può impedire che si verifichi un cambio di contesto non necessario tra la chiamata KeReleaseSemaphore e la chiamata KeWaitXxx. La routine KeWaitXxx, prima che venga restituita, ripristina il valore originale di IRQL all'inizio della chiamata KeReleaseSemaphore. Sebbene IRQL disabiliti i commutatori di contesto tra le due chiamate, queste chiamate non possono essere usate in modo affidabile come inizio e fine di un'operazione atomica. Ad esempio, tra queste due chiamate, un thread in esecuzione contemporaneamente in un altro processore potrebbe modificare lo stato dell'oggetto semaforo o della destinazione dell'attesa.
Avvertimento
Una routine del driver di paging o di thread visualizzabile da paging eseguita in IRQL = PASSIVE_LEVEL non deve mai chiamare KeReleaseSemaphore con il parametro wait impostato su TRUE. Tale chiamata causa un errore di pagina irreversibile se la funzione chiamante viene visualizzata tra le chiamate a KeReleaseSemaphore e KeWaitXxx.
Per altre informazioni sugli oggetti semaforo, vedere Semaphore Objects.
I chiamanti di KeReleaseSemaphore devono essere eseguiti in IRQL <= DISPATCH_LEVEL purché Wait sia impostato su FALSE. In caso contrario, il chiamante deve essere in esecuzione in IRQL = PASSIVE_LEVEL.