Rogue Wave banner
Previous fileTop of DocumentContentsIndexNext file

4.6 The Guard Classes

The guard classes are a family of helper classes commonly used to manipulate synchronization objects.

As explained in Section 4.4.3, the guard classes use the "resource acquisition is initialization" idiom. The RWTLockGuard template class uses this idiom for automatic acquisition and release of synchronization resources. The lock guard constructor calls an acquire() member provided by the synchronization resource. The lock guard destructor calls the release() member of an acquired resource.

4.6.1 Using a Lock Guard

To use a lock guard, declare a named instance of the guard class and initialize it with a reference to the synchronization mechanism, as shown in Example 42.

Example 42 -- Using a lock guard

//1The declaration of an RWTLockGuard<RWMutexLock> instance invokes a constructor that acquires the mutex passed as an argument.
//2The RWTLockGuard<RWMutexLock> instance is automatically destroyed when it goes out-of-scope-upon exit from the block where it was declared. The RWTLockGuard<RWMutexLock> destructor releases the mutex that was previously acquired. The guard instance is also destroyed if an exception occurs within this block, thus insuring that the mutex is always released.

4.6.2 Releasing and Reacquiring a Guarded Lock

To release and reacquire a guarded lock, you should use the release() and acquire() members of the guard object. as shown in Example 43. These member functions update the internal state of the guard so that the destructor does not attempt to release a lock that is no longer held.

Example 43 -- Releasing and reacquiring a guarded lock

4.6.3 Using the Unlock Guard Class

The same result can be achieved by using an RWTUnlockGuard to temporarily release then reacquire a synchronization resource, as shown in Example 44. The unlock guard class works in the same way as the lock guard class, except that it releases the resource in the constructor, and reacquires it in the destructor.

Example 44 -- Using an unlock guard

4.6.4 Using the RWTTryLockGuard Template Class

The RWTTryLockGuard template class defines a constructor that uses the resource member function tryAcquire(), to conditionally acquire a resource. The tryAcquire() function only acquires the resource when it is immediately available. It returns TRUE if the resource was successfully acquired and FALSE if the resource is currently owned by another thread. The destructor for this class releases the resource, but only if it was and is still acquired. The try-lock guard method isAcquired() can be used to test whether or not the acquisition was successful.

Example 45 -- Using a try-lock guard for conditional acquisition and release

4.6.5 Using Classes with Read-Write Synchronization Resources

The remaining guard classes are used with read-write synchronization resources such as RWReadersWriterLock. They are:

These guards behave in a manner identical to the simple guard classes, but rely on an acquisition interface that has been divided into read and write access:

 
Read InterfaceWrite Interface
acquireRead()
acquireWrite()
tryAcquireRead()
tryAcquireWrite()



Previous fileTop of DocumentContentsIndexNext file

©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.