CSingleLock Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

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

class CSingleLock  

Public Constructors

NameDescription
CSingleLock::CSingleLockConstructs a CSingleLock object.

Public Methods

NameDescription
CSingleLock::IsLockedDetermines if the object is locked.
CSingleLock::LockWaits on a synchronization object.
CSingleLock::UnlockReleases a synchronization object.

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.

CSingleLock

Header: afxmt.h

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();
   }

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();
   }

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();
   }

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();
   }

Hierarchy Chart
CMultiLock Class

Show: