Função CreateSemaphoreA (winbase.h)

Artigo
06/10/2023

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.

Use a função CloseHandle para fechar o identificador. O sistema fecha o identificador automaticamente quando o processo é encerrado. O objeto semáforo é destruído quando seu último identificador foi fechado.

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