vpr::CondVarPosix Class Reference

Condition variable wrapper for POSIX-compliant systems using pthreads condition variables for the implementation. More...

#include <vpr/Sync/CondVar.h>

Collaboration diagram for vpr::CondVarPosix:

[legend]List of all members.

Public Member Functions
	CondVarPosix (MutexPosix *mutex=NULL)
	Constructor for vpr::CondVarPosix class.
	~CondVarPosix ()
	Destructor for vpr::CondVarPosix class.
vpr::ReturnStatus	wait (vpr::Interval timeToWait=vpr::Interval::NoTimeout)
	Blocks on a condition.
vpr::ReturnStatus	signal ()
	Signals a thread waiting on this condition variable.
vpr::ReturnStatus	broadcast ()
	Signals all waiting threads.
vpr::ReturnStatus	acquire ()
	Acquires a lock on the mutex variable associated with this condition variable.
vpr::ReturnStatus	tryAcquire ()
	Try to acquire a lock on the mutex variable associated with this condition variable.
vpr::ReturnStatus	release ()
	Releases the lock on the mutex variable associated with this condition variable.
void	setMutex (vpr::MutexPosix *mutex)
	Changes the condition variable mutex to be the specifiec mutex variable.
int	test ()
	Tests the mutex to see if it is held.
void	dump () const
	Prints out information about the condition variable to stderr.

---

Detailed Description

Condition variable wrapper for POSIX-compliant systems using pthreads condition variables for the implementation.

This is typedef'd to vpr::CondVar.

Examples:

Example of using a vpr::CondVar.

Definition at line 68 of file CondVarPosix.h.

---

Constructor & Destructor Documentation

vpr::CondVarPosix::CondVarPosix

(

MutexPosix *

mutex = NULL

)

[inline]

Constructor for vpr::CondVarPosix class.

Postcondition:

The condition variable is intialized, and the mutex variable associated with it is defined. These two steps must be done before any other member functions can use them.

Parameters:

mutex

Pointer to a vpr::MutexPosix variable that is used in association with this condition variable in this class (optional).

Definition at line 82 of file CondVarPosix.h.

   {
      // Initialize the condition variable.
      pthread_cond_init(&mCondVar, NULL);

      // If the caller did not specify a mutex variable to use with
      // the condition variable, use mDefaultMutex.
      if ( mutex == NULL )
      {
         mutex = &mDefaultMutex;
      }

      mCondMutex = mutex;
   }

vpr::CondVarPosix::~CondVarPosix

(

)

[inline]

Destructor for vpr::CondVarPosix class.

Postcondition:

The condition variable is destroyed.

Definition at line 102 of file CondVarPosix.h.

   {
      pthread_cond_destroy(&mCondVar);
   }

---

Member Function Documentation

vpr::ReturnStatus vpr::CondVarPosix::wait

(

vpr::Interval

timeToWait = vpr::Interval::NoTimeout

)

Blocks on a condition.

Precondition:

The mutex variable associated with this condition variable must be locked.

Postcondition:

The condition variable is locked. If it was previously locked, the caller blocks until signaled.

Returns:

vpr::ReturnStatus::Succeed is returned after blocking.

vpr::ReturnStatus::Fail is returned if an error occurred when trying to wait on the condition variable.

Examples:

Example of using a vpr::CondVar.

Definition at line 55 of file CondVarPosix.cpp.

References vpr::ReturnStatus::Fail, vpr::MutexPosix::mMutex, vpr::Interval::NoTimeout, vpr::Interval::sec(), vpr::ReturnStatus::setCode(), vpr::ReturnStatus::Succeed, vpr::MutexPosix::test(), vpr::ReturnStatus::Timeout, vpr::Interval::usec(), vprASSERT, vprDBG_ALL(), vprDBG_CRITICAL_LVL, vprDEBUG, and vprDEBUG_FLUSH.

Referenced by vpr::ThreadPosix::start().

