CMultiLock Class

Represents the access-control mechanism used in controlling access to resources in a multithreaded program.


class CMultiLock


Public Constructors

Name Description
CMultiLock::CMultiLock Constructs a CMultiLock object.

Public Methods

Name Description
CMultiLock::IsLocked Determines if a specific synchronization object in the array is locked.
CMultiLock::Lock Waits on the array of synchronization objects.
CMultiLock::Unlock Releases any owned synchronization objects.


CMultiLock does not have a base class.

To use the synchronization classes CSemaphore, CMutex, and CEvent, you can create either a CMultiLock or CSingleLock object to wait on and release the synchronization object. Use CMultiLock when there are multiple objects that you could use at a particular time. Use CSingleLock when you only need to wait on one object at a time.

To use a CMultiLock object, first create an array of the synchronization objects that you wish to wait on. Next, call the CMultiLock object's constructor inside a member function in the controlled resource's class. Then call the Lock member function to determine if a resource is available (signaled). If one is, continue with the remainder of the member function. If no resource is available, either wait for a specified amount of time for a resource to be released, or return failure. After use of a resource is complete, either call the Unlock function if the CMultiLock object is to be used again, or allow the CMultiLock object to be destroyed.

CMultiLock objects are most useful when a thread has a large number of CEvent objects it can respond to. Create an array containing all the CEvent pointers, and call Lock. This will cause the thread to wait until one of the events is signaled.

For more information on how to use CMultiLock objects, see the article Multithreading: How to Use the Synchronization Classes.

Inheritance Hierarchy



Header: afxmt.h


Constructs a CMultiLock object.

    CSyncObject* ppObjects [ ],
    DWORD dwCount,
    BOOL bInitialLock = FALSE);


Array of pointers to the synchronization objects to be waited on. Cannot be NULL.

Number of objects in ppObjects. Must be greater than 0.

Specifies whether to initially attempt to access any of the supplied objects.


This function is called after creating the array of synchronization objects to be waited on. It is usually called from within the thread that must wait for one of the synchronization objects to become available.


Determines if the specified object is nonsignaled (unavailable).

BOOL IsLocked(DWORD dwItem);


The index in the array of objects corresponding to the object whose state is being queried.

Return Value

Nonzero if the specified object is locked; otherwise 0.


Call this function to gain access to one or more of the resources controlled by the synchronization objects supplied to the CMultiLock constructor.

    DWORD dwTimeOut = INFINITE,
    BOOL bWaitForAll = TRUE,
    DWORD dwWakeMask = 0);


Specifies the amount of time to wait for the synchronization object to be available (signaled). If INFINITE, Lock will wait until the object is signaled before returning.

Specifies whether all objects waited on must become signaled at the same time before returning. If FALSE, Lock will return when any one of the objects waited on is signaled.

Specifies other conditions that are allowed to abort the wait. For a full list of the available options for this parameter, see MsgWaitForMultipleObjects in the Windows SDK.

Return Value

If Lock fails, it returns - 1. If successful, it returns one of the following values:

  • Between WAIT_OBJECT_0 and WAIT_OBJECT_0 + (number of objects - 1)

    If bWaitForAll is TRUE, all objects are signaled (available). If bWaitForAll is FALSE, the return value - WAIT_OBJECT_0 is the index in the array of objects of the object that is signaled (available).

  • WAIT_OBJECT_0 + (number of objects)

    An event specified in dwWakeMask is available in the thread's input queue.

  • Between WAIT_ABANDONED_0 and WAIT_ABANDONED_0 + (number of objects - 1)

    If bWaitForAll is TRUE, all objects are signaled, and at least one of the objects is an abandoned mutex object. If bWaitForAll is FALSE, the return value - WAIT_ABANDONED_0 is the index in the array of objects of the abandoned mutex object that satisfied the wait.


    The timeout interval specified in dwTimeOut expired without the wait succeeding.


If bWaitForAll is TRUE, Lock will return successfully as soon as all the synchronization objects become signaled simultaneously. If bWaitForAll is FALSE, Lock will return as soon as one or more of the synchronization objects becomes signaled.

If Lock is not able to return immediately, it will wait for no more than the number of milliseconds specified in the dwTimeOut parameter before returning. If dwTimeOut is INFINITE, Lock will not return until access to an object is gained or a condition specified in dwWakeMask was met. Otherwise, if Lock was able to acquire a synchronization object, it will return successfully; if not, it will return failure.


Releases the synchronization object owned by CMultiLock.

BOOL Unlock();

BOOL Unlock(
    LONG lCount,
    LPLONG lPrevCount = NULL);


Number of reference counts to release. Must be greater than 0. If the specified amount would cause the object's count to exceed its maximum, the count is not changed and the function returns FALSE.

Points to a variable to receive the previous count for the synchronization object. If NULL, the previous count is not returned.

Return Value

Nonzero if the function was successful; otherwise 0.


This function is called by CMultiLock's destructor.

The first form of Unlock tries to unlock the synchronization object managed by CMultiLock. The second form of Unlock tries to unlock the CSemaphore objects owned by CMultiLock. If CMultiLock does not own any locked CSemaphore object, the function returns FALSE; otherwise, it returns TRUE. lCount and lpPrevCount are exactly the same as the parameters of CSingleLock::Unlock. The second form of Unlock is rarely applicable to multilock situations.

See also

Hierarchy Chart