Prior to opening an I/O device, some attributes can be set. These in turn affect how the device is opened. In the general case of vpr::BlockIO, the only attribute that is available determines whether the device will be opened in blocking mode or non-blocking mode. By default, all devices open in blocking mode, and in most cases, this is the desired mode.

The decision to use blocking or non-blocking I/O depends on the needs of the application or library being developed on top of VPR. While the decision can be made before opening the device, it can also be made after the device is open using the methods vpr::BlockIO::enableBlocking() and vpr::BlockIO::enableNonBlocking(). Typically, the blocking/non-blocking state should be set exactly once (either before or after opening the device). In some cases, it is not possible to change the state after a critical “point of no return.” Refer to the section called “Fixed Blocking State” for more information on this.

Instances of vpr::Socket cannot be created because the constructors are not public. Instances of the concrete types vpr::SocketDatagram and vpr::SocketStream can be used polymorphically as instances of vpr::Socket (and vpr::BlockIO, of course). Because the basic operations such as read() and write() are defined by the base class, using the concrete socket types polymorphically could be a convenient mechanism for mixing socket communication protocols in an application.

Due to the semantics of sockets on Windows NT, the VPR socket abstraction contains a slight variation of the behavior that is available on UNIX-based systems. In Windows, once a call to read(), write(), accept(), etc., is made, the blocking state of the socket is fixed^[3]. That is, if the socket is a blocking socket, it will forever remain in a blocking socket after one of these calls. The same is true for non-blocking sockets. Furthermore, for a stream-oriented socket that is accepting connections, the sockets created as clients connect inherit the blocking state of the accepting socket. The full list of methods that fix the blocking state is as follows:

The NSPR documentation has a more complete description of this issue. We must implement our socket abstraction in this way in order to provide consistent semantics (not just consistent syntax) across platforms.

The acceptor is created using a vpr::InetAddr object that specifies the address on which the acceptor listens for incoming connection requests. Once opened, the acceptor is ready to accept new connections. The call to vpr::SocketAcceptor::accept() uses the same arguments and behavior as vpr::SocketStream::accept(), so programmers already familiar with setting up an accepting socket with vpr::SocketStream will find vpr::SocketAcceptor very easy to use.

The connector is designed to make non-blocking connections easy to manage. Depending on the arguments passed to vpr::SocketConnector::connect(), a socket may be put into non-blocking mode if it is not already set as such. Thus, a connection can be made “in the background” if necessary. However, due to the semantics described in the section called “Fixed Blocking State”, after a background connection is made, the socket must remain in non-blocking mode for the duration of its lifetime.

The following example illustrates how to create a thread that will execute a free function called run() that takes no arguments. The prototype for run() is:

void run();

This will be the same across all platforms. The thread creation code is then:

vpr::Thread* thread;

thread = new vpr::Thread(run);

At this point, a newly spawned thread is executing the code in run(). It is advisable to hang onto the variable thread so that the thread may be controlled as necessary.

That was pretty easy. What if you want to pass one or more arguments to run() so that its behavior can be modified based on some variables? One approach is to define the function so that it takes a parameter that is an aggregate type (a struct or a class). The data needed by the function is then collected into this aggregate type and packaged with the function pointer. A common way to do this is as follows:

struct ThreadArgs
{
   int id;
   std::string name;
   // And so on...
};

void run(const ThreadArgs& args)
{
   // Do work ...
}