{
   // ASSERT:  We have been locked
   vpr::ReturnStatus status;

   // If not locked ...
   if ( mCondMutex->test() == 0 )
   {
      std::cerr << "[vpr::CondVarPosix::wait()] INCORRECT USAGE: Mutex was not "
                << "locked when wait invoked!!!\n";

      status.setCode(vpr::ReturnStatus::Fail);
   }
   else
   {
      // The mutex variable must be locked when passed to
      // pthread_cond_wait().
      if ( vpr::Interval::NoTimeout == timeToWait )
      {
         int retcode = pthread_cond_wait(&mCondVar, &(mCondMutex->mMutex));
         if ( retcode != 0 )
         {
#ifdef HAVE_STRERROR_R
            char error_str[255];
            strerror_r(retcode, error_str, 254);
#else
            char* error_str = strerror(retcode);
#endif
            vprDEBUG(vprDBG_ALL,vprDBG_CRITICAL_LVL)
               << "[vpr::CondVarPosix::wait()] Unexpected error: "
               << error_str << std::endl << vprDEBUG_FLUSH;
            status.setCode(vpr::ReturnStatus::Fail);
         }
      }
      else
      {
         struct timeval  now;                // The current time
         struct timespec abs_timeout;        // The absolute time of the timeout

         const vpr::Uint64 UsecsPerSec(1000000);

         // Calculate the absolute time for wait timeout
         gettimeofday(&now, NULL);

         // - Calculate the amount of usecs left as fractional seconds from
         //   wait time
         // - Calcualte the absolute time number of usecs
         // - If greater then a second then addon on those seconds to abs
         //   seconds
         // - Add on the waiting secons and the current time in seconds
         vpr::Uint64 abs_secs(0);
         const vpr::Uint64 left_over_usecs = timeToWait.usec() % UsecsPerSec;
         vpr::Uint64 abs_usecs = now.tv_usec + left_over_usecs;
         if(abs_usecs > UsecsPerSec)    // Have extra seconds
         {
            abs_secs = abs_usecs / UsecsPerSec;    // Get the number of seconds
            abs_usecs = abs_usecs % UsecsPerSec;
         }
         abs_secs += (now.tv_sec + timeToWait.sec());

         abs_timeout.tv_sec = abs_secs;
         abs_timeout.tv_nsec = 1000 * (abs_usecs);
         vprASSERT(abs_timeout.tv_nsec < vpr::Int64(UsecsPerSec * 1000) &&
                   "Nano seconds out of range (greater then one second).");

         int retcode = pthread_cond_timedwait(&mCondVar, &(mCondMutex->mMutex),
                                              &abs_timeout);

         if(0 == retcode)
         {
            status.setCode(vpr::ReturnStatus::Succeed);
         }
         else if(ETIMEDOUT == retcode)
         {
            status.setCode(vpr::ReturnStatus::Timeout);
         }
         else if(EINVAL == retcode)
         {
            status.setCode(vpr::ReturnStatus::Fail);
            vprDEBUG(vprDBG_ALL,vprDBG_CRITICAL_LVL)
               << "[vpr::CondVarPosix::wait()] Invalid value.\n"
               << vprDEBUG_FLUSH;
         }
         else
         {
#ifdef HAVE_STRERROR_R
            char error_str[255];
            strerror_r(retcode, error_str, 254);
#else
            char* error_str = strerror(retcode);
#endif
            vprDEBUG(vprDBG_ALL,vprDBG_CRITICAL_LVL)
               << "[vpr::CondVarPosix::wait()] Unexpected error: "
               << error_str << std::endl << vprDEBUG_FLUSH;
            status.setCode(vpr::ReturnStatus::Fail);
         }
      }
   }

   return status;
}

vpr::ReturnStatus vpr::CondVarPosix::signal

(

)

[inline]

Signals a thread waiting on this condition variable.

Precondition:

The condition variable must be locked.

Postcondition:

The condition variable is unlocked, and a signal is sent to a thread waiting on it.

Returns:

vpr::ReturnStatus::Succeed is returned if the signal is sent successfully.

vpr::ReturnStatus::Fail is returned if the signalling failed.

Examples:

Example of using a vpr::CondVar.

Definition at line 132 of file CondVarPosix.h.

References vpr::ReturnStatus::Fail, and vpr::ReturnStatus::Succeed.

Referenced by vpr::ThreadPosix::startThread().

   {
      // ASSERT:  We have been locked
      if ( pthread_cond_signal(&mCondVar) == 0 )
      {
         return vpr::ReturnStatus(vpr::ReturnStatus::Succeed);
      }
      else
      {
         return vpr::ReturnStatus(vpr::ReturnStatus::Fail);
      }
   }

vpr::ReturnStatus vpr::CondVarPosix::broadcast

(

)

[inline]

Signals all waiting threads.

