Функция CreateMutexExA (synchapi.h)

Статья
03/08/2023

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

Синтаксис

HANDLE CreateMutexExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Параметры

[in, optional] lpMutexAttributes

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

Элемент lpSecurityDescriptor указывает дескриптор безопасности для нового мьютекса. Если lpMutexAttributesNULL, мьютекс получает дескриптор безопасности по умолчанию. Списки управления доступом в дескрипторе безопасности по умолчанию для мьютекса получены из первичного или олицетворения маркера создателя. Дополнительные сведения см. в службы "Безопасность объектов синхронизации и права доступа".

[in, optional] lpName

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

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

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

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

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

[in] dwFlags

Этот параметр может иметь значение 0 или следующее значение.

Ценность	Значение
CREATE_MUTEX_INITIAL_OWNER 0x00000001	Создатель объекта является первоначальным владельцем мьютекса.

[in] dwDesiredAccess

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

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

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

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

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

Замечания

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

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

Состояние объекта мьютекса сигнализируется, когда он не принадлежит ни одному потоку. Создание потока может использовать параметр dwFlags для запроса немедленного владения мьютексом. В противном случае поток должен использовать одну из функций ожидания для запроса владения. Когда состояние мьютекса сигнализирует, один ожидающий поток получает владение, состояние мьютекса изменяется на незначаемое, а функция ожидания возвращается. Только один поток может принадлежать мьютексу в любое время. В потоке владения используется функция ReleaseMutex для освобождения его владения.

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

Два или более процессов могут вызывать CreateMutex для создания того же именованного мьютекса. Первый процесс фактически создает мьютекс, а последующие процессы с достаточными правами доступа просто открывают дескриптор существующего мьютекса. Это позволяет нескольким процессам получать дескриптора одного и того же мьютекса, при этом пользователю необходимо обеспечить запуск процесса создания. При использовании этого метода не следует использовать флаг CREATE_MUTEX_INITIAL_OWNER; в противном случае может быть трудно определить, какой процесс имеет начальное владение.

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

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

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

Заметка

Заголовок synchapi.h определяет CreateMutexEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

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

См. также

CloseHandle

объекты Мьютекса

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

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