• vpr::Exception (declared in vpr/Util/Exception.h)
  • vpr::IOException (declared in vpr/IO/IOException.h)
    • vpr::EOFException (declared in vpr/IO/EOFException.h)
    • vpr::SocketException (declared in vpr/IO/Socket/SocketException.h)
      • vpr::ConnectionAbortedException (declared in vpr/IO/Socket/ConnectionAbortedException.h)
      • vpr::ConnectionRefusedException (declared in vpr/IO/Socket/ConnectionRefusedException.h)
      • vpr::ConnectionResetException (declared in vpr/IO/Socket/ConnectionResetException.h)
      • vpr::NoRouteToHostException (declared in vpr/IO/Socket/NoRouteToHostException.h)
      • vpr::UnknownHostException (declared in vpr/IO/Socket/UnknownHostException.h)
    • vpr::TimeoutException (declared in vpr/IO/TimeoutException.h)
    • vpr::WouldBlockException (declared in vpr/IO/WouldBlockException.h)

• vpr::Mutex
• vpr::Guard<T>
• vpr::CondVar
• vpr::Semaphore
• vpr::RWMutex
• vpr::RWGuard<T>

Previously, operations such as vpr::Mutex::acquire() and vpr::Mutex::release() returned a vpr::ReturnStatus to indicate whether the lock/unlock operation succeeded. Now, these methods have a void return type. If locking/unlocking should fail due to an exceptional case, then an exception is thrown.

These changes were made in the following VPR versions:

• 1.1.28—change vpr::Mutex to use exceptions instead of vpr::ReturnStatus
• 1.1.29—change vpr::CondVar to use exceptions instead of vpr::ReturnStatus
• 1.1.30—change vpr::Semaphore to use exceptions instead of vpr::ReturnStatus
• 1.1.31—change vpr::Mutex and vpr::Semaphore to report deadlock detection
• 1.1.33—change vpr::RWMutex to use exceptions instead of vpr::ReturnStatus and to report deadlock detection

To write code that works with VPR 1.0 and 2.0, it is recommended that users test __VPR_version against either 1001033 (the encoding of 1.1.33) or 2000000 (the encoding of 2.0.0). Since most of these version increments were made in quick succession, it is highly unlikely that code would need to work with all the different VPR 1.1 versions.

Synchronization Exceptions

The exceptions thrown by synchronization methods are the following (indentation indicates class hierarchy):

• vpr::Exception (declared in vpr/Util/Exception.h)
  • vpr::ResourceException (declared in vpr/Util/ResourceException.h)
  • vpr::LockException (declared in vpr/Sync/LockException.h)
    • vpr::DeadlockException (declared in vpr/Sync/DeadlockException.h)

The exception type vpr::ResourceException is thrown by the constructor of each of the various synchronization classes if allocation of the platform-specific synchronization primitive should fail. In that case, there is no way for the VPR synchronization object to be used, and all locking and unlocking methods would fail.

The exception type vpr::LockException is thrown if a lock or unlock operation fails due to misuse of the object. For example, if vpr::Mutex::release() is invoked on an object from a thread that is not currently holding the mutex lock, then that is a misuse of the mutex object, and vpr::LockException is thrown. Similarly, if vpr::CondVar::signal() or vpr::CondVar::broadcast() is invoked on a condition variable object that is not currently locked, that violates the contract of those methods, and vpr::LockException is thrown.

The exception type vpr::DeadlockException is thrown when an attempt to lock a synchronization object would cause a thread to deadlock. This occurs when the same thread tries to lock the same mutex twice. The operating system detects this case and reports it, and VPR synchronization objects translate this error code into a vpr::DeadlockException that is thrown. Previously, this case was only "reported" through an assertion failure when building with _DEBUG defined, so this change is definitely a big improvement.

Return Type Changes

The synchronization classes all have a non-blocking lock acquisition method named tryAcquire(), and many have tryAcquireRead() and tryAcquireWrite() methods. In VPR 1.0, these methods return a vpr::ReturnStatus object to indicate whether or not the lock was acquired. Since this operation either succeeded in acquiring the lock or failing to do so, the return type was changed to bool to allow simplification of user-level code. The following example shows a simple use of vpr::Guard<vpr::Mutex> and vpr::Mutex::tryAcquire() that will compile with VPR 1.0, 1.1, and 2.0:

#include <boost/noncopyable.hpp>
#include <vpr/vprParam.h>
#include <vpr/Sync/Mutex.h>
#include <vpr/Sync/Guard.h>

// The class is non-copyable because vpr::Mutex is non-copayble.
class MyClass : boost::noncopyable
{
public:
   void changeData(const int newValue)
   {
      // Acquires the mutex on construction; releases it on destruction.
      vpr::Guard<vpr::Mutex> g(mMutex);
      mData = newValue;
   }

   bool useData()
   {
#if __VPR_version < 1001033
      const bool locked = mMutex.tryAcquire().success();
#else
      const bool locked = mMutex.tryAcquire();
#endif
      int result(-1);

      if ( locked )
      {
         const int cur_value(mData);
         mMutex.release();
         // Do work based on cur_value ...
      }

      return locked;
   }

private:
   vpr::Mutex mMutex;
   int mData;
};

We could take the above example a little farther by handling the case of deadlock detection in the implementation of MyClass::changeData(), as shown below (note that vpr/Sync/DeadlockException.h would need to be included):

   void changeData(const int newValue)
   {
#if __VPR_version >= 1001033
      try
      {
         // Acquires the mutex on construction; releases it on destruction.
         // If an exception is thrown during mutex acquisition, g is
         // automatically destroyed, but no change is made to the state of
         // mMutex.
         vpr::Guard<vpr::Mutex> g(mMutex);
         mData = newValue;
      }
      // If deadlock was detected, then this thread is already holding a
      // lock on mMutex, so it is still save to change mData.
      catch (vpr::DeadlockException& ex)
      {
         mData = newValue;
      }
#else
      // Acquires the mutex on construction; releases it on destruction.
      vpr::Guard<vpr::Mutex> g(mMutex);
      mData = newValue;
#endif
   }

This example is rather contrived and is intended to demonstrate what options exist for handling deadlock detection and how vpr::Guard<vpr::Mutex> will behave in this context.

• vpr::BlockIO
• vpr::Selector
• vpr::SerialPort (see vpr::SerialPortImplTermios and vpr::SerialPortImplWin32)
• vpr::ObjectReader
• vpr::ObjectWriter
• vpr::BufferedObjectReader
• vpr::BufferedObjectWriter
• vpr::XMLObjectReader
• vpr::XMLObjectWriter
• vpr::ReadableObject
• vpr::WritableObject
• vpr::Socket (see vpr::Socket_t<T>, vpr::SocketImplBSD, and vpr::SocketImplNSPR)
• vpr::SocketDatagram (see vpr::SocketDatagram_t<T>, vpr::SocketDatagramImplBSD, and vpr::SocketDatagramImplNSPR)
• vpr::SocketStream (see vpr::SocketStream_t<T>, vpr::SocketStreamImplBSD, and vpr::SocketStreamImplNSPR)
• vpr::InetAddr (see vpr::InetAddrBSD and vpr::InetAddrNSPR)
• vpr::FileHandle (see vpr::FileHandle_t<T> and vpr::FileHandleImplUNIX)

I/O Exceptions

The exceptions thrown by I/O methods are the following (indentation indicates class hierarchy):

• vpr::Exception
  • vpr::IOException
    • vpr::EOFException
    • vpr::SocketException
      • vpr::ConnectionAbortedException
      • vpr::ConnectionRefusedException
      • vpr::ConnectionResetxception
      • vpr::NoRouteToHostException
      • vpr::UnknownHostException
    • vpr::TimeoutException
    • vpr::WouldBlockException

#include <vector>
#include <vpr/IO/ObjectReader.h>
#include <vpr/IO/EOFException.h>
#include <plugins/ApplicationDataManager/UserData.h>

class MyType : public vpr::SerializableObject
{
public:
   void readObject(vpr::ObjectReader* reader)
   {
      try
      {
         const vpr::Uint8 val_count = reader->readUint8();
         std::vector<vpr::Uint32> values(val_count);
         for ( vpr::Uint8 i = 0; i < val_count; ++i )
         {
            values[i] = reader->readUint32();
         }

         // Wait to replace mValues until we know that we have
         // read everything.
         mValues = values;
      }
      catch (vpr::EOFException& ex)
      {
         std::cerr << "Ran out of data unexpectedly:\n"
                   << ex.what() << std::endl;
         throw;
      }
      catch (vpr::IOException& ex)
      {
         std::cerr << "I/O error occurred during de-serialization:\n"
                   << ex.what() << std::endl;
         throw;
      }
   }

   // writeObject() implementation omitted

private:
   std::vector<vpr::Uint32> mValues;
};

Of course, the exception handling in the above example is not very interesting since it just prints a different error message based on the exception type. One can imagine more complex uses, however, and the point of the above example is to demonstrate what is possible rather than to give a definitive example of what to do in all cases.

Querying Environment Variables

The helper functions vpr::System::getenv() and vpr::System::setenv() have had their return type changed from vpr::ReturnStatus to bool. Since these methods either succeed or fail, using vpr::ReturnStatus was overkill. This change was made in VPR 1.1.35 (encoded as 1001035 in the preprocessor symbol __VPR_version as defined in vpr/vprParam.h). The following shows an example of how to use vpr::System::getenv() in a way that will work with VPR 1.0, 1.1, and 2.0:

#include <vpr/vprParam.h>
#include <vpr/System.h>

void f()
{
   const std::string envvar("SOME_VAR");
   std::string value;
#if __VPR_version < 10010135
   const bool result = vpr::System::getenv(envvar, value).success();
#else
   const bool result = vpr::System::getenv(envvar, value);
#endif

   if ( result )
   {
      // Do something with value ...
   }
}

Another approach that does not require the version testing would be the following:

#include <vpr/System.h>

void f()
{
   std::string value;
   vpr::System::getenv("SOME_VAR", value);

   if ( ! value.empty() )
   {
      // Do something with value ...
   }
}

Application-Specific Cluster Data

The changes to the return type of vpr::ReadableObject::readObject() and vpr::WritableObject::writeObject() impact code written for sharing application-specific data in a cluster. These changes were made as part of VPR 1.1.5, so all code built against versions of VPR prior to this must return vpr::ReturnStatus in their override of these methods. For VPR 1.1.5 and beyond, the return type must be void. The following shows an example of how to write code that will work with VPR 1.0, 1.1, and 2.0. Here, the VPR 1.1.5 version number is encoded as 1001005, and the encoded version can be queried from the __VPR_version preprocessor symbol defined in vpr/vprParam.h.

#include <vpr/vprParam.h>
#include <plugins/ApplicationDataManager/UserData.h>

class MyType : public vpr::SerializableObject
{
public:
#if __VPR_version < 1001005
   vpr::ReturnStatus
#else
   void
#endif
   readObject(vpr::ObjectReader* reader)
   {
      // Read object from reader...
#if __VPR_version < 1001005
      return vpr::ReturnStatus();
#endif
   }

#if __VPR_version < 1001005
   vpr::ReturnStatus
#else
   void
#endif
   writeObject(vpr::ObjectWriter* writer)
   {
      // Write object to writer...
#if __VPR_version < 1001005
      return vpr::ReturnStatus();
#endif
   }
};

#include <vpr/vprParam.h>
#include <vpr/Thread/Thread.h>

class MyClass
{
public:
   MyClass()
      : mRunning(false)
#if __VPR_version < 1001016
      , mThreadFunctor(NULL)
#endif
      , mThread(NULL)
   {
   }

   ~MyClass()
   {
      if ( mRunning )
      {
         stopThread();
      }

      if ( NULL != mThread )
      {
         delete mThread;
         mThread = NULL;
      }

#if __VPR_version < 1001016
      if ( NULL != mThreadFunctor )
      {
         delete mThreadFunctor;
         mThreadFunctor = NULL;
      }
#endif
   }

