CSingleLock Class

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

Syntax

class CSingleLock

Members

Public Constructors

Public Methods

Remarks

CSingleLock doesn't 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. Can't 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 didn't 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 isn't 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 isn't 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();
}

See also

Hierarchy Chart
CMultiLock Class