diff --git a/doc/concepts.xml b/doc/concepts.xml index bff619c7..63434a7f 100644 --- a/doc/concepts.xml +++ b/doc/concepts.xml @@ -8,7 +8,7 @@ Concepts
Mutexes - A mutex (short for mutual-exclusion) object is used to serializes + A mutex (short for mutual-exclusion) object is used to serialize access to a resource shared between multiple threads. The Mutex concept, with TryMutex and @@ -16,7 +16,7 @@ formalize the requirements. A model that implements Mutex and its refinements has two states: locked and unlocked. Before using a shared resource, a - thread locks a Boost.Threads mutex object + thread locks a &Boost.Threads; mutex object (an object whose type is a model of Mutex or one of it's refinements), ensuring @@ -28,7 +28,7 @@ APIs, expose functions to lock and unlock a mutex object. This is dangerous since it's easy to forget to unlock a locked mutex. When the flow of control is complex, with multiple return points, the likelihood of forgetting to - unlock a mutex object would become even greater. When exceptions are thrown, + unlock a mutex object becomes even greater. When exceptions are thrown, it becomes nearly impossible to ensure that the mutex object is unlocked properly when using these traditional API's. The result is deadlock. @@ -38,10 +38,10 @@ Lock concept is employed where the lock object's constructor locks the associated mutex object and the destructor automatically does the unlocking. The - Boost.Threads library takes this pattern to + &Boost.Threads; library takes this pattern to the extreme in that Lock concepts are the only way to lock and unlock a mutex object: lock and unlock functions are not exposed by any - Boost.Threads mutex objects. This helps to + &Boost.Threads; mutex objects. This helps to ensure safe usage patterns, especially when code throws exceptions.
@@ -51,16 +51,16 @@ thread already owns a lock on the mutex object.
Recursive Locking Strategy - With a recursive locking strategy when a thread attempts to acquire + With a recursive locking strategy, when a thread attempts to acquire a lock on the mutex object for which it already owns a lock, the operation is successful. Note the distinction between a thread, which may have multiple locks outstanding on a recursive mutex object, and a lock object, which even for a recursive mutex object cannot have any of its lock functions called multiple times without first calling unlock. Internally a lock count is maintained and the owning thread must - unlock the mutex model the same number of times that it's locked it before + unlock the mutex model the same number of times that it locked it before the mutex object's state returns to unlocked. Since mutex objects in - Boost.Threads expose locking + &Boost.Threads; expose locking functionality only through lock concepts, a thread will always unlock a mutex object the same number of times that it locked it. This helps to eliminate a whole set of errors typically found in traditional C style @@ -72,25 +72,25 @@
Checked Locking Strategy - With a checked locking strategy when a thread attempts to acquire a + With a checked locking strategy, when a thread attempts to acquire a lock on the mutex object for which the thread already owns a lock, the operation will fail with some sort of error indication. Further, attempts by a thread to unlock a mutex object that was not locked by the thread will also return some sort of error indication. In - Boost.Threads, an exception of type + &Boost.Threads;, an exception of type boost::lock_error would be thrown in these cases. - Boost.Threads does not currently + &Boost.Threads; does not currently provide any mutex objects that use this strategy.
Unchecked Locking Strategy - With an unchecked locking strategy when a thread attempts to acquire + With an unchecked locking strategy, when a thread attempts to acquire a lock on a mutex object for which the thread already owns a lock the operation will deadlock. In general this locking strategy is less safe than a checked or recursive strategy, but it's also a faster strategy and so is employed by many libraries. - Boost.Threads does not currently + &Boost.Threads; does not currently provide any mutex objects that use this strategy.
@@ -119,9 +119,9 @@ defines which waiting thread shall acquire the lock.
FIFO Scheduling Policy - With a FIFO scheduling policy, threads waiting for the lock will - acquire it in a first come first serve order (or First In First Out). This - can help prevent a high priority thread from starving lower priority + With a FIFO ("First In First Out") scheduling policy, threads waiting + for the lock will acquire it in a first-come-first-served order. + This can help prevent a high priority thread from starving lower priority threads that are also waiting on the mutex object's lock.
@@ -137,7 +137,7 @@
Unspecified Policy The mutex object does not specify a scheduling policy. In order to - ensure portability, all Boost.Threads + ensure portability, all &Boost.Threads; mutex models use an unspecified scheduling policy.
@@ -169,7 +169,7 @@ unlocked. - (&->~M(); + (&m)->~M(); Precondition: m is unlocked. Destroys a mutex object m. @@ -237,41 +237,42 @@
Mutex Models - Boost.Threads currently supplies six + &Boost.Threads; currently supplies six models of Mutex. - Mutex Models - - - - Concept - Refines - Models - - - - - Mutex - - boost::mutex - boost::recursive_mutex - - - TryMutex - Mutex - boost::try_mutex - boost::recursive_try_mutex - - - TimedMutex - TryMutex - boost::timed_mutex - boost::recursive_timed_mutex - - + Mutex Models + + + + Concept + Refines + Models + + + + + Mutex + + boost::mutex + boost::recursive_mutex + + + TryMutex + Mutex + boost::try_mutex + boost::recursive_try_mutex + + + TimedMutex + TryMutex + boost::timed_mutex + boost::recursive_timed_mutex + + +