Função CreateSemaphoreA (winbase.h)
Cria ou abre um objeto de semáforo nomeado ou sem nome.
Para especificar uma máscara de acesso para o objeto, use a função CreateSemaphoreEx .
Sintaxe
HANDLE CreateSemaphoreA(
[in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
[in] LONG lInitialCount,
[in] LONG lMaximumCount,
[in, optional] LPCSTR lpName
);
Parâmetros
[in, optional] lpSemaphoreAttributes
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . Se esse parâmetro for NULL, o identificador não poderá ser herdado por processos filho.
O membro lpSecurityDescriptor da estrutura especifica um descritor de segurança para o novo semáforo. Se esse parâmetro for NULL, o semáforo receberá um descritor de segurança padrão. As ACLs no descritor de segurança padrão para um semáforo vêm do token primário ou de representação do criador.
[in] lInitialCount
A contagem inicial para o objeto semáforo. Esse valor deve ser maior ou igual a zero e menor ou igual a lMaximumCount. O estado de um semáforo é sinalizado quando sua contagem é maior que zero e não atribuída quando é zero. A contagem é reduzida em um sempre que uma função de espera libera um thread que estava esperando pelo semáforo. A contagem é aumentada por um valor especificado chamando a função ReleaseSemaphore .
[in] lMaximumCount
A contagem máxima para o objeto semáforo. Esse valor deve ser maior que zero.
[in, optional] lpName
O nome do objeto semáforo. O nome é limitado a MAX_PATH caracteres. A comparação de nomes diferencia maiúsculas de minúsculas.
Se lpName corresponder ao nome de um objeto de semáforo nomeado existente, essa função solicitará o acesso SEMAPHORE_ALL_ACCESS direito. Nesse caso, os parâmetros lInitialCount e lMaximumCount são ignorados porque já foram definidos pelo processo de criação. Se o parâmetro lpSemaphoreAttributes não for NULL, ele determinará se o identificador pode ser herdado, mas seu membro descritor de segurança será ignorado.
Se lpName for NULL, o objeto semáforo será criado sem um nome.
Se lpName corresponder ao nome de um evento existente, mutex, temporizador de espera, trabalho ou objeto de mapeamento de arquivo, a função falhará e a função GetLastError retornará ERROR_INVALID_HANDLE. Isso ocorre porque esses objetos compartilham o mesmo namespace.
O nome pode ter um prefixo "Global" ou "Local" para criar explicitamente o objeto no namespace global ou de sessão. O restante do nome pode conter qualquer caractere, exceto o caractere de barra invertida (\). Para obter mais informações, consulte Namespaces de objeto kernel. A troca rápida de usuário é implementada usando sessões dos Serviços de Terminal. Os nomes de objetos kernel devem seguir as diretrizes descritas para os Serviços de Terminal para que os aplicativos possam dar suporte a vários usuários.
O objeto pode ser criado em um namespace privado. Para obter mais informações, consulte Namespaces de objeto.
Valor retornado
Se a função for bem-sucedida, o valor retornado será um identificador para o objeto semáforo. Se o objeto semáforo nomeado existir antes da chamada de função, a função retornará um identificador para o objeto existente e GetLastError retornará ERROR_ALREADY_EXISTS.
Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.
Comentários
O identificador retornado por CreateSemaphore tem o SEMAPHORE_ALL_ACCESS direito de acesso; ele pode ser usado em qualquer função que exija um identificador para um objeto semáforo, desde que o chamador tenha recebido acesso. Se um semáforo for criado a partir de um serviço ou de um thread que esteja representando um usuário diferente, você poderá aplicar um descritor de segurança ao semáforo ao criá-lo ou alterar o descritor de segurança padrão para o processo de criação alterando sua DACL padrão. Para obter mais informações, consulte Segurança do objeto de sincronização e direitos de acesso.
O estado de um objeto semáforo é sinalizado quando sua contagem é maior que zero e não atribuída quando sua contagem é igual a zero. O parâmetro lInitialCount especifica a contagem inicial. A contagem nunca pode ser menor que zero ou maior do que o valor especificado no parâmetro lMaximumCount .
Qualquer thread do processo de chamada pode especificar o identificador de objeto semáforo em uma chamada para uma das funções de espera. As funções de espera de objeto único retornam quando o estado do objeto especificado é sinalizado. As funções de espera de vários objetos podem ser instruídas a retornar quando qualquer um ou quando todos os objetos especificados forem sinalizados. Quando uma função de espera retorna, o thread de espera é liberado para continuar sua execução. Sempre que um thread conclui uma espera por um objeto semáforo, a contagem do objeto semáforo é decrementada por um. Quando o thread for concluído, ele chamará a função ReleaseSemaphore , que incrementa a contagem do objeto semáforo.
Vários processos podem ter identificadores do mesmo objeto semáforo, permitindo o uso do objeto para sincronização entre processos. Os seguintes mecanismos de compartilhamento de objetos estão disponíveis:
- Um processo filho criado pela função CreateProcess poderá herdar um identificador para um objeto semáforo se o parâmetro lpSemaphoreAttributes da herança habilitada para CreateSemaphore.
- Um processo pode especificar o identificador de objeto semáforo em uma chamada para a função DuplicateHandle para criar um identificador duplicado que pode ser usado por outro processo.
- Um processo pode especificar o nome de um objeto semáforo em uma chamada para a função [OpenSemaphore](/windows/win32/api/synchapi/nf-synchapi-opensemaphorew) ou CreateSemaphore.
Exemplos
Para obter um exemplo que usa CreateSemaphore, consulte Usando objetos semáforos.
Requisitos
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |