|
Boost.Threadsscoped_try_lock |
Introduction
Header
Synopsis
Members
Example
This class template defines a generic lock type which meets the ScopedTryLock requirements.
The try_mutex,
timed_mutex, recursive_try_mutex
and recursive_timed_mutex classes
use this template to define their scoped_try_lock
types.
Like all the Boost.Threads lock
models, scoped_try_lock
objects are meant to be
short-lived. Objects of the class are not thread-safe, and so should not be
shared between threads.
Class scoped_try_lock
follows the "resource
acquisition is initialization" idiom [Stroustrup 00 14.4.1] and is a
realization of the "Scoped Locking Pattern" [Schmidt-00]. Thus the usage is to
let the constructor do the locking, and then let the destructor do the
unlocking automatically at the end of the enclosing scope. The lock()
and unlock() members are usually not explicitly called, but are
provided to allow for complex overlapping locks of multiple
mutexes.
Although this class is an implementation detail, it is publicly documented here because of its importance.
The type used to instantiate the class must meet the TryMutex requirements.
#include <boost/thread/detail/lock.hpp> This header is usually not included directly by programmers because it is supplied by <boost/thread/mutex.hpp> or <boost/thread/recursive_mutex.hpp>
namespace boost { namespace detail { namespace thread { template <typename TryMutex> class scoped_try_lock : private boost::noncopyable // Exposition only. // Class scoped_try_lock meets the NonCopyable requirement. { public: typedef TryMutex mutex_type; explicit scoped_try_lock(TryMutex& mx); scoped_try_lock(TryMutex& mx, bool initially_locked); ~scoped_try_lock(); void lock(); bool try_lock(); void unlock(); operator const void*() const; }; } // namespace thread } // namespace detail } // namespace boost
explicit scoped_try_lock(TryMutex& mx);
Effects: Associates mutex mx
with
*this
. Calls try_lock()
.
scoped_try_lock(TryMutex& mx, bool initially_locked);
Effects: Associates mutex mx
with
*this
. If initially_locked
is true,
calls lock()
.
~scoped_try_lock();
Effects: If locked()
, calls
unlock()
. Destroys *this
.
void lock();
Effects: If the associated mutex is already locked by another lock in the current thread, the effects depend on the locking strategy of the associated mutex, as shown in the following table:
Locking Strategy of associated mutex |
Effect if associated mutex is already locked by the current thread |
Recursive | As if an additional lock were added to the mutex. |
Checked | Throws lock_error. |
Unchecked | Undefined behavior [ISO 1.3.12] (but typically, deadlock.) |
If the associated mutex is already locked by some other thread, places the current thread in the Blocked state until the associated mutex is unlocked, after which the current thread is placed in the Ready state, eventually to be returned to the Running state. Places the associated mutex in the locked state.
Throws: lock_error if
locked()
or as indicated in Effects.
bool try_lock();
Effects: If the associated mutex is already locked by another lock in the current thread, the effects depend on the locking strategy of the associated mutex, as shown in the following table:
Locking Strategy of associated mutex |
Effect if associated mutex is already locked by the current thread |
Recursive | As if an additional lock were added to the mutex. |
Checked | Throws lock_error. |
Unspecified | Undefined behavior [ISO 1.3.12] (but typically, deadlock.) |
If the associated mutex is not already locked by some other thread, locks the associated mutex and returns true, else returns false.
Returns: See effects.
Throws: lock_error if
locked()
or as indicated in Effects.
void unlock();
Effects: Unlocks the associated mutex.
Throws: lock_error if
!locked()
.
operator const void*() const;
Returns: If the associated mutex is currently locked, a value
convertible to true
, else a value convertible to
false
.
Rationale: A const void*
conversion is
considered safer than a conversion to bool
.
bool locked() const;
Returns: this->operator const void*() !=
0
.
#include <boost/thread/mutex.hpp> #include <iostream> int main(int, char*[]) { boost::mutex mutex; boost::mutex::try_lock lock(mutex); if (lock) std::cout << "locked" << std::endl; else std::cout << "unlocked" << std::endl; return 0; }
The output is:
locked
Revised 05 November, 2001
© Copyright William E. Kempf 2001 all rights reserved.