void someFunc()
{
   // Other code ...

   ThreadArgs args;
   args.id = 50;
   args.name = "My Thread";
   // And so on ...

   vpr::Thread* thread;
   thread = new vpr::Thread(boost::bind(run, args);
}

When creating a single thread, this works beautifully. If multiple threads are needed, all taking the same type of argument, there would usually have to be a separate argument structure instance for each one. A bunch of objects can be declared, or the same objects can be reused over and over.

The preceding example made use of Boost.Bind to couple the run() function with a struct instance. Instead of declaring a struct to bundle all the arguments together, we could take advantage of the flexibility of Boost.Bind to couple multiple arguments with the function. This is shown below:

void run(int id, char* name)
{
   // Do work ...
}

void someFunc()
{
   // Other code ...

   vpr::Thread* thread;
   thread = new vpr::Thread(boost::bind(run, 50, "My Thread"));
}

There is a limit to the number of parameters that can be passed in this way, so this approach must be used judiciously. We will explain more about function objects and Boost.Bind in the section called “Thread Functors”.

Once we have a thread running, it is often useful to synchronize another thread so that its execution halts until the running thread has completed. This is called “joining threads”. The following example illustrates how this can be done:

vpr::Thread* thread;

thread = new vpr::Thread(run);

// Do other things while the thread is going ...

thread->join();

// Now that the thread is done, continue.

Here, the creator of thread can be another vpr::Thread, or it can be the main thread of execution. In other words, any thread can create more threads and control them. What happens in this example is that thread is created and begins running. Meanwhile, the creator thread continues to do some more work and then must wait for thread to finish its work before continuing. It calls the join() method, a blocking call, and it will not return until thread has completed.

While it is not demonstrated here, the join() method can take a single argument of type void**. It is a pointer to a pointer where the exit status of the joined thread is stored. The operating system fills the pointed to pointer with the exit status when the thread exits.

Sometimes, it may be necessary to suspend the execution of a running thread and resume it again later. There are two methods in the vpr::Thread interface that do just this. Assuming that there is already a running thread pointed to by the object thread, it can be suspended as follows:

thread->suspend();

Resuming execution of the suspended thread is just as easy:

thread->resume();

If something goes wrong when suspending or resuming, vpr::IllegalArgumentException is thrown. Otherwise, these methods return nothing upon successful completion.

Changing the priority of a thread tells the underlying operating system how important a thread is and gives it hints about how to schedule the threads. If no value for the priority is given to the constructor, all vpr::Threads are created with the default priority for all threads. Values higher than 0 for the priority request a higher priority when the thread is created.

Besides being able to set the priority when the thread is created, it is possible to query and to adjust the priority of a running thread. Assuming that there is already a running thread pointed to by the object thread, its priority can be requested as follows:

int prio;

thread->getPrio(&prio);

The thread's priority is stored in prio and returned via the pointer passed to the getPrio() method. Setting that thread's priority is also easy:

int prio;

// Assign some priority value to prio ...

thread->setPrio(prio);

If something goes wrong when querying or changing the priority of the thread, vpr::IllegalArgumentException is thrown. Otherwise, these methods return nothing upon successful completion.

On UNIX-based systems, a signal is sent to a process using the kill(2) system call. With POSIX threads, signals are sent using pthread_kill(3). VPR's thread interface implements these ideas using a kill() method. There are two ways to call this method: with an argument naming the signal to be delivered to the thread or without an argument which cancels the thread's execution. The first of these is described in this section, and the second is described in the next section.

A problem does arise here, unfortunately. Signals are not supported on all operating systems (notably, Win32). The interface is consistent, but code written on IRIX will not compile on Win32 if, for example, it sends a SIGHUP to a thread. An improved thread interface is being designed to overcome problems such as this one. For now, we describe this part of the interface as though it is supported completely on all platforms.

As usual, assume there is a running thread, a pointer to which is stored in thread. To send it a signal (SIGINT, for example), use the following:

thread->kill(SIGINT);

The signal will be delivered to the thread by the operating system, and the thread is expected to handle it properly. This version of the kill() method throws vpr::IllegalArgumentException if an error occurs. Otherwise, this method returns nothing upon successful compltion.

As described in the previous section, using the kill() method with no argument cancels the execution of the thread. When using POSIX threads, this is actually implemented using pthread_cancel(3). On IRIX with SPROC threads, a SIGKILL is sent to the thread to end its execution forcibly. The syntax for using this method is basically the same as in the previous section, but it is repeated to make that clear. Again assuming that there is a running thread with a pointer to its vpr::Thread object stored in thread, use the following:

thread->kill();

Unlike the syntax used to send a signal to a thread, this version of kill() does not have a return value.

Users of POSIX threads may be wondering if the vpr::Thread API provides a way to set cancellation points in the code. Unfortunately, it does not at this time. Extending the interface in this way is being considered, but cancellation points do not have meaning with all thread implementations.

Lastly, it is common to request the currently running thread's identifier. This only makes sense when called from a point on that thread's flow of execution. (In POSIX threads, this is the notion of “self”. For IRIX SPROC threads, this means getting the process ID.) The vpr::Thread API provides a static method that can be called at any time in the thread that is currently running. It returns a pointer to a vpr::BaseThread (the basic type from which vpr::Thread inherits its interface). The syntax is as follows:

vpr::BaseThread* my_id;

my_id = vpr::Thread::self();

The returned pointer can then be used to perform all of the previously described operations on the current thread.

The current threading implementation in VPR is a little difficult to understand. The code is not complicated at all, but because all platform-specific implementations are referred to as vpr::Threads, the details can get lost in the shuffle. To begin, the current list of platform-specific thread implementation wrapper classes are:

The interface itself is defined in vpr::BaseThread, and all of the above classes inherit from that class.

The threading implementation used is chosen when VPR is compiled. To use a certain type of thread system, be sure that the version of VPR in use was compiled with the type of threads desired. When the VPR build is configured, preprocessor #define statements are made in vpr/vprDefines.h that describe the threading system to use. Based on that, the header file vpr/Thread/Thread.h makes several typedefs that set up one of the platform-specific thread implementations to act as the vpr::Thread interface. For example, if compiling on Win32, the class vpr::ThreadWin32 is typedef'd to be vpr::Thread. Since the interface is consistent among all the wrappers, everything works as though that was the way it was written to behave.

The current implementation is modeled after the POSIX thread API for the most part. When designing it, we approached it with the idea that having a more complete API was more important than having a “lowest-common-denominator” API. That is, just because not all threading implementations support a specific feature does not mean that the API should suffer by not having that feature. Whether this was a good approach or not is an open debate.

As mentioned, a functor is used in VPR with vpr::Threads. VPR threads utilize Boost.Function as the functor implementation. A Boost.Function object is a callable object, meaning that it has an overload of operator() that takes zero or more arguments. Earlier in the section called “Creating Threads”, we saw how to use raw function pointers. Boost.Function can wrap four different types of callable types:

Programmers already familiar with the use of Boost.Function and Boost.Bind can skip this entire section about thread functors. The remainder of this section is an overview of how to use Boost.Function and Boost.Bind for programmers who are unfamiliar with these tools.

Getting back to functors, a functor is simply another object type that happens to encapsulate a user-defined function. The details on how this is done are not important here. What is important to know is that a functor can be thought of as a normal function. When using them, programmers usually just implement a function and then pass the function pointer to the Boost.Function constructor. Boost.Function does the rest.

The functor must behave as a function that returns nothing and takes no parameters. In terms of function pointers, the type must be void(*)(void). A more readable form of this is the Boost.Function type: boost::function<void()>. Yet another form is the portable Boost.Function type used for older compilers: boost::function0<void>. Remember that we are not restricted to using function pointers to create functions. We are describing here callable objects that behave as functions.

If the functor needs to be passed arguments, then Boost.Bind must used to couple parameters with the functor. Those parameters will be passed into the function later when the functor is invoked. Boost.Bind is very powerful, and the full usage of it is beyond the scope of this document. We will demonstrate its use more fully later in this section, but we provide some uses in Example 5.1, “Using Boost.Bind to Create Thread Functors”.

struct ThreadArgs
{
   int id;
   std::string name;
};

void run1(const ThreadArgs& args);
void run2(const int id, const std::string& name);

class MyClass
{
public:
   // Bind a free function with an instance of an aggregate type.
   void spawnThread1()
   {
      ThreadArgs args = { 50, "My Thread" };
      mThread = new vpr::Thread(boost::bind(run1, args));
   }

   // Bind a free function with an instanced of an aggregate type that
   // is a data member.
   void spawnThread2()
   {
      // Copies mArgs.
      mThread = new vpr::Thread(boost::bind(run1, mArgs));

      // Passes a reference to mArgs.
      mThread = new vpr::Thread(boost::bind(run1, boost::ref(mArgs)));
   }

   // Bind a free function with multiple parameters.
   void spawnThread2()
   {
      mThread =
         new vpr::Thread(boost::bind(run2, 50,
                                     std::string("My Thread")));
   }

   // Bind a static member function with an argument.
   void spawnThread3()
   {
      mThread = new vpr::Thread(boost::bind(MyClass::staticRun, 10));
   }

   // Bind a non-static member function.
   void spawnThread4()
   {
      mThread = new vpr::Thread(boost::bind(&MyClass::run, this));
   }

   // Bind a non-static member function with multiple parameters.
   void spawnThread5()
   {
      mThread = new vpr::Thread(boost::bind(&MyClass::run, this,
                                            3.14159f, 16));
   }

private:
   static void staticRun(int id);

   void run();

   void otherRun(const float someParam, short otherParam);

   vpr::Thread* mThread;
   ThreadArgs   mArgs;
};

Once a functor object exists, it is passed to the vpr::Thread constructor, and the new thread will execute the functor (which knows what to do with its held callable). The end result is the same as using a normal C/C++ free function or a static class member function, but there is one special benefit: with functors, non-static class member functions can be passed. In many cases, there arises a need to run a member function in a separate thread, but making it static is infeasible or awkward. Thus, it would be best to pass a non-static member function to the created thread. To get access to the non-static data members, however, the C++ this pointer must be available to the thread. By using Boost.Bind with Boost.Function, that is all handled behind the scenes so that passing a non-static member function is straightforward. We have seen how to do this in the methods MyClass::spawnThread4() and MyClass::spawnThread5().

Before getting into specifics, there is a header file that must be included to use Boost.Function VPR thread functors. In this case, the header is boost/function.hpp. If Boost.Bind is needed, then boost/bind.hpp must be included. Finally, if boost::ref() is needed, then boost/ref.hpp must be included.

We have already seen examples of how to create a Boost.Function functor for a member function. In this section, we will review in more detail using Boost.Function and Boost.Bind to accomplish this. Just as with free functions, the member functions (heretofore referred to as “methods”) must have the following prototype:

void methodName();

A common example of using vpr::Thread with a member function as the functor callable is shown in Example 5.2, “Member Function for Thread Functor (1)”. The key aspect in this example is the implementation of the method MyObject::start(). The usage of Boost.Bind here is required because the object pointer has to be bound with the member function pointer in order for it to be invoked properly. Fortunately, this use is very simple—much simpler than the use of vpr::ThreadMemberFunctor<T> in VPR 1.0.

class MyObject
{
public:
   MyObject()
      : mThread(NULL)
      , mRunning(false)
   {
   }

   ~MyObject()
   {
      if ( mRunning )
      {
         stop();
      }

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

   void start()
   {
      mThread  = new vpr::Thread(boost::bind(&MyObject::run, this));
      mRunning = true;
   }

   void stop()
   {
      mRunning = false;
      mThread->join();
   }

private:
   void run()
   {
      while ( mRunning )
      {
         // Do work ...
      }
   }

   vpr::Thread* mThread;
   bool         mRunning;
};

Now let us say that there is the method MyObject::run() needs to take one or more arguments. Boost.Bind makes this possible, and it is just as easy as what we have seen in the previous example. We simply have to bind the method arguments along with the this pointer, as shown in Example 5.3, “Member Function for Thread Functor (2)”. For the purposes of this example, we have changed MyObject::start() so that it takes an argument that specifies how many iterations the thread loop will perform before exiting.

void MyObject::start(const int runCount)
{
   mThread = vpr::Thread(boost::bind(&MyObject::run, this, runCount));
}

void MyObject::run(const int runCount)
{
   for ( int i = 0; i < runCount; ++i )
   {
      // Do work ...
   }
}

What if the thread spawning is happening externally to the class that does the work? Once again, Boost.Bind will be necessary, and as we will see, the usage is familiar. Instead of using this, we use the object instance created by the external code. We will change the declaration of MyObject and assume that there is an aggregate type thread_args_t declared somewhere. The code shown in Example 5.4, “Member Function for Thread Functor (3)” demonstrates how we make this happen, though it is a contrived example. Note that the memory allocated for args would have to be deleted at some point after the thread is done using the data. That could be done at the end of MyObject::run() or after the thread is known to have completed its execution.

struct thread_args_t;

class MyObject
{
public:
   void run(thread_args_t* args)
   {
      // Do work ...
   }
};

void spawnThread()
{
   MyObject* my_obj = new MyObject();
   thread_args_t* args = new thread_args_t();
   // Fill in the arguments to be passed to the thread...

   vpr::Thread* thread = new vpr::Thread(boost::bind(&MyObject::run,
                                                     my_obj, args));
}

Creating so many heap-allocated objects is rather a hassle. Parameters passed to boost::bind() are copied by default. This allows the memory to be coupled with the functor so that it is available when the functor is invoked later. This means that it is safe to use stack-allocated memory when calling boost::bind(). It is not always desirable to have all the data copied, and that is where boost::ref() comes into the picture. In Example 5.5, “Member Function for Thread Functor (4)”, we see an example of using boost::ref() to create a reference to the instance of MyObject while copying in the object of type thread_args_t. Since my_obj is passed by reference, the memory should not actually be allocated on the heap. Rather, it would normally be a data member for the class creating the thread. More generally, my_obj cannot be deleted before the created thread exits. If my_obj is deleted while the thread is running, the application will crash. This is true of all data bound to the function called by the spawned thread.

MyObject my_obj;
thread_args_t args;

// Fill in the arguments to be passed to the thread...

vpr::Thread* thread = new vpr::Thread(boost::bind(&MyObject::run,
                                                  boost::ref(my_obj),
                                                  args));

Functors for threads can be created for non-member functions. The process is basically the same as for using static member functions. The only real difference is that the class scoping does not need to be used since the non-member functions will not be in a class. A simple example of this is shown in Example 5.9, “Non-Member Function for Thread Functor”. As usual, proper memory management would be needed for the allocated vpr::Thread object. And, of course, parameters to the non-member function can be bound to the function using Boost.Bind.

void run()
{
   // Do some work ...
}

void startThread()
{
   vpr::Thread* thread = new vpr::Thread(run);
}

A new capability not (easily) available with VPR 1.0 is the use of callable objects as functors. This means using an instance of a type that overloads operator() as the callable handled by Boost.Function. One way of doing this is shown in Example 5.10, “Callable Object for Thread Functor (1)”. Note that a copy of c will be made for use when the functor is invoked in the spawned thread.

class Callable
{
public:
   void operator()()
   {
      // Do some work ...
   }
};

void startThread()
{
   Callable c;
   vpr::Thread* thread = new vpr::Thread(c);
}

A more interesting use of a callable object would be one that has state. There are two ways of using a stateful callable object. The first is to use data members in the class (or struct) declaration that are then accessed by the overload of operator(). This is a very simple thing to do since having data members in a class is so common.

The other is to use our old friend Boost.Bind, though it is not as simple as in previous cases. Since Boost.Bind is designed for binding parameters to function pointers, we have to use a proper function pointer—or use Boost.Function. In Example 5.11, “Callable Object for Thread Functor (2)”, we see how Boost.Bind is used to bind the parameter value 5 to the invocation of c.operator()(int). This is not nearly as simple as what was shown in Example 5.10, “Callable Object for Thread Functor (1)”, even if data members of Callable had to be initialized.

class Callable
{
public:
   void operator()(int arg)
   {
      // Do some work ...
   }
};

void startThread()
{
   Callable c;
   vpr::Thread* thread =
      new vpr::Thread(boost::bind(&Callable::operator(), c, 5));
}

Since we are working with a callable object, it stands to reason that we should be able to leverage Boost.Function somehow. In Example 5.12, “Callable Object for Thread Functor (3)”, we see how boost::function<T> can be used to reduce the apparent complexity of binding the parameter value 5 to the invocation of c.operator()(int). To some, this may look a little more friendly since there is no member function pointer required. Ultimately, it requires slightly more typing than the previous example. Either way, neither of these approaches are very pleasing to the eye, but they do work. One of these approaches may be necessary to use a legacy callable type with vpr::Thread.

class Callable
{
public:
   void operator()(int arg)
   {
      // Do some work ...
   }
};

void startThread()
{
   Callable c;
   vpr::Thread* thread =
      new vpr::Thread(boost::bind(boost::function<void(int)>(c), 5));
}

In VPR 1.0, thread functors were handled by subclasses of vpr::BaseThreadFunctor. While this approach worked, it was not anywhere near as flexible as what is possible with Boost.Function and Boost.Bind. What has been presented here is for VPR 1.1 and beyond. For those users updating from VPR 1.0, we now present the simple process of changing code using the VPR 1.0 thread API to the VPR 1.1 API.

First, the signature for the function called by the spawned thread in VPR 1.0 took a single void* parameter. In VPR 1.1, the function takes no argument. This change was made for two reasons. First, most functions ignored this parameter, so it was wasted memory on the stack. Second, void* is a notoriously poor choice for a type since it can point to anything. C++ is a strongly typed language, and we should be taking advantage of that feature. However, since the presence of the parameter acknowledged that it was often necessary to pass data into the thread function, it is still possible to do this using Boost.Bind. What this means is that the callable invoked by the functor can have any signature, but the default behavior is for it to return nothing and take no parameters.

Next, the types vpr::ThreadNonMemberFunctor, vpr::ThreadMemberFunctor<T>, and vpr::ThreadRunFunctor<T> have been removed, as has the header file vpr/Thread/ThreadFunctor.h. The functionality provided by those types has been offloaded to Boost.Function and Boost.Bind. In so doing, the flexibility of how threads are spawned has been increased immensely while actually making it simpler to spawn them.

For uses of vpr::ThreadNonMemberFunctor, quite a bit less code has to be written to spawn a thread. We see in Example 5.13, “VPR 1.0 Use of Thread Non-Member Functor” how this type was used with VPR 1.0 to spawn a thread that executed a static member function. Then, in Example 5.14, “Updated Use of Static Member Function for Thread Functor”, we see the equivalent code using the VPR 1.1 (and newer) interface. No longer must a functor object to instantiated on the heap and stored for later deletion^[4]. Moreover, there is no need to pass NULL as the parameter value, though if a parameter value is needed, then Boost.Bind must be used. Refer to the section called “Functors from Static Member Functions” for more details on this topic.

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

class MyClass_VPR10
{
public:
   void start()
   {
      mFunctor =
         new vpr::ThreadNonMemberFunctor(MyClass_VPR10::run, NULL);
      mThread = new vpr::Thread(mFunctor);
   }

private:
   static void run(void* args)
   {
      // Do some work ...
   }

   vpr::ThreadNonMemberFunctor* mFunctor;
   vpr::Thread* mThread;
};

#include <vpr/Thread.h>

class MyClass
{
public:
   void start()
   {
      mThread = new vpr::Thread(MyClass::run);
   }

private:
   static void run()
   {
      // Do some work ...
   }

   vpr::Thread* mThread;
};

To use a non-static member function, either vpr::ThreadMemberFunctor<T> or vpr::ThreadRunFunctor<T> was used with VPR 1.0, as shown in Example 5.15, “VPR 1.0 Use of Thread Member Functor”. Now, Boost.Bind comes to our rescue and vastly simplifies the code needed to accomplish the very same thing. In Example 5.16, “Updated Use of Member Function for Thread Functor”, we see just how much less code is required. The nice thing is that the parameters that were passed to the vpr::ThreadMemberFunctor<T> constructor are nearly the same as what must be passed to boost::bind(). The order for the this pointer and the member function pointer are simply reversed—and the NULL value for the function argument is removed. If arguments need to be passed to the function, pass them in as arguments to boost::bind() after the this pointer. Refer to the section called “Functors from (Non-Static) Member Functions” for more details on this topic.

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

class MyClass_VPR10
{
public:
   void start()
   {
      mFunctor =
         new vpr::ThreadMemberFunctor<MyClass_VPR10>(
            this, &MyClass_VPR10::run, NUL
         );
      mThread = new vpr::Thread(mFunctor);
   }

private:
   void run(void* args)
   {
      // Do some work ...
   }

   vpr::ThreadMemberFunctor<MyClass_VPR10>* mFunctor;
   vpr::Thread* mThread;
};

#include <boost/bind.hpp>
#include <vpr/Thread/Thread.h>

class MyClass
{
public:
   void start()
   {
      mThread = new vpr::Thread(boost::bind(&MyClass::run, this));
   }

private:
   void run()
   {
      // Do some work ...
   }

   vpr::Thread* mThread;
};

As with threads, a cross-platform abstraction layer has been written to provide a consistent way to use semaphores on all supported platforms. The primary goal behind the interface design is to provide the common P (acquire) and V (release) operations. The interface does include methods for read/write semaphores, but as of this writing, that part of the interface is not complete. Because of that, the use section does not cover that part of the interface. When the implementation is complete, this section will be expanded.

As always, there is a header file that must be included to use vpr::Semaphore. This time around, the file is vpr/Sync/Semaphore.h. Do not include any of the platform-specific implementation files. That is all handled appropriately within vpr/Sync/Semaphore.h.

When creating a vpr::Semaphore object, give the initial value that represents the number of resources being controlled by the semaphore. If no value is given, the default is 1 which of course gives a binary semaphore. Binary semaphores are better known as mutexes (see the section called “Mutual Exclusion: Using vpr::Mutex” for more information about mutex use in VPR). An example of creating a simple semaphore to control access to five resources is as follows:

vpr::Semaphore sema(5);

This creates a semaphore capable of controlling concurrent access to five resources. At some point, if there is a need to change the number of resources, a method called reset() is provided. Pass the new number of resources, and the semaphore object is updated appropriately:

sema.reset(4);

The semaphore sema now controls access to only four resources.

Creation of a semaphore can fail, and if it does, the vpr::Semaphore constructor throws an exception of type vpr::ResourceException. If creation of the semaphore succeeds, then lock and unlock operations on that semaphore are guaranteed to succeed.

When a thread needs to acquire access to shared data, it locks a semaphore. In the vpr::Semaphore interface, this is accomplished using the acquire() method:

sema.acquire();

As expected, acquire() is a blocking call, so if the semaphore's value is less than or equal to 0, the thread requesting the lock will block until the semaphore's value is greater than 0. If the acquisition of the semaphore would cause a deadlock (because the thread already holds the semaphore lock), vpr::DeadlockException is thrown. Otherwise, the method is guaranteed to return when the lock is acquired.

Finally, when access to the critical section is complete, the semaphore is released using the release() method:

sema.release();

This method is guaranteed to return successfully.

Those who have read the Gory Details section for vpr::Threads will find this section very familiar. As with vpr::Threads, there are several platform-specific semaphore implementation wrapper classes:

Unlike vpr::Thread, however, there is no base interface from which these implementations inherit. Performance decreases caused by virtual functions are avoided this way.

The semaphore implementation used is chosen when VPR is compiled and will always match the thread implementation being used. When the VPR build is configured, preprocessor #define statements are made in vpr/vprDefines.h that describe the threading system and thus the semaphores to use. Based on that, the header file vpr/Sync/Semaphore.h makes several typedefs that set up one of the platform-specific implementations to act as the vpr::Semaphore interface. For example, if compiling on Linux, the class vpr::SempahorePosix is typedef'd to vpr::Semaphore. Since the interface is consistent among all the wrappers, everything works as though that was the way it was written to behave.

The cross-platform mutex abstraction in VPR is critical for synchronizing access to shared data. Those who have read the section on vpr::Semaphore will find this section very, very familiar. The interface for vpr::Mutex is a subset of that for vpr::Semaphore since mutexes are binary semaphores. They can be locked and unlocked. That is all there is to know. The vpr::Mutex interface does include some methods for read/write mutexes, but this implementation is incomplete and is not documented here for that reason. When the implementation is finished, this documentation will be expanded.

The header file to include for using vpr::Mutex is vpr/Sync/Mutex.h. As with other classes discussed in this chapter, it is important not to include the platform-specific header files.

When creating a vpr::Mutex object, there are no special parameters to pass or considerations to be made. An example of creating a mutex is as follows:

vpr::Mutex mutex;

Creation of a mutex can fail, and if it does, the vpr::Mutex constructor throws an exception of type vpr::ResourceException. If creation of the mutex succeeds, then lock and unlock operations on that mutex are guaranteed to succeed.

When a thread needs to acquire access to shared data, it can lock a mutex. In the vpr::Mutex interface, this is accomplished using the acquire() method:

mutex.acquire();

As expected, acquire() is a blocking call, so if the mutex is already locked by another thread, the thread requesting the lock will block until the mutex is released by the other thread. If the acquisition of the mutex would cause a deadlock (because the thread already holds the mutex), vpr::DeadlockException is thrown. Otherwise, the method is guaranteed to return when the lock is acquired.

If there is a need to lock a mutex only when the call would not block, a method is provided to do this. It is called tryAcquire(), and it will not block if the mutex is already locked. It works as follows:

const bool locked = mutex.tryAcquire();

If the mutex is locked, true is returned. Otherwise, false is returned. The call does not block.

In addition to conditional locking, the state of a mutex can be tested to see if it is locked or unlocked. This is done using the test() method as follows:

const bool locked = mutex.test();

If the mutex is not locked, false is returned. Otherwise, true is returned.

When access to the critical section is complete, a locked mutex is released using the release() method:

mutex.release();

This method is guaranteed to return successfully.

Those who have read the Gory Details sections for vpr::Threads or for vpr::Semaphores will find this last section very familiar (and probably uninteresting at this point). As with vpr::Threads and vpr::Semaphores, there are several platform-specific mutex implementation wrapper classes:

Similar to vpr::Semaphore, there is no base interface from which these implementations inherit. Performance issues caused by virtual functions are avoided by doing this.

The mutex implementation used is chosen when VPR is compiled and will always match the thread implementation being used. When the VPR build is configured, preprocessor #define statements are made in vpr/vprDefines.h that describe the threading system and thus the mutexes to use. Based on that, the header file vpr/Sync/Mutex.h makes several typedefs that set up one of the platform-specific implementations to act as the vpr::Mutex interface. For example, if compiling on Solaris, the class vpr::MutexPosix is typedef'd to be vpr::Mutex. Since the interface is consistent among all the wrappers, everything works as though that was the way it was written to behave.

The interface for vpr::CondVar is very similar to that of vpr::Mutex. This is because every instance of vpr::CondVar contains an instance of vpr::Mutex. Thus, acquiring and releasing a condition variable actually acquires and releases the contained mutex.

The header file to include for using vpr::CondVar is vpr/Sync/CondVar.h. As with other classes discussed in this chapter, it is important not to include the platform-specific header files.

When creating a vpr::CondVar object, there are no special parameters to pass or considerations to be made. An example of creating a condition variable is as follows:

vpr::CondVar cv;

Creation of a condition variable can fail, and if it does, the vpr::CondVar constructor throws an exception of type vpr::ResourceException. If creation of the condition variable succeeds, then lock and unlock operations on that condition variable are guaranteed to succeed.

In addition to the vpr::CondVar instance, there is usually some associated variable whose value will be tested and modified by various threads. For our purposes, we will use a boolean variable:

bool state_var;

When a thread needs to acquire access to shared data, it can lock a condition variable. In the vpr::CondVar interface, this is accomplished using the acquire() method:

cv.acquire();

As expected, acquire() is a blocking call, so if the condition variable's mutex is already locked by another thread, the thread requesting the lock will block until the mutex is released by the other thread. If the acquisition of the condition variable's lock would cause a deadlock (because the thread already holds the lock), vpr::DeadlockException is thrown. Otherwise, the method is guaranteed to return when the lock is acquired.

If there is a need to lock a condition variable's mutex only when the call would not block, a method is provided to do this. It is called tryAcquire(), and it will not block if the mutex is already locked. It works as follows:

const bool locked = cv.tryAcquire();

If the condition variable's mutex is locked, true is returned. Otherwise, false is returned. The call does not block.

When access to the critical section is complete, a locked condition variable is released using the release() method:

cv.release();

This method is guaranteed to return successfully.

Prior to calling vpr::CondVar::release(), it is almost always necessary to call vpr::CondVar::signal() (or vpr::CondVar::broadcast()) to inform any waiting threads that the condition on which they are waiting may have changed. The next section describes this procedure in greater detail.

So far, we have seen how to lock and unlock a condition variable, but we have not seen how to use a condition variable. Let us say that we have two threads running concurrently. One thread is performing an operation, and the other thread must wait until that operation is complete. Condition variables work wonderfully in such a situation. For the following description, we will call the first thread the worker thread and the second thread the waiting thread. For the example, we will use the condition variable cv and the boolean flag state_var, introduced above. Initially, state_var will be set to false to indicate that the worker thread has not done its job yet.

cv.acquire();
{
   while ( state_var == false )
   {
      cv.wait();
   }
}
cv.release();

cv.acquire();
{
   // Perform our critical task ...

   state_var = true;
   cv.signal();
}
cv.release();