   bool startThread()
   {
#if __VPR_version < 1001016
      mThreadFunctor =
         new vpr::ThreadMemberFunctor<MyClass>(this,
                                               &MyClass::run,
                                               NULL);
      mThread = new vpr::Thread(mThreadFunctor);

      return mThread->isValid();
#else
      bool started(false);
      try
      {
         mThread =
            new vpr::Thread(boost::bind(&MyClass::run,
                                        this));

         // Handle versions between 1.1.16 and 1.1.31.
#if __VPR_version < 1001031
         started = mThread->isValid();
#else
         started = true;
#endif
      }
      catch (vpr::Exception& ex)
      {
         std::cerr << ex.what() << std::endl;
      }

      return started;
#endif
   }

   void stopThread()
   {
      mRunning = false;
      if ( NULL != mThread )
      {
         mThread->join();
      }
   }

private:
   void run(
#if __VPR_version < 1001016
      void*
#endif
   )
   {
      mRunning = true;
      while ( mRunning )
      {
         // Do work...
      }
   }

   bool mRunning;
#if __VPR_version < 1001016
   vpr::ThreadMemberFunctor<MyClass>* mThreadFunctor;
#endif
   vpr::Thread* mThread;
};

Porting from VR Juggler 2.0 to 2.2

VPR Interface Changes

The VR Juggler Portable Runtime (VPR) has undergone extensive work to improve error reporting through the use of exceptions (derived from vpr::Exception) rather than the clumsier use of vpr::ReturnStatus. Methods in VPR 1.0 classes that used to return vpr::ReturnStatus (generally) now have a void return type and report errors by throwing exceptions. In some cases, the use of vpr::ReturnStatus as the return type was replaced by returning a bool and throwing exceptions to report critical errors. This was only done for cases where an operation can "fail" under standard usage; exceptions are used to report exceptional cases.

I/O Classes

Threads

The use of vpr::ThreadFunctor has been replaced by the much more powerful and flexible Boost.Function. In VPR 1.0, threads were created using one of the following approaches:

   // Using a member function.
   MyType* my_obj = new MyType();
   vpr::ThreadMemberFunctor* functor =
      new vpr::ThreadMemberFunctor<MyType>(my_obj,
                                           &MyType::threadFunc,
                                           NULL);
   vpr::Thread* thread = new vpr::Thread(functor);

   // Using a non-member function or a static member function.
   vpr::ThreadNonMemberFunctor* functor =
      new vpr::ThreadNonMemberFunctor(threadFunc, NULL);
   vpr::Thread* thread = new vpr::Thread(functor);

The signature of the thread function passed to the functor had to have a void return type and take a single void* parameter (that often went unused).

In VPR 2.0, the thread function can take any number of parameters, though it must still have a void return type. (The boost::function<T> type instantiation is boost::function<void ()>.) This is possible by using boost::bind(). boost::bind() must also be used for creating thread functors for member functions. The following shows how to do the equivalent of the above VPR 1.0 thread creation mechanisms:

   // Using a member function.
   MyType* my_obj = new MyType();
   vpr::Thread* thread =
      new vpr::Thread(boost::bind(&MyType::threadFunc, my_obj));

   // Using a non-member function.
   vpr::Thread* thread = new vpr::Thread(threadFunc);

Clearly, this new approach is much simpler and avoids a potential (and all-too-common) memory leak wherein the heap-allocated vpr::ThreadFunctor instance would not get deleted.

As noted, boost::bind() can be used to allow for thread functors that take any number of arguments. For example, consider these (somewhat contrived) cases:

   void threadFunc(const int val,
                   std::vector<SomeClass>& vecRef)
   {
      for ( int i = 0; i < val; ++i )
      {
         vecRef.push_back(SomeClass(i));
      }
   }

   void createThread(const int val)
   {
      std::vector<SomeClass> vec;
      vpr::Thread* thead =
         new vpr::Thread(boost::bind(threadFunc,
                                     val, boost::ref(vec));
      thread->join();
      std::cout << vec.size() << std::endl;
   }

Synchronization Primitives

Using Flagpoll

-- PatrickHartling - 27 Oct 2006