winbase.h

CreateMutex

La función CreateMutex crea objeto mutex con o sin nombre.

Sintaxis

HANDLE CreateMutex(
    LPSECURITY_ATTRIBUTES lpMutexAttributes,	// puntero a atributos de seguridad 
    BOOL bInitialOwner,	// bandera para el proprietario inicial
    LPCTSTR lpName 	// puntero al nombre de objeto-mutex  
   );

Parámetros

lpMutexAttributes: Puntero a una estructura SECURITY_ATTRIBUTES que determina si el manipulador retornado puede ser heredado por procesos hijos. Si lpMutexAttributes es NULL, el manipulador no puede ser heredado.
Windows NT: El miembro lpSecurityDescriptor de la estructura especifica un descriptor de seguridad para el mutex. Si lpMutexAttributes es NULL, el mutex toma el descriptor de seguridad por defecto.
Windows 95: El miembro lpSecurityDescriptor de la estructura es ignorado.
bInitialOwner: Especifica el propietario inicial del objeto mutex. Si es TRUE, el hilo que llama requiere de forma inmediata la propiedad del objeto mutex. En caso contrario, el mutex no tiene dueño.
lpName: Apunta a una cadena terminada en cero que especifica el nombre del objeto mutex. El nombre está limitado a MAX_PATH caracteres y puede contener cualquier caracter excepto el carácter separador de camino (\). Las comparaciones de nombres son case sensitive.
Si lpName coincide con el nombre de un objeto mutex existente, esta función requiere un acceso MUTEX_ALL_ACCESS al objeto existente. En ese caso, el parámetro bInitialOwner es ignorado, ya que ya ha sido establecido por el proceso de creación. Si el parámetro lpMutexAttributes no es NULL, determina si el manipulador puede o no ser heredado, pero su descriptor de seguridad es ignorado.
Si lpName es NULL, el objeto mutex es creado sin un nombre.
Si lpName coincide con el nombre de un evento existente, semáforo u objeto de mapeado de fichero, la función falla y le función GetLastError retorna ERROR_INVALID_HANDLE. Esto ocurre porque los eventos, mutex, semáforos y objetos de mapeado de ficheros comparten el mismo espacio de nombres.

Valor de retorno

Si la función tiene éxito, el valor de retorno es un manipulador al objeto mutex. Si el objeto mutex con nombre existe antes de la llamada a la función, la función GetLastError retorna ERROR_ALREADY_EXISTS. En caso contrario, GetLastError retorna cero.

Si la función falla, el valor de retorno es NULL. Para obtener información adicional sobre el error, llamar a GetLastError.

Observaciones

El manipulador devuelto por CreateMutex tiene el acceso MUTEX_ALL_ACCESS al nuevo objeto mutex y puede ser usado por cualquier función que requiera un manipulador a un objeto mutex.

Cualquier hilo del proceso que la llama puede especificar el manipulador del objeto mutex en una llamada a una de las funciones de espera. Las funciones de espera de un solo objeto retornan cuando el estado del objeto especificado esté señalado. Las funciones de espera de múltiples objetos pueden ser instruidas para retornar tanto cuando uno o cuando todos los objetos especificados estén señalados. Cuando una función de espera retrona, el hilo en espera es liberado para continuar su ejecución.

El estado de un objeto mutex está señalado cuando no tiene ningún propietario en ningún hilo. El hilo que lo crea puede usar la bandera bInitialOwner para solicitar de forma inmediata la propiedad del mutex. En otro caso, el hilo debe usar una de las funciones de espera para solicitar la propiedad. Cuando el estado del mutex está señalado, uno de los hilos que esperaba obtiene la propiedad, el estado del mutex cambia a no señalado, y la función de espera retorna. Sólo un hilo puede tener un mutex en un momento dado. El hilo propietario usa la función ReleaseMutex para liberar su propiedad.

El hilo que tiene un mutex puede especificar el mismo mutex en llamadas repetidas a la función de espera sin bloquear su ejecución. Normalmente no se esperará repetidamente por el mismo mutex, pero este mecanismo evita que un hilo se autobloquee mientras espera por un mutex que ya posee. Sin embargo, para liberar su propiedad, el hilo debe llamar a ReleaseMutex una vez por cada una que el mutex haya satisfecho una espera.

Uno o más procesos pueden llamar a CreateMutex para crear el mismo mutex con nombre. El primer proceso es el que realmente crea el mutex, los procesos subsiguientes abren un manipulador al mutex existente. Esto permite que varios procesos obtengan manipuladores al mismo mutex, mientras relevan al usuario de la responsabilidad de asegurarse de qué proceso de creación ha comenzado primero. Cuando se use esta técnica, se debe asignara a la bandera bInitialOwner FALSE; en caso contrario, puede resultar difícil estar seguro de qué proceso tiene la propiedad inicialmente.

Varios procesos pueden tener manipuladores del mismo objeto mutex, habilitando el uso de los objetos para sincronización entre procesos. Están disponibles los siguientes mecanismos de compartir objetos:

Un proceso hijo creao por la función CreateProcess puede heredar un manipulador al objeto mutex si el parámetro lpMutexAttributes de CreateMutex permite herencia.
Un proceso puede especificar el manipulador de objeto mutex en un llamada a la función DuplicateHandle para crear un duplicado del manipulador que puede ser usado por otro proceso.
Un proceso puede especificar el nombre de un objeto mutex en una llamada a la función OpenMutex o CreateMutex.

Usar la función CloseHandle para cerrar el manipulador. El sistema cierra los manipuladores de forma automática cuando el proceso termina. El objeto mutex es destruido cuando si último manipulador ha sido cerrado.