CMultiLock Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CMultiLock Class.
Represents the access-control mechanism used in controlling access to resources in a multithreaded program.
class CMultiLock
Name | Description |
---|---|
CMultiLock::CMultiLock | Constructs a CMultiLock object. |
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.
CMultiLock
Header: afxmt.h
Constructs a CMultiLock object.
CMultiLock(
CSyncObject* ppObjects [ ],
DWORD dwCount,
BOOL bInitialLock = FALSE);
ppObjects
Array of pointers to the synchronization objects to be waited on. Cannot be NULL.
dwCount
Number of objects in ppObjects
. Must be greater than 0.
bInitialLock
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);
dwItem
The index in the array of objects corresponding to the object whose state is being queried.
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 Lock(
DWORD dwTimeOut = INFINITE,
BOOL bWaitForAll = TRUE,
DWORD dwWakeMask = 0);
dwTimeOut
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.
bWaitForAll
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.
dwWakeMask
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.
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). IfbWaitForAll
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. IfbWaitForAll
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.WAIT_TIMEOUT
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);
lCount
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.
lPrevCount
Points to a variable to receive the previous count for the synchronization object. If NULL, the previous count is not returned.
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.