Функция CreateSemaphoreA (winbase.h)
Создает или открывает именованный или неименованный объект семафора.
Чтобы указать маску доступа для объекта, используйте функцию 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, он определяет, можно ли наследовать дескриптор безопасности, но его член дескриптора безопасности игнорируется.
Если lpNameNULL, объект семафора создается без имени.
Если lpName соответствует имени существующего события, мьютекса, таймера ожидания, задания или объекта сопоставления файлов, функция завершается ошибкой, а функция GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит, так как эти объекты используют одно и то же пространство имен.
Имя может иметь префикс "Глобальный" или "Локальный", чтобы явно создать объект в глобальном или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать несколько пользователей.
Объект можно создать в частном пространстве имен. Дополнительные сведения см. в пространствах имен объектов.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение является дескриптором объекта семафора. Если перед вызовом функции существовал именованный объект семафора, функция возвращает дескриптор существующему объекту и GetLastError возвращает ERROR_ALREADY_EXISTS.
Если функция завершается ошибкой, возвращаемое значение равно NULL. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.
Замечания
Дескриптор, возвращаемый CreateSemaphore, имеет право SEMAPHORE_ALL_ACCESS доступа; его можно использовать в любой функции, требующей дескриптора для объекта семафора, при условии, что вызывающий объект предоставлен доступ. Если семафор создается из службы или потока, олицетворения другого пользователя, можно применить дескриптор безопасности к семафору при его создании или изменить дескриптор безопасности по умолчанию для процесса создания, изменив значение DACL по умолчанию. Дополнительные сведения см. в службы "Безопасность объектов синхронизации и права доступа".
Состояние объекта семафора сигнализируется, когда его число больше нуля и незначен, если его число равно нулю. Параметр lInitialCount указывает начальное число. Число не может быть меньше нуля или больше значения, указанного в параметре lMaximumCount.
Любой поток вызывающего процесса может указать дескриптор семафора-объекта в вызове одной из функций ожидания . Функции ожидания одного объекта возвращаются при сигнале состояния указанного объекта. Функции ожидания с несколькими объектами можно указать возвращать, когда любой из них или когда сигналируют все указанные объекты. Когда функция ожидания возвращается, поток ожидания освобождается для продолжения его выполнения. Каждый раз, когда поток завершает ожидание объекта семафора, количество объекта семафора уменьшается по одному. По завершении потока вызывается функция ReleaseSemaphore, которая увеличивает количество объектов семафора.
Несколько процессов могут иметь дескриптор одного и того же объекта семафора, что позволяет использовать объект для межпроцессной синхронизации. Доступны следующие механизмы совместного использования объектов:
- Дочерний процесс , созданный функцией createProcess createProcess, может наследовать дескриптор объекту семафора, если параметр lpSemaphoreAttributes наследования с поддержкой CreateSemaphore.
- Процесс может указать дескриптор семафора-объекта в вызове функции DuplicateHandle, чтобы создать повторяющийся дескриптор, который можно использовать другим процессом.
- Процесс может указать имя объекта семафора в вызове функции [OpenSemaphore](/windows/win32/api/synchapi/nf-synchapi-openemaphorew) или функции CreateSemaphore.
Примеры
Пример использования CreateSemaphoreсм. в разделе Using Semaphore Objects.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows XP [классические приложения | Приложения UWP] |
| минимальный поддерживаемый сервер | Windows Server 2003 [классические приложения | Приложения UWP] |
| целевая платформа | Виндоус |
| заголовка | winbase.h (включая Windows.h) |
| библиотеки |
Kernel32.lib |
| DLL | Kernel32.dll |