OSB_LIB::Guard Class Reference

Collaboration diagram for OSB_LIB::Guard:

[legend]List of all members.

---

Detailed Description

Automatically perform actions when the object goes out of scope.

A guard is an object that automatically performs clean-up actions when it goes out of scope. When copying the responsibility to perform the clean-up actions is transferred to the target (left hand side) object. On assignment frist any pending clean-up actions are done and then the ownership for the clean-up actions is transferred.

Remarks:

Originally the class was designed to automatically unlock a Mutex. The introduction of Cleanup now allows for a much broader usage: Any actions needed when the guard goes out of scope can now be executed in Cleanup::cleanup().

Example to use a guard with a Mutex (MutexUnlock is derived from Cleanup):

      class Locker {
      public:
         // Initialize the unlock object:
         Locker() : unlock_(&mutex_);

         // Issue a guard:
         Guard mkGuard()
         {
             bool locked = (0 == mutex_.trylock());
             Guard g(&unlock_, locked);
             return g;
         }

      private:
         Mutex       mutex_;       // protecting mutex
         MutexUnlock unlock_;      // unlock the mutex
      };

      void foo()
      {
          Guard g = theLocker().mkGuard();
          if (g.isLoaded()) {
              // Save access to locked resource.
          }
          else {
              // Error: can not lock resource.
          }
      }

Definition at line 105 of file guard.h.

Public Member Functions

• Guard (Cleanup *pCleanup=0, bool doClean=true)

  Create a (empty) guard.
  

• Guard (Cleanup::AutoPtr cleanup, bool doClean)

  Create a guard, taking ownership of the Cleanup object.
  

• ~Guard ()

  The destructor performs the clean-up actions.
  

• Guard (Guard &rhs)

  Non-const copy constructor.
  

• Guard & operator= (Guard rhs)

  Non-const assignment operator.
  

• bool isLoaded () const

  Object responsible for clean-up?
  

• std::pair< bool, int > cleanup ()

  Do the clean-up actions.
  

• bool release ()

  Release clean-up responsibility without calling pCleanup_->cleanup().
  

Non-const construction:

The following constructor and conversion operator are used to achive the non-const copy construction Guard(Guard) by compiler generated conversions.

• Guard (GuardRef r)

  Construct from a GuardRef.
  

• operator GuardRef ()

  Convert to GuardRef.
  

Private Attributes

• bool doClean_

  Clean-up to be done?
  

• Cleanup * pCleanup_

  Pointer to the cleanup object.
  

• bool delCleanup_

  Flag if the Cleanup object is owned by the guard.
  

Classes

• class Cleanup

  Base class to perform the clean-up actions. More...
  

• struct GuardRef

  Helping structure to allow non-const copy of Guard. More...
  

---

Constructor & Destructor Documentation

OSB_LIB::Guard::Guard	(	Cleanup *	pCleanup = 0,
		bool	doClean = true
	)

Create a (empty) guard.

When used as default constructor, i.e., without providing an Cleanup object, the guard behaves as if it was in charge for the clean-up. This specification allows to test the correct usage of the guard when copied or assigned.

Parameters:

	pCleanup	Object to perform the clean-up actions, the guard does not take its ownership.
	doClean	Flag if clean-up actions are to be performed.

Remarks:

When working with mutexes, `doClean' should be set to true if caller of the guard constructor is owner of mutex lock, else false.

OSB_LIB::Guard::Guard	(	Cleanup::AutoPtr	cleanup,
		bool	doClean
	)

Create a guard, taking ownership of the Cleanup object.

Parameters:

	cleanup	Auto pointer to the Cleanup object, the guard takes ownership.
	doClean	Flag if clean-up actions are to be performed.

Remarks:

The argument `cleanup' may be an empty auto pointer.

When working with mutexes, `doClean' should be set to true if caller of the guard constructor is owner of mutex lock, else false.

OSB_LIB::Guard::~Guard

(

)

The destructor performs the clean-up actions.

The destructor calls cleanup() to perform the clean-up actions and -if owned- deletes pCleanup_.

OSB_LIB::Guard::Guard

(

Guard &

rhs

)

Non-const copy constructor.

Transfers the ownership of the clean-up actions and Cleanup object from `rhs'.

OSB_LIB::Guard::Guard

(

GuardRef

r

)

Construct from a GuardRef.

Takes the ownership of the clean-up actions and the Cleanup object from `r'.

---

Member Function Documentation

std::pair<bool, int> OSB_LIB::Guard::cleanup

(

)

Do the clean-up actions.

Calls pCleanup_->cleanup() if release() returns true and pCleanup_ is not NULL.

Returns:

The first part of the return value is true if pCleanup_->cleanup() was called, else false.
The second part of the return value is the result of the cleanup action. It has no meaning if the first part is false.

Remarks:

The function always calls release() which means that any side effects of it apply to this member function as well.

bool OSB_LIB::Guard::isLoaded

(

)

const [inline]

Object responsible for clean-up?

Definition at line 246 of file guard.h.

References doClean_.

OSB_LIB::Guard::operator GuardRef

(

)

Convert to GuardRef.

Guard& OSB_LIB::Guard::operator=

(

Guard

rhs

)

Non-const assignment operator.

First executes pending clean-up actions and -if owned- deletes pCleanup_. Then transfers the responsiblity to clean-up and the ownership of the Cleanup object from `rhs'.

bool OSB_LIB::Guard::release

(

)

Release clean-up responsibility without calling pCleanup_->cleanup().

Remarks:

After the function is called, doClean_ is always false and the guard will no more dereference the Cleanup pointer to call its clean-up function.

Returns:

True if the object was in charge for the clean-up before the function was called, else false.

---

Member Data Documentation

bool OSB_LIB::Guard::delCleanup_ [private]

Flag if the Cleanup object is owned by the guard.

Definition at line 284 of file guard.h.

bool OSB_LIB::Guard::doClean_ [private]

Clean-up to be done?

Definition at line 280 of file guard.h.

Referenced by isLoaded().

Cleanup* OSB_LIB::Guard::pCleanup_ [private]

Pointer to the cleanup object.

Definition at line 282 of file guard.h.

---

The documentation for this class was generated from the following file:

• guard.h

---