Функция CreateSemaphoreA (winbase.h)

Статья
06/10/2023

Создает или открывает именованный или неименованный объект семафора.

Чтобы указать маску доступа для объекта, используйте функцию CreateSemaphoreEx .

Синтаксис

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

Параметры

[in, optional] lpSemaphoreAttributes

Указатель на структуру SECURITY_ATTRIBUTES . Если этот параметр имеет значение NULL, дескриптор не может наследоваться дочерними процессами.

Элемент lpSecurityDescriptor структуры указывает дескриптор безопасности для нового семафора. Если этот параметр имеет значение NULL, семафор получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для семафора поступают из основного маркера или маркера олицетворения создателя.

[in] lInitialCount

Начальное число для объекта семафора. Это значение должно быть больше или равно нулю и меньше или равно lMaximumCount. Состояние семафора сигнализируется, когда его число больше нуля, и без знака, когда оно равно нулю. Количество уменьшается на один раз, когда функция ожидания освобождает поток, ожидающий семафора. Количество увеличивается на указанную величину путем вызова функции ReleaseSemaphore .

[in] lMaximumCount

Максимальное число объектов семафора. Это значение должно быть больше нуля.

[in, optional] lpName

Имя объекта семафора. Имя ограничено MAX_PATH символами. При сравнении имен учитывается регистр.

Если lpName соответствует имени существующего именованного объекта семафора, эта функция запрашивает право доступа SEMAPHORE_ALL_ACCESS . В этом случае параметры lInitialCount и lMaximumCount игнорируются, так как они уже заданы процессом создания. Если параметр lpSemaphoreAttributes не равен NULL, он определяет, можно ли наследовать дескриптор, но его член дескриптора безопасности игнорируется.

Если lpName имеет значение NULL, объект семафора создается без имени.

Если lpName соответствует имени существующего события, мьютекса, таймера ожидания, задания или объекта сопоставления файлов, функция завершается сбоем и функция GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит потому, что эти объекты используют одно и то же пространство имен.

Имя может иметь префикс "Global" или "Local" для явного создания объекта в глобальном пространстве имен или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе Пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать нескольких пользователей.

Объект можно создать в частном пространстве имен. Дополнительные сведения см. в разделе Пространства имен объектов.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение является дескриптором для объекта семафора. Если именованный объект семафор существовал до вызова функции, функция возвращает дескриптор существующему объекту, а GetLastError возвращает ERROR_ALREADY_EXISTS.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Дескриптор, возвращаемый CreateSemaphore, имеет право доступа SEMAPHORE_ALL_ACCESS ; Его можно использовать в любой функции, требующей дескриптора объекта семафора, при условии, что вызывающему объекту предоставлен доступ. Если семафор создается из службы или потока, который олицетворяет другого пользователя, можно либо применить дескриптор безопасности к семафору при его создании, либо изменить дескриптор безопасности по умолчанию для процесса создания, изменив его daCL по умолчанию. Дополнительные сведения см. в разделе Синхронизация безопасности объектов и прав доступа.

Состояние объекта семафора сигнализируется, когда его число больше нуля, и без знака, когда его число равно нулю. Параметр lInitialCount указывает начальное число. Число никогда не может быть меньше нуля или больше значения, указанного в параметре lMaximumCount .

Любой поток вызывающего процесса может указать дескриптор объекта семафора в вызове одной из функций ожидания. Функции ожидания с одним объектом возвращаются при сигнале о состоянии указанного объекта. Функции ожидания с несколькими объектами можно указать, что они возвращаются при получении сигнала о любом объекте или при получении сигнала для всех указанных объектов. При возврате функции ожидания поток ожидания освобождается для продолжения выполнения. Каждый раз, когда поток завершает ожидание объекта семафора, количество объекта семафора уменьшается на единицы. По завершении потока вызывается функция ReleaseSemaphore , которая увеличивает количество объектов семафора.

Несколько процессов могут иметь дескриптор одного объекта семафора, что позволяет использовать объект для синхронизации между процессами. Доступны следующие механизмы совместного использования объектов:

Дочерний процесс, созданный функцией CreateProcess, может наследовать дескриптор объекта семафора, если параметр lpSemaphoreAttributes наследования с поддержкой CreateSemaphore.
Процесс может указать дескриптор объекта семафора в вызове функции DuplicateHandle , чтобы создать повторяющийся дескриптор, который может использоваться другим процессом.
Процесс может указать имя объекта семафора при вызове функции [OpenSemaphore](/windows/win32/api/synchapi/nf-synchapi-opensemaphorew) или CreateSemaphore.

Используйте функцию CloseHandle , чтобы закрыть дескриптор. Система автоматически закрывает дескриптор при завершении процесса. Объект семафора уничтожается при закрытии последнего дескриптора.

Примеры

Пример использования CreateSemaphore см. в разделе Использование объектов семафора.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll