mutex_concepts.qbk

来自「Boost provides free peer-reviewed portab」· QBK 代码 · 共 1,120 行 · 第 1/3 页

[/
  (C) Copyright 2007-8 Anthony Williams.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[section:mutex_concepts Mutex Concepts]

A mutex object facilitates protection against data races and allows thread-safe synchronization of data between threads. A thread
obtains ownership of a mutex object by calling one of the lock functions and relinquishes ownership by calling the corresponding
unlock function. Mutexes may be either recursive or non-recursive, and may grant simultaneous ownership to one or many
threads. __boost_thread__ supplies recursive and non-recursive mutexes with exclusive ownership semantics, along with a shared
ownership (multiple-reader / single-writer) mutex.

__boost_thread__ supports four basic concepts for lockable objects: __lockable_concept_type__, __timed_lockable_concept_type__,
__shared_lockable_concept_type__ and __upgrade_lockable_concept_type__. Each mutex type implements one or more of these concepts, as
do the various lock types.

[section:lockable `Lockable` Concept]

The __lockable_concept__ models exclusive ownership. A type that implements the __lockable_concept__ shall provide the following
member functions:

* [lock_ref_link `void lock();`]
* [try_lock_ref_link `bool try_lock();`]
* [unlock_ref_link `void unlock();`]

Lock ownership acquired through a call to __lock_ref__ or __try_lock_ref__ must be released through a call to __unlock_ref__.

[section:lock `void lock()`]

[variablelist

[[Effects:] [The current thread blocks until ownership can be obtained for the current thread.]]

[[Postcondition:] [The current thread owns `*this`.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]
[endsect]

[section:try_lock `bool try_lock()`]

[variablelist

[[Effects:] [Attempt to obtain ownership for the current thread without blocking.]]

[[Returns:] [`true` if ownership was obtained for the current thread, `false` otherwise.]]

[[Postcondition:] [If the call returns `true`, the current thread owns the `*this`.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]
[endsect]

[section:unlock `void unlock()`]

[variablelist

[[Precondition:] [The current thread owns `*this`.]]

[[Effects:] [Releases ownership by the current thread.]]

[[Postcondition:] [The current thread no longer owns `*this`.]]

[[Throws:] [Nothing]]
]
[endsect]
[endsect]

[section:timed_lockable `TimedLockable` Concept]

The __timed_lockable_concept__ refines the __lockable_concept__ to add support for
timeouts when trying to acquire the lock.

A type that implements the __timed_lockable_concept__ shall meet the requirements
of the __lockable_concept__. In addition, the following member functions must be
provided:

* [timed_lock_ref_link `bool timed_lock(boost::system_time const& abs_time);`]
* [timed_lock_duration_ref_link `template<typename DurationType> bool timed_lock(DurationType const& rel_time);`]

Lock ownership acquired through a call to __timed_lock_ref__ must be released through a call to __unlock_ref__.

[section:timed_lock `bool timed_lock(boost::system_time const& abs_time)`]

[variablelist

[[Effects:] [Attempt to obtain ownership for the current thread. Blocks until ownership can be obtained, or the specified time is
reached. If the specified time has already passed, behaves as __try_lock_ref__.]]

[[Returns:] [`true` if ownership was obtained for the current thread, `false` otherwise.]]

[[Postcondition:] [If the call returns `true`, the current thread owns `*this`.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]
]
[endsect]

[section:timed_lock_duration `template<typename DurationType> bool
timed_lock(DurationType const& rel_time)`]

[variablelist

[[Effects:] [As-if [timed_lock_ref_link
`timed_lock(boost::get_system_time()+rel_time)`].]]

]
[endsect]

[endsect]

[section:shared_lockable `SharedLockable` Concept]

The __shared_lockable_concept__ is a refinement of the __timed_lockable_concept__ that
allows for ['shared ownership] as well as ['exclusive ownership]. This is the
standard multiple-reader / single-write model: at most one thread can have
exclusive ownership, and if any thread does have exclusive ownership, no other threads
can have shared or exclusive ownership. Alternatively, many threads may have
shared ownership.

For a type to implement the __shared_lockable_concept__, as well as meeting the
requirements of the __timed_lockable_concept__, it must also provide the following
member functions:

* [lock_shared_ref_link `void lock_shared();`]
* [try_lock_shared_ref_link `bool try_lock_shared();`]
* [unlock_shared_ref_link `bool unlock_shared();`]
* [timed_lock_shared_ref_link `bool timed_lock_shared(boost::system_time const& abs_time);`]

Lock ownership acquired through a call to __lock_shared_ref__, __try_lock_shared_ref__ or __timed_lock_shared_ref__ must be released
through a call to __unlock_shared_ref__.

[section:lock_shared `void lock_shared()`]

[variablelist

[[Effects:] [The current thread blocks until shared ownership can be obtained for the current thread.]]

[[Postcondition:] [The current thread has shared ownership of `*this`.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]
[endsect]

[section:try_lock_shared `bool try_lock_shared()`]

[variablelist

[[Effects:] [Attempt to obtain shared ownership for the current thread without blocking.]]

[[Returns:] [`true` if shared ownership was obtained for the current thread, `false` otherwise.]]

[[Postcondition:] [If the call returns `true`, the current thread has shared ownership of `*this`.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]
[endsect]

[section:timed_lock_shared `bool timed_lock_shared(boost::system_time const& abs_time)`]

[variablelist

[[Effects:] [Attempt to obtain shared ownership for the current thread. Blocks until shared ownership can be obtained, or the
specified time is reached. If the specified time has already passed, behaves as __try_lock_shared_ref__.]]

[[Returns:] [`true` if shared ownership was acquired for the current thread, `false` otherwise.]]

[[Postcondition:] [If the call returns `true`, the current thread has shared
ownership of `*this`.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]
[endsect]

[section:unlock_shared `void unlock_shared()`]

[variablelist

[[Precondition:] [The current thread has shared ownership of `*this`.]]

[[Effects:] [Releases shared ownership of `*this` by the current thread.]]

[[Postcondition:] [The current thread no longer has shared ownership of `*this`.]]

[[Throws:] [Nothing]]

]
[endsect]


[endsect]

[section:upgrade_lockable `UpgradeLockable` Concept]

The __upgrade_lockable_concept__ is a refinement of the __shared_lockable_concept__ that allows for ['upgradable ownership] as well
as ['shared ownership] and ['exclusive ownership]. This is an extension to the multiple-reader / single-write model provided by the
__shared_lockable_concept__: a single thread may have ['upgradable ownership] at the same time as others have ['shared
ownership]. The thread with ['upgradable ownership] may at any time attempt to upgrade that ownership to ['exclusive ownership]. If
no other threads have shared ownership, the upgrade is completed immediately, and the thread now has ['exclusive ownership], which
must be relinquished by a call to __unlock_ref__, just as if it had been acquired by a call to __lock_ref__.

If a thread with ['upgradable ownership] tries to upgrade whilst other threads have ['shared ownership], the attempt will fail and
the thread will block until ['exclusive ownership] can be acquired.

Ownership can also be ['downgraded] as well as ['upgraded]: exclusive ownership of an implementation of the
__upgrade_lockable_concept__ can be downgraded to upgradable ownership or shared ownership, and upgradable ownership can be
downgraded to plain shared ownership.

For a type to implement the __upgrade_lockable_concept__, as well as meeting the
requirements of the __shared_lockable_concept__, it must also provide the following
member functions:

* [lock_upgrade_ref_link `void lock_upgrade();`]
* [unlock_upgrade_ref_link `bool unlock_upgrade();`]
* [unlock_upgrade_and_lock_ref_link `void unlock_upgrade_and_lock();`]
* [unlock_and_lock_upgrade_ref_link `void unlock_and_lock_upgrade();`]
* [unlock_upgrade_and_lock_shared_ref_link `void unlock_upgrade_and_lock_shared();`]

Lock ownership acquired through a call to __lock_upgrade_ref__ must be released through a call to __unlock_upgrade_ref__. If the
ownership type is changed through a call to one of the `unlock_xxx_and_lock_yyy()` functions, ownership must be released through a
call to the unlock function corresponding to the new level of ownership.


[section:lock_upgrade `void lock_upgrade()`]

[variablelist

[[Effects:] [The current thread blocks until upgrade ownership can be obtained for the current thread.]]

[[Postcondition:] [The current thread has upgrade ownership of `*this`.]]

[[Throws:] [__thread_resource_error__ if an error occurs.]]

]
[endsect]

[section:unlock_upgrade `void unlock_upgrade()`]

[variablelist

[[Precondition:] [The current thread has upgrade ownership of `*this`.]]

[[Effects:] [Releases upgrade ownership of `*this` by the current thread.]]

[[Postcondition:] [The current thread no longer has upgrade ownership of `*this`.]]

[[Throws:] [Nothing]]

]
[endsect]

[section:unlock_upgrade_and_lock `void unlock_upgrade_and_lock()`]

[variablelist

[[Precondition:] [The current thread has upgrade ownership of `*this`.]]

[[Effects:] [Atomically releases upgrade ownership of `*this` by the current thread and acquires exclusive ownership of `*this`. If
any other threads have shared ownership, blocks until exclusive ownership can be acquired.]]

[[Postcondition:] [The current thread has exclusive ownership of `*this`.]]

[[Throws:] [Nothing]]

]
[endsect]

[section:unlock_upgrade_and_lock_shared `void unlock_upgrade_and_lock_shared()`]

[variablelist

[[Precondition:] [The current thread has upgrade ownership of `*this`.]]

[[Effects:] [Atomically releases upgrade ownership of `*this` by the current thread and acquires shared ownership of `*this` without
blocking.]]

[[Postcondition:] [The current thread has shared ownership of `*this`.]]

[[Throws:] [Nothing]]

]
[endsect]

[section:unlock_and_lock_upgrade `void unlock_and_lock_upgrade()`]

[variablelist

[[Precondition:] [The current thread has exclusive ownership of `*this`.]]

[[Effects:] [Atomically releases exclusive ownership of `*this` by the current thread and acquires upgrade ownership of `*this`
without blocking.]]

[[Postcondition:] [The current thread has upgrade ownership of `*this`.]]

[[Throws:] [Nothing]]

]
[endsect]

[endsect]

[endsect]

[section:locks Lock Types]

[section:lock_guard Class template `lock_guard`]

    #include <boost/thread/locks.hpp>

    template<typename Lockable>
    class lock_guard
    {
    public:
        explicit lock_guard(Lockable& m_);
        lock_guard(Lockable& m_,boost::adopt_lock_t);

        ~lock_guard();
    };

__lock_guard__ is very simple: on construction it
acquires ownership of the implementation of the __lockable_concept__ supplied as
the constructor parameter. On destruction, the ownership is released. This
provides simple RAII-style locking of a __lockable_concept_type__ object, to facilitate exception-safe
locking and unlocking. In addition, the [link
thread.synchronization.locks.lock_guard.constructor_adopt `lock_guard(Lockable &
m,boost::adopt_lock_t)` constructor] allows the __lock_guard__ object to
take ownership of a lock already held by the current thread.

[section:constructor `lock_guard(Lockable & m)`]

[variablelist

[[Effects:] [Stores a reference to `m`. Invokes [lock_ref_link `m.lock()`].]]

[[Throws:] [Any exception thrown by the call to [lock_ref_link `m.lock()`].]]

]

[endsect]

[section:constructor_adopt `lock_guard(Lockable & m,boost::adopt_lock_t)`]

[variablelist

[[Precondition:] [The current thread owns a lock on `m` equivalent to one
obtained by a call to [lock_ref_link `m.lock()`].]]

[[Effects:] [Stores a reference to `m`. Takes ownership of the lock state of
`m`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:destructor `~lock_guard()`]

[variablelist

[[Effects:] [Invokes [unlock_ref_link `m.unlock()`] on the __lockable_concept_type__
object passed to the constructor.]]

[[Throws:] [Nothing.]]

]