Função CreateSemaphoreExA (winbase.h)
Cria ou abre um objeto de semáforo nomeado ou sem nome e retorna um identificador para o objeto .
Sintaxe
HANDLE CreateSemaphoreExA(
[in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
[in] LONG lInitialCount,
[in] LONG lMaximumCount,
[in, optional] LPCSTR lpName,
DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parâmetros
[in, optional] lpSemaphoreAttributes
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . Se esse parâmetro for NULL, o identificador de semáforo 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
Um ponteiro para uma cadeia de caracteres terminada em nulo especificando 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 semaphore nomeado existente, os parâmetros lInitialCount e lMaximumCount serã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.
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.
dwFlags
Esse parâmetro é reservado e deve ser 0.
[in] dwDesiredAccess
A máscara de acesso para o objeto semáforo. Para obter uma lista de direitos de acesso, confira Direitos de Acesso e Segurança do Objeto de Sincronização.
Retornar valor
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 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 CreateSemaphoreEx .
- 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 o [OpenSemaphore](.. /synchapi/nf-synchapi-signalobjectandwait.md) ou a função CreateSemaphoreEx .
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de