Vault Threads

Classes
class	VMutex
	VMutex implements a platform-independent mutex that you can embed in an object or place on the stack to guarantee its cleanup when the VMutex object is destructed. More...
class	VMutexLocker
	VMutexLocker is a helper class that you can use to make working with mutexes easier, and more importantly to guarantee proper release behavior of a VMutex even when exceptions are raised. More...
class	VSemaphore
	VSemaphore implements a platform-independent semaphore that you can embed in an object or place on the stack to guarantee its cleanup when the VSemaphore object is destructed. More...
class	VThread
	VThread is class that provides an easy way to create a thread of execution. More...
class	VListenerThread
	A VListenerThread is a thread whose run() method listens on a socket and creates a new VSocket for each incoming connection and a VSocketThread object to manage each such VSocket. More...

---

Detailed Description

Overview

The Vault's thread-related facilities make it easy to create multiple threads of concurrent execution, starting with VThread. Care is still needed to make those threads safely cooperate with shared data, and you can use VMutex and VMutexLocker to implement that consistently and safely. Finally, VSemaphore can be used to implement message-passing between threads.

Threads

VThread is the abstract base class from which you will derive your thread classes. Your subclass just needs to override the run() method. Your code there is executed in its own thread and that thread lives until the run() method returns. After instantiating a thread object, call its start() method to get it running. Call its join() method to cause the calling thread to block until the thread completes. Call its stop() method to notify it that it should complete at its next opportunity. See the VThread documentation for complete details on all that.

Locking

VMutex is a mutual exclusion lock for synchronization. Use a mutex to prevent multiple threads from accessing the same resource at the same time. However, the code that attempts to access the lock should usually do so via a VMutexLocker object (see below) to guarantee correct unlocking behavior. You'll usually declare a VMutex as an instance variable of a class that needs to synchronize access to one of its resources. That mutex is associated with a particular resource, and callers must aqcuire the lock before accessing the resource. When an attempt is made to acquire the lock, the calling thread blocks until it is able to acquire the lock; only one thread can own the lock at any given moment in time.

VMutexLocker is a helper class for ensuring proper lock/unlock behavior around a VMutex object. The code that needs to acquire a VMutex lock will usually declare a temporary VMutexLocker object on the stack to acquire the lock, and the lock will be released when the VMutexLocker destructs, or earlier via an explicit call. This ensures proper unlocking even if an exception is thrown by some called function. Otherwise, the caller would have to be sure to catch all exceptions and call unlock() on the mutex object, which leads to ugly and error-prone code. VMutexLocker make the correct behavior trivial. See the VMutexLocker documentation for details.

Signaling

VSemaphore is a low-level mechanism for allowing threads to communicate by waiting for signals from each other; while a thread is waiting on a semaphore, it is blocked and does not consume the CPU. Another thread can signal the semaphore, causing exactly one of the waiting threads to wake up. A thread that is awakened simply is unblocked from its wait call. A semaphore is often used as a way of threads posting messages to each other, such that a receiving thread sleeps if there are no messages for it to process, yet wakes up the moment a message is available. See the VSemaphore documentation for details. VSemaphore is used by VMessageQueue and VMessageOutputThread to provide a high-level facility for passing messages between threads.