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 function called run() that takes no arguments. The prototype for run() is:

void run(void* args);

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? Not surprisingly, that is fairly easy too. As mentioned above, if there is more than one argument to pass to the thread function, they will have to be collected into a struct, and pointer to that struct will have to be passed. A common way to do this is as follows:

struct ThreadArgs
{
   int id;
   char name[40];
   // And so on...
};

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

   ThreadArgs* args;
   vpr::Thread* thread;

   args = new ThreadArgs();

   // Fill in the elements of args ...

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

When creating a single thread, this works beautifully. If multiple threads are needed, all taking the same type of argument, there must be a separate argument structure instance for each one. A bunch of pointers can be declared, or the same pointer can be reused over and over. The address passed to each thread will be unique either way. Using this method requires that the argument memory be released before the thread exits, of course.

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();

On successful completion, both methods return vpr::ReturnStatus::Succeed. If the operation could not be performed for some reason, vpr::ReturnStatus::Fail is returned to indicate error status.

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);

On successful completion, both methods return vpr::ReturnStatus::Succeed. If the operation could not be performed for some reason, vpr::ReturnStatus::Fail is returned to indicate error status.

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 returns vpr::ReturnStatus::Succeed if the signal is sent successfully. Otherwise, vpr::ReturnStatus::Fail is returned to indicate that an error occurred.

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::ThreadNSPR 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's threads can execute two types of functions: normal C/C++ functions and class methods or functors. The former was described in the section about using vpr::Threads, and the latter is described here. The use of functors is given more attention because the concept may be foreign to some programmers. Those who already know about functors can skip this short description and go straight to the section on using functors.

