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

Статья
03/13/2024

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

Синтаксис

HANDLE CreateSemaphoreExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCSTR                lpName,
                 DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Параметры

[in, optional] lpSemaphoreAttributes

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

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

[in] lInitialCount

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

[in] lMaximumCount

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

[in, optional] lpName

Указатель на строку, завершающую значение NULL, указывающую имя объекта семафора. Имя ограничено MAX_PATH символами. Сравнение имен учитывает регистр.

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

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

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

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

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

dwFlags

Этот параметр зарезервирован и должен иметь значение 0.

[in] dwDesiredAccess

Маска доступа для объекта семафора. Список прав доступа см. в службы "Безопасность объектов синхронизации" и "Права доступа".

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

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

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

Замечания

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

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

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2008 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

CloseHandle

объекты Семафора

Функции синхронизации

Поделиться через