Funzione CreateSemaphoreA (winbase.h)

Articolo
06/10/2023

Crea o apre un oggetto semaforo denominato o senza nome.

Per specificare una maschera di accesso per l'oggetto, usare la funzione CreateSemaphoreEx .

Sintassi

HANDLE CreateSemaphoreA(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCSTR                lpName
);

Parametri

[in, optional] lpSemaphoreAttributes

Puntatore a una struttura SECURITY_ATTRIBUTES . Se questo parametro è NULL, l'handle non può essere ereditato dai processi figlio.

Il membro lpSecurityDescriptor della struttura specifica un descrittore di sicurezza per il nuovo semaforo. Se questo parametro è NULL, il semaforo ottiene un descrittore di sicurezza predefinito. Gli ACL nel descrittore di sicurezza predefinito per un semaforo provengono dal token primario o di rappresentazione del creatore.

[in] lInitialCount

Conteggio iniziale dell'oggetto semaforo. Questo valore deve essere maggiore o uguale a zero e minore o uguale a lMaximumCount. Lo stato di un semaforo viene segnalato quando il suo conteggio è maggiore di zero e nonsignaled quando è zero. Il conteggio viene ridotto di uno ogni volta che una funzione di attesa rilascia un thread in attesa del semaforo. Il conteggio viene aumentato di una quantità specificata chiamando la funzione ReleaseSemaphore .

[in] lMaximumCount

Numero massimo per l'oggetto semaforo. Il valore deve essere maggiore di zero.

[in, optional] lpName

Nome dell'oggetto semaforo. Il nome è limitato a MAX_PATH caratteri. Il confronto tra nomi è distinzione tra maiuscole e minuscole.

Se lpName corrisponde al nome di un oggetto denominato semaforo esistente, questa funzione richiede il diritto di accesso SEMAPHORE_ALL_ACCESS . In questo caso, i parametri lInitialCount e lMaximumCount vengono ignorati perché sono già stati impostati dal processo di creazione. Se il parametro lpSemaphoreAttributes non è NULL, determina se l'handle può essere ereditato, ma il membro del descrittore di sicurezza viene ignorato.

Se lpName è NULL, l'oggetto semaforo viene creato senza un nome.

Se lpName corrisponde al nome di un evento esistente, mutex, timer in attesa, processo o oggetto mapping file, la funzione ha esito negativo e la funzione GetLastError restituisce ERROR_INVALID_HANDLE. Ciò si verifica perché questi oggetti condividono lo stesso spazio dei nomi.

Il nome può avere un prefisso "Global" o "Local" per creare in modo esplicito l'oggetto nello spazio dei nomi globale o sessione. Il resto del nome può contenere qualsiasi carattere, ad eccezione del carattere barra rovesciata (\). Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel. Il passaggio rapido degli utenti viene implementato usando le sessioni di Servizi terminal. I nomi degli oggetti kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.

L'oggetto può essere creato in uno spazio dei nomi privato. Per altre informazioni, vedere Spazi dei nomi degli oggetti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto semaforo. Se l'oggetto semaforo denominato esiste prima della chiamata alla funzione, la funzione restituisce un handle all'oggetto esistente e GetLastError restituisce ERROR_ALREADY_EXISTS.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

L'handle restituito da CreateSemaphore ha il diritto di accesso SEMAPHORE_ALL_ACCESS ; può essere usato in qualsiasi funzione che richiede un handle per un oggetto semaforo, a condizione che il chiamante abbia concesso l'accesso. Se un semaforo viene creato da un servizio o da un thread che rappresenta un utente diverso, è possibile applicare un descrittore di sicurezza al semaforo quando lo si crea o modificare il descrittore di sicurezza predefinito per il processo di creazione modificando l'elenco dati predefinito. Per altre informazioni, vedere Sicurezza oggetti di sincronizzazione e diritti di accesso.

Lo stato di un oggetto semaforo viene segnalato quando il numero è maggiore di zero e non firmato quando il numero è uguale a zero. Il parametro lInitialCount specifica il conteggio iniziale. Il conteggio non può mai essere minore di zero o maggiore del valore specificato nel parametro lMaximumCount .

Qualsiasi thread del processo chiamante può specificare l'handle dell'oggetto semaforo in una chiamata a una delle funzioni di attesa. Le funzioni di attesa a singolo oggetto restituiscono quando viene segnalato lo stato dell'oggetto specificato. Le funzioni di attesa a più oggetti possono essere indicate per restituire quando uno o quando vengono segnalati tutti gli oggetti specificati. Quando viene restituita una funzione di attesa, il thread in attesa viene rilasciato per continuare l'esecuzione. Ogni volta che un thread completa un'attesa per un oggetto semaforo, il conteggio dell'oggetto semaforo viene decrementato da uno. Al termine del thread, chiama la funzione ReleaseSemaphore , che incrementa il conteggio dell'oggetto semaforo.

Più processi possono avere handle dello stesso oggetto semaforo, consentendo l'uso dell'oggetto per la sincronizzazione tra processi. Sono disponibili i meccanismi di condivisione degli oggetti seguenti:

Un processo figlio creato dalla funzione CreateProcess può ereditare un handle in un oggetto semaforo se il parametro lpSemaphoreAttributes dell'ereditarietà abilitata per CreateSemaphore.
Un processo può specificare l'handle dell'oggetto semaforo in una chiamata alla funzione DuplicateHandle per creare un handle duplicato che può essere usato da un altro processo.
Un processo può specificare il nome di un oggetto semaforo in una chiamata alla funzione [OpenSemaphore](/windows/win32/api/synchapi/nf-synchapi-opensemaphorew) o CreateSemaphore.

Usare la funzione CloseHandle per chiudere l'handle. Il sistema chiude automaticamente l'handle al termine del processo. L'oggetto semaforo viene distrutto quando l'ultimo handle è stato chiuso.

Esempio

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

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	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll