Funzione ReleaseSemaphore (synchapi.h)

Articolo
08/26/2023

Aumenta il conteggio dell'oggetto semaforo specificato in base a una quantità specificata.

Sintassi

BOOL ReleaseSemaphore(
  [in]            HANDLE hSemaphore,
  [in]            LONG   lReleaseCount,
  [out, optional] LPLONG lpPreviousCount
);

Parametri

[in] hSemaphore

Handle per l'oggetto semaforo. La funzione CreateSemaphore o OpenSemaphore restituisce questo handle.

Questo handle deve avere il diritto di accesso SEMAPHORE_MODIFY_STATE . Per altre informazioni, vedere Sicurezza oggetti di sincronizzazione e diritti di accesso.

[in] lReleaseCount

Quantità in base alla quale il conteggio corrente dell'oggetto semaforo deve essere aumentato. Il valore deve essere maggiore di zero. Se l'importo specificato causerebbe che il conteggio del semaforo superi il numero massimo specificato quando è stato creato il semaforo, il conteggio non viene modificato e la funzione restituisce FALSE.

[out, optional] lpPreviousCount

Puntatore a una variabile per ricevere il conteggio precedente per il semaforo. Questo parametro può essere NULL se il conteggio precedente non è obbligatorio.

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 informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Lo stato di un oggetto semaforo viene segnalato quando il conteggio è maggiore di zero e nonsignaled quando il numero è uguale a zero. Il processo che chiama la funzione CreateSemaphore specifica il conteggio iniziale del semaforo. Ogni volta che un thread in attesa viene rilasciato a causa dello stato segnalato dal semaforo, il conteggio del semaforo è diminuito di uno.

In genere, un'applicazione usa un semaforo per limitare il numero di thread usando una risorsa. Prima che un thread usi la risorsa, specifica l'handle del semaforo in una chiamata a una delle funzioni di attesa. Quando la funzione di attesa viene restituita, diminuisce il conteggio del semaforo per uno. Al termine dell'uso della risorsa, il thread chiama ReleaseSemaphore per aumentare il numero di semafori per uno.

Un altro uso di ReleaseSemaphore è durante l'inizializzazione di un'applicazione. L'applicazione può creare un semaforo con un conteggio iniziale pari a zero. In questo modo lo stato del semaforo viene impostato su non firmato e impedisce a tutti i thread di accedere alla risorsa protetta. Al termine dell'inizializzazione dell'applicazione, usa ReleaseSemaphore per aumentare il conteggio al relativo valore massimo, per consentire l'accesso normale alla risorsa protetta.

Non è possibile ridurre il conteggio degli oggetti semafori usando ReleaseSemaphore, perché lReleaseCount non può essere un numero negativo. Per limitare o ridurre temporaneamente l'accesso, creare un ciclo in cui si chiama la funzione WaitForSingleObject con un intervallo di timeout pari a zero fino a quando il numero di semafori non è stato ridotto sufficientemente. Si noti che altri thread possono ridurre il conteggio durante l'esecuzione di questo ciclo. Per ripristinare l'accesso, chiamare ReleaseSemaphore con il numero di versioni uguale al numero di volte in cui waitForSingleObject è stato chiamato nel ciclo.

Esempio

Per un esempio che usa ReleaseSemaphore, vedere Uso di oggetti Semaphore.

Requisiti

Requisito	Valore
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 (includere Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Libreria	Kernel32.lib
DLL	Kernel32.dll