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 .
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.

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

CloseHandle

Objetos semáforos

Funções de sincronização