Represents a "mutex" — a synchronization object that allows one thread mutually exclusive access to a resource.
class CMutex : public CSyncObject
Mutexes are useful when only one thread at a time can be allowed to modify data or some other controlled resource. For example, adding nodes to a linked list is a process that should only be allowed by one thread at a time. By using a
CMutex object to control the linked list, only one thread at a time can gain access to the list.
To use a
CMutex object, construct the
CMutex object when it is needed. Specify the name of the mutex you wish to wait on, and that your application should initially own it. You can then access the mutex when the constructor returns. Call CSyncObject::Unlock when you are done accessing the controlled resource.
An alternative method for using
CMutex objects is to add a variable of type
CMutex as a data member to the class you wish to control. During construction of the controlled object, call the constructor of the
CMutex data member specifying if the mutex is initially owned, the name of the mutex (if it will be used across process boundaries), and desired security attributes.
To access resources controlled by
CMutex objects in this manner, first create a variable of either type CSingleLock or type CMultiLock in your resource's access member function. Then call the lock object's
Lock member function (for example, CSingleLock::Lock). At this point, your thread will either gain access to the resource, wait for the resource to be released and gain access, or wait for the resource to be released and time out, failing to gain access to the resource. In any case, your resource has been accessed in a thread-safe manner. To release the resource, use the lock object's
Unlock member function (for example, CSingleLock::Unlock), or allow the lock object to fall out of scope.
For more information on using
CMutex objects, see the article Multithreading: How to Use the Synchronization Classes.
Constructs a named or unnamed
CMutex( BOOL bInitiallyOwn = FALSE, LPCTSTR lpszName = NULL, LPSECURITY_ATTRIBUTES lpsaAttribute = NULL);
Specifies if the thread creating the
CMutex object initially has access to the resource controlled by the mutex.
Name of the
CMutex object. If another mutex with the same name exists, lpszName must be supplied if the object will be used across process boundaries. If NULL, the mutex will be unnamed. If the name matches an existing mutex, the constructor builds a new
CMutex object which references the mutex of that name. If the name matches an existing synchronization object that is not a mutex, the construction will fail.
Security attributes for the mutex object. For a full description of this structure, see SECURITY_ATTRIBUTES in the Windows SDK.
To access or release a
CMutex object, create a CMultiLock or CSingleLock object and call its Lock and Unlock member functions. If the
CMutex object is being used stand-alone, call its
Unlock member function to release it.
After creating the
CMutex object, use GetLastError to ensure that the mutex did not already exist. If the mutex did exist unexpectedly, it may indicate a rogue process is squatting and may be intending to use the mutex maliciously. In this case, the recommended security-conscious procedure is to close the handle and continue as if there was a failure in creating the object.