CSingleLock 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 CSingleLock Class.
Represents the access-control mechanism used in controlling access to a resource in a multithreaded program.
Syntax
class CSingleLock
Members
Public Constructors
| Name | Description |
|---|---|
| CSingleLock::CSingleLock | Constructs a CSingleLock object. |
Public Methods
| Name | Description |
|---|---|
| CSingleLock::IsLocked | Determines if the object is locked. |
| CSingleLock::Lock | Waits on a synchronization object. |
| CSingleLock::Unlock | Releases a synchronization object. |
Remarks
CSingleLock does not have a base class.
In order to use the synchronization classes CSemaphore, CMutex, CCriticalSection, and CEvent, you must create either a CSingleLock or CMultiLock object to wait on and release the synchronization object. Use CSingleLock when you only need to wait on one object at a time. Use CMultiLock when there are multiple objects that you could use at a particular time.
To use a CSingleLock object, call its constructor inside a member function in the controlled resource's class. Then call the IsLocked member function to determine if the resource is available. If it is, continue with the remainder of the member function. If the resource is unavailable, either wait for a specified amount of time for the resource to be released, or return failure. After use of the resource is complete, either call the Unlock function if the CSingleLock object is to be used again, or allow the CSingleLock object to be destroyed.
CSingleLock objects require the presence of an object derived from CSyncObject. This is usually a data member of the controlled resource's class. For more information on how to use CSingleLock objects, see the article Multithreading: How to Use the Synchronization Classes.
Inheritance Hierarchy
CSingleLock
Requirements
Header: afxmt.h
CSingleLock::CSingleLock
Constructs a CSingleLock object.
explicit CSingleLock(
CSyncObject* pObject,
BOOL bInitialLock = FALSE);
Parameters
pObject
Points to the synchronization object to be accessed. Cannot be NULL.
bInitialLock
Specifies whether to initially attempt to access the supplied object.
Remarks
This function is generally called from within an access member function of the controlled resource.
Example
// m_CritSection is a data member (of type CCriticalSection)
// of an existing class that implements the resource being shared.
// Relate the synchronization object (m_CritSection) with
// our CSingleLock object.
CSingleLock singleLock(&m_CritSection);
singleLock.Lock(); // Attempt to lock the shared resource
if (singleLock.IsLocked()) // Resource has been locked
{
//...use the shared resource...
// Now that we are finished,
// unlock the resource for others.
singleLock.Unlock();
}
CSingleLock::IsLocked
Determines if the object associated with the CSingleLock object is nonsignaled (unavailable).
BOOL IsLocked();
Return Value
Nonzero if the object is locked; otherwise 0.
Example
// m_Mutex is a data member (of type CMutex)
// of an existing class that implements the resource being shared.
// Relate the synchronization object (m_Mutex) with
// our CSingleLock object.
CSingleLock singleLock(&m_Mutex);
// Attempt to lock the shared resource
singleLock.Lock(100); // Wait 100 ms...
// Has the resource been successfully locked?
if (singleLock.IsLocked())
{
// We were able to lock the resource;
// we may now work with the data associated with the mutex...
// Now that we are finished, unlock the resource for others.
singleLock.Unlock();
}
CSingleLock::Lock
Call this function to gain access to the resource controlled by the synchronization object supplied to the CSingleLock constructor.
BOOL Lock(DWORD dwTimeOut = INFINITE);
Parameters
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.
Return Value
Nonzero if the function was successful; otherwise 0.
Remarks
If the synchronization object is signaled, Lock will return successfully and the thread now owns the object. If the synchronization object is nonsignaled (unavailable), Lock will wait for the synchronization object to become signaled up to the number of milliseconds specified in the dwTimeOut parameter. If the synchronization object did not become signaled in the specified amount of time, Lock returns failure.
Example
// m_Mutex is a data member (of type CMutex)
// of an existing class that implements the resource being shared.
// Relate the synchronization object (m_Mutex) with
// our CSingleLock object.
CSingleLock singleLock(&m_Mutex);
// Attempt to lock the shared resource
if (singleLock.Lock(100)) // Wait 100 ms...
{
// We were able to lock the resource;
// we may now work with the data associated with the mutex...
// Now that we are finished, unlock the resource for others.
singleLock.Unlock();
}
CSingleLock::Unlock
Releases the synchronization object owned by CSingleLock.
BOOL Unlock();
BOOL Unlock(
LONG lCount,
LPLONG lPrevCount = NULL);
Parameters
lCount
Number of accesses 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 of the synchronization object. If NULL, the previous count is not returned.
Return Value
Nonzero if the function was successful; otherwise 0.
Remarks
This function is called by CSingleLock's destructor.
If you need to release more than one access count of a semaphore, use the second form of Unlock and specify the number of accesses to release.
Example
// m_Mutex is a data member (of type CMutex)
// of an existing class that implements the resource being shared.
// Relate the synchronization object (m_Mutex) with
// our CSingleLock object.
CSingleLock singleLock(&m_Mutex);
// Attempt to lock the shared resource
if (singleLock.Lock(100)) // Wait 100 ms...
{
// We were able to lock the resource;
// we may now work with the data associated with the mutex...
// Now that we are finished, unlock the resource for others.
singleLock.Unlock();
}