In VPR, 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, but they are provided later for those who are interested. What is important to know is that a functor can be thought of as a normal function. When using them, programmers simply implement a function and then pass the function pointer (and the function's optional argument) to the functor's constructor. The object does the rest.

Observant readers may have noticed the parenthetical phrase in the previous paragraph mentioning a function's optional argument. Note that “argument” is singular meaning that only one parameter can be passed to the function that will be run by the created thread. The type of that argument is the wonderfully vague void*, an artifact of basing the threading subsystem on C libraries. As discussed in the section on using vpr::Threads, if there is a need to pass multiple arguments, they must be encapsulated in a struct or a comparable object.

Once a functor object exists, it is passed to the vpr::Thread constructor, and the new thread will execute the functor (which knows about the function). The end result is the same as using a normal C/C++ 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 a VPR functor, that is all handled behind the scenes so that passing a non-static member function is straightforward.

Before getting into specifics, there is a header file that must be included to use VPR thread functors. In this case, the header is vpr/Thread/ThreadFunctor.h. Within this header, vpr::BaseThreadFunctor is declared as an abstract base class. It has two subclasses implementing its interface: vpr::ThreadMemberFunctor and vpr::ThreadNonMemberFunctor. Both of these subclasses will be discussed in turn next.

This implementation of vpr::BaseThreadFunctor is for all functions that fall into the rather elite category of being non-static class member functions. To be more specific, those member functions (heretofore referred to as “methods”) must have the following prototype:

void methodName(void* arg);

Those readers with experience in multi-threaded programming will recognize this prototype instantly. It is no different than that used in common threading implementations. Constructing the functor to use this method, however, is quite different than what readers may have seen before.

Say there is a class MyObject with a method run() having the appropriate prototype that will be executed by a vpr::Thread object. In this case, run() takes an argument that is a pointer to a user-defined type thread_args_t. Also assume that there is an instance of MyObject pointed to by the variable my_obj. The following code creates the vpr::ThreadMemberFunctor object that will encapsulate the method:

vpr::ThreadMemberFunctor<MyObject>* my_functor;
thread_args_t* args;
vpr::Thread* thread;

args = new thread_args_t();

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

my_functor = new vpr::ThreadMemberFunctor<MyObject>(my_obj, &MyObject::run, (void*) args);
thread = new vpr::Thread(my_functor);

The important thing to note in this example is that vpr::ThreadMemberFunctor is a template class. When creating the functor instance, the class must be specified as the template parameter. (If you do not understand this syntax, take a look at a C++ book that covers the current C++ standard.) Also note that when creating the new vpr::Thread object, the argument structure is not passed to the constructor. The argument to run() is packaged up with the function in the functor object my_functor. Once this code has executed, a new thread is spawned that will run the run() method given the provided argument structure.

The vpr::BaseThreadFunctor interface defines an extra method setArg() that allows the function's argument to be set after the functor object is created. The argument to the constructor providing the function's argument is optional and will default to NULL if not specified. At a later time, should there be an argument to provide, the following can be used:

thread_args_t* args = new thread_args_t();

// Fill in args ...

my_functor->setArg(args);

This assumes that there is already a functor object instantiated called my_functor. Alternatively, setArg() could be used to remove a previously defined argument by passing NULL.

The last thing to note is that a lot of memory is being allocated dynamically in the example code. Be careful to deallocate the memory when it is no longer needed.

An extension to the concept of vpr::ThreadMemberFunctor has been written to handle a situation that often arises. Typically, a class will have data members that define the state of a class instance. Thus, when using a member functor to create a thread, the object passed to the vpr::ThreadMemberFunctor constructor probably has all the state information that is required for the thread to execute. In this case, the single void* parameter held by the functor is ignored entirely when the thread executes.

To address this case (and to simplify user code), the class vpr::ThreadRunFunctor exists. A class that implements the “runnable” concept can be used to create a thread with vpr::ThreadRunFunctor. Such a class has a public method named run() that takes no parameters and has a void return type. The declaration of a runnable class would thus appear similar to the following:

class MyClass
{
public:
   void run();

   // Other public methods ...

private:
   // Some internal data members ...
};

To create a thread using this class, the code would appear as follows (assuming the existence of a heap-allocated variable my_obj of type MyClass*):

vpr::ThreadRunFunctor<MyClass>* my_functor =
   new vpr::ThreadRunFunctor<MyClass>(my_obj);
vpr::Thread* my_thread = new vpr::Thread(my_functor);

The spawned thread will execute the method MyClass::run().

While the above code is much simpler than what was presented in the section called “vpr::ThreadMemberFunctor”, there is one major drawback. Namely, the run() method must be public, and it could therefore be invoked outside the scope of an executing thread. This would have to be the case if VPR provided an abstract base class such as Runnable (similar to the Java interface Runnable) with a pure virtual method named run(). If the visibility of the member function executed by the thread is a concern, use vpr::ThreadMemberFunctor.

This implementation of vpr::BaseThreadFunctor is the complement of the set of functions contained by vpr::ThreadMemberFunctor. It is used for normal C/C++ functions and for static class member functions. There is nothing terribly interesting about this class, and its use is straightforward. The following example, an adaptation of that presented in the previous section, shows how to use this interface rather than passing a function pointer and an argument to the vpr::Thread constructor. In this case, assume that the function run() is appropriately defined for use here.

vpr::ThreadNonMemberFunctor* my_functor;
thread_args_t* args;
vpr::Thread* thread;

args = new thread_args_t();

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

my_functor = new vpr::ThreadNonMemberFunctor(run, (void*) args);
thread = new vpr::Thread(my_functor);

That is all there is to it. Programmers end up doing more work than if they had just passed the function pointer and the associated argument to the vpr::Thread constructor directly, but the vpr::Thread constructor is relieved of some work. (The reason for this is described below.) Thus, either way is equally efficient, and what you use is up to you.

The magic behind these functors is done by overloading operator() for vpr::BaseThreadFunctor objects. Both implementations of the interface store the function pointer (and optional argument pointer), and when vpr::BaseThreadFunctor::operator() is invoked, they call the function and pass the argument if there is one. There is a little more magic with the vpr::ThreadMemberFunctor, however, that allows it to work with the non-static methods of a given class.

The class vpr::ThreadMemberFunctor works its extra-special magic through the use of a template and one of C++'s dustier operators, ::*. This operator is used to point to a member of a class. In this case, it points to the method that will be executed by the thread. When used in conjunction with the provided class instance (the this pointer), the non-static method can be invoked by the functor.

One interesting thing to note about vpr::Threads is that they deal only in functors. More specifically, they deal only with objects that subsume to vpr::BaseThreadFunctor. If a function pointer and its argument are passed directly to the vpr::Thread constructor, a vpr::ThreadNonMemberFunctor object is created to package those arguments. That new functor is then used internally by the thread. Thus, whether you choose to create a non-member functor or to pass the function pointer and associated argument, the same code will be executed.

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.

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 lock is acquired, vpr::ReturnStatus::Succeed is returned. If the attempt to lock the semaphore fails for some reason, vpr::ReturnStatus::Fail is returned.

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

sema.release();

If the locked semaphore is released successfully, vpr::ReturnStatus::Succeed is returned. Otherwise, vpr::ReturnStatus::Fail is returned.

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;

There is nothing more to say this time.

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 lock is acquired, vpr::ReturnStatus::Succeed is returned. If the attempt to lock the semaphore fails for some reason, vpr::ReturnStatus::Fail is returned.

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:

mutex.tryAcquire();

If the mutex is locked, vpr::ReturnStatus::Succeed is returned. Otherwise, vpr::ReturnStatus::Fail 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:

int state = mutex.test();

If the mutex is not locked, vpr::ReturnStatus::Fail is returned. Otherwise, vpr::ReturnStatus::Succeed is returned.

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

mutex.release();

If the locked mutex is released successfully, vpr::ReturnStatus::Succeed is returned. Otherwise, vpr::ReturnStatus::Fail is returned.

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;

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 lock is acquired, vpr::ReturnStatus::Succeed is returned. If the attempt to lock the semaphore fails for some reason, vpr::ReturnStatus::Fail is returned.

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

cv.release();

If the locked condition variable is released successfully, vpr::ReturnStatus::Succeed is returned. Otherwise, vpr::ReturnStatus::Fail is returned.

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();