Precondition:

The mutex variable associated with this condition variable should be locked.

Postcondition:

The condition variable is unlocked, and all waiting threads are signaled of this event.

Returns:

vpr::ReturnStatus::Succeed is returned if a signal was broadcast to all waiting threads successfully.

vpr::ReturnStatus::Fail is returned to indicate an error with the signal broadcast.

Definition at line 158 of file CondVarPosix.h.

References vpr::ReturnStatus::Fail, vpr::ReturnStatus::Succeed, and vpr::MutexPosix::test().

   {
      // ASSERT:  We have been locked

      // If not locked ...
      if ( mCondMutex->test() == 0 )
      {
         std::cerr << "vpr::CondVarPosix::broadcast: Mutex was not locked when "
                   << "broadcast called!!!\n";
      }

      if ( pthread_cond_broadcast(&mCondVar) == 0 )
      {
         return vpr::ReturnStatus(vpr::ReturnStatus::Succeed);
      }
      else
      {
         return vpr::ReturnStatus(vpr::ReturnStatus::Fail);
      }
   }

vpr::ReturnStatus vpr::CondVarPosix::acquire

(

)

[inline]

Acquires a lock on the mutex variable associated with this condition variable.

Postcondition:

A lock is acquired on the mutex variable associated with the condition variable. If a lock is acquired, the caller controls the mutex variable. If it was previously locked, the caller blocks until it is unlocked.

Returns:

vpr::ReturnStatus::Succeed is returned if the lock was acquired successfully.

vpr::ReturnStatus::Fail is returned otherwise.

Examples:

Example of using a vpr::CondVar.

Definition at line 192 of file CondVarPosix.h.

References vpr::MutexPosix::acquire().

Referenced by vpr::ThreadPosix::start(), and vpr::ThreadPosix::startThread().

   {
      return mCondMutex->acquire();
   }

vpr::ReturnStatus vpr::CondVarPosix::tryAcquire

(

)

[inline]

Try to acquire a lock on the mutex variable associated with this condition variable.

Postcondition:

If the mutex variable is not already locked, the caller obtains a lock on it. If it is already locked, the routine returns immediately to the caller.

Returns:

vpr::ReturnStatus::Succeed is returned if the lock was acquired successfully.

vpr::ReturnStatus::Fail is returned if the lock could not be acquired.

Definition at line 210 of file CondVarPosix.h.

References vpr::MutexPosix::tryAcquire().

   {
      return mCondMutex->tryAcquire();
   }

vpr::ReturnStatus vpr::CondVarPosix::release

(

)

[inline]

Releases the lock on the mutex variable associated with this condition variable.

Postcondition:

The lock held by the caller on the mutex variable is released.

Examples:

Example of using a vpr::CondVar.

Definition at line 221 of file CondVarPosix.h.

References vpr::MutexPosix::release().

Referenced by vpr::ThreadPosix::start(), and vpr::ThreadPosix::startThread().

   {
      return mCondMutex->release();
   }

void vpr::CondVarPosix::setMutex

(

vpr::MutexPosix *

mutex

)

[inline]

Changes the condition variable mutex to be the specifiec mutex variable.

Precondition:

The specified mutex variable must be initialized.

Postcondition:

The condition variable associated with the mutex variable is reset to the specified variable.

Parameters:

mutex

Pointer to a vpr::MutexPosix variable that is used in association with the condition variable in this class.

Note:

NEVER call except to initialize explicitly.

Definition at line 239 of file CondVarPosix.h.

References vpr::MutexPosix::release().

   {
      // NOT exactly correct, but just make sure not to leave it locked
      mutex->release();
      mCondMutex = mutex;
   }

int vpr::CondVarPosix::test

(

)

[inline]

Tests the mutex to see if it is held.

Definition at line 247 of file CondVarPosix.h.

References vpr::MutexPosix::test().

   {
      return mCondMutex->test();
   }

void vpr::CondVarPosix::dump

(

)

const [inline]

Prints out information about the condition variable to stderr.

Postcondition:

All important data and debugging information related to the condition variable and its mutex are dumped to stderr.

Definition at line 258 of file CondVarPosix.h.

   {
      std::cerr << "------------- vpr::CondVarPosix::Dump ---------\n"
                << "Not Implemented yet.\n";
   }

---

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

• CondVarPosix.h
• CondVarPosix.cpp

---