mutex_concepts.qbk

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

[endsect]

[endsect]

[section:unique_lock Class template `unique_lock`]

    #include <boost/thread/locks.hpp>

    template<typename Lockable>
    class unique_lock
    {
    public:
        unique_lock();
        explicit unique_lock(Lockable& m_);
        unique_lock(Lockable& m_,adopt_lock_t);
        unique_lock(Lockable& m_,defer_lock_t);
        unique_lock(Lockable& m_,try_to_lock_t);
        unique_lock(Lockable& m_,system_time const& target_time);

        ~unique_lock();

        unique_lock(detail::thread_move_t<unique_lock<Lockable> > other);
        unique_lock(detail::thread_move_t<upgrade_lock<Lockable> > other);

        operator detail::thread_move_t<unique_lock<Lockable> >();
        detail::thread_move_t<unique_lock<Lockable> > move();
        unique_lock& operator=(detail::thread_move_t<unique_lock<Lockable> > other);
        unique_lock& operator=(detail::thread_move_t<upgrade_lock<Lockable> > other);

        void swap(unique_lock& other);
        void swap(detail::thread_move_t<unique_lock<Lockable> > other);

        void lock();
        bool try_lock();

        template<typename TimeDuration>
        bool timed_lock(TimeDuration const& relative_time);
        bool timed_lock(::boost::system_time const& absolute_time);

        void unlock();

        bool owns_lock() const;
        operator ``['unspecified-bool-type]``() const;
        bool operator!() const;

        Lockable* mutex() const;
        Lockable* release();
    };

__unique_lock__ is more complex than __lock_guard__: not only does it provide for RAII-style locking, it also allows for deferring
acquiring the lock until the __lock_ref__ member function is called explicitly, or trying to acquire the lock in a non-blocking
fashion, or with a timeout. Consequently, __unlock_ref__ is only called in the destructor if the lock object has locked the
__lockable_concept_type__ object, or otherwise adopted a lock on the __lockable_concept_type__ object.

Specializations of __unique_lock__ model the __timed_lockable_concept__ if the supplied __lockable_concept_type__ type itself models
__timed_lockable_concept__ (e.g. `boost::unique_lock<boost::timed_mutex>`), or the __lockable_concept__ otherwise
(e.g. `boost::unique_lock<boost::mutex>`). 

An instance of __unique_lock__ is said to ['own] the lock state of a __lockable_concept_type__ `m` if __mutex_func_ref__ returns a
pointer to `m` and __owns_lock_ref__ returns `true`. If an object that ['owns] the lock state of a __lockable_concept_type__ object
is destroyed, then the destructor will invoke [unlock_ref_link `mutex()->unlock()`].

The member functions of __unique_lock__ are not thread-safe. In particular, __unique_lock__ is intended to model the ownership of a
__lockable_concept_type__ object by a particular thread, and the member functions that release ownership of the lock state
(including the destructor) must be called by the same thread that acquired ownership of the lock state.

[section:defaultconstructor `unique_lock()`]

[variablelist

[[Effects:] [Creates a lock object with no associated mutex.]]

[[Postcondition:] [__owns_lock_ref__ returns `false`. __mutex_func_ref__ returns `NULL`.]]

[[Throws:] [Nothing.]]

]

[endsect]

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

[variablelist

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

[[Postcondition:] [__owns_lock_ref__ returns `true`. __mutex_func_ref__ returns `&m`.]]

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

]

[endsect]

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

[variablelist

[[Precondition:] [The current thread owns an exclusive lock on `m`.]]

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

[[Postcondition:] [__owns_lock_ref__ returns `true`. __mutex_func_ref__ returns `&m`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:constructor_defer `unique_lock(Lockable & m,boost::defer_lock_t)`]

[variablelist

[[Effects:] [Stores a reference to `m`.]]

[[Postcondition:] [__owns_lock_ref__ returns `false`. __mutex_func_ref__ returns `&m`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:constructor_try `unique_lock(Lockable & m,boost::try_to_lock_t)`]

[variablelist

[[Effects:] [Stores a reference to `m`. Invokes [try_lock_ref_link
`m.try_lock()`], and takes ownership of the lock state if the call returns
`true`.]]

[[Postcondition:] [__mutex_func_ref__ returns `&m`. If the call to __try_lock_ref__
returned `true`, then __owns_lock_ref__ returns `true`, otherwise __owns_lock_ref__
returns `false`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:constructor_abs_time `unique_lock(Lockable & m,boost::system_time const& abs_time)`]

[variablelist

[[Effects:] [Stores a reference to `m`. Invokes [timed_lock_ref_link
`m.timed_lock(abs_time)`], and takes ownership of the lock state if the call
returns `true`.]]

[[Postcondition:] [__mutex_func_ref__ returns `&m`. If the call to __timed_lock_ref__
returned `true`, then __owns_lock_ref__ returns `true`, otherwise __owns_lock_ref__
returns `false`.]]

[[Throws:] [Any exceptions thrown by the call to [timed_lock_ref_link `m.timed_lock(abs_time)`].]]

]

[endsect]

[section:destructor `~unique_lock()`]

[variablelist

[[Effects:] [Invokes __mutex_func_ref__`->`[unlock_ref_link `unlock()`] if
__owns_lock_ref__ returns `true`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:owns_lock `bool owns_lock() const`]

[variablelist

[[Returns:] [`true` if the `*this` owns the lock on the __lockable_concept_type__
object associated with `*this`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:mutex `Lockable* mutex() const`]

[variablelist

[[Returns:] [A pointer to the __lockable_concept_type__ object associated with
`*this`, or `NULL` if there is no such object.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:bool_conversion `operator unspecified-bool-type() const`]

[variablelist

[[Returns:] [If __owns_lock_ref__ would return `true`, a value that evaluates to
`true` in boolean contexts, otherwise a value that evaluates to `false` in
boolean contexts.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:operator_not `bool operator!() const`]

[variablelist

[[Returns:] [`!` __owns_lock_ref__.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:release `Lockable* release()`]

[variablelist

[[Effects:] [The association between `*this` and the __lockable_concept_type__ object is removed, without affecting the lock state
of the __lockable_concept_type__ object. If __owns_lock_ref__ would have returned `true`, it is the responsibility of the calling
code to ensure that the __lockable_concept_type__ is correctly unlocked.]]

[[Returns:] [A pointer to the __lockable_concept_type__ object associated with `*this` at the point of the call, or `NULL` if there
is no such object.]]

[[Throws:] [Nothing.]]

[[Postcondition:] [`*this` is no longer associated with any __lockable_concept_type__ object. __mutex_func_ref__ returns `NULL` and
__owns_lock_ref__ returns `false`.]]

]

[endsect]

[endsect]

[section:shared_lock Class template `shared_lock`]

    #include <boost/thread/locks.hpp>

    template<typename Lockable>
    class shared_lock
    {
    public:
        shared_lock();
        explicit shared_lock(Lockable& m_);
        shared_lock(Lockable& m_,adopt_lock_t);
        shared_lock(Lockable& m_,defer_lock_t);
        shared_lock(Lockable& m_,try_to_lock_t);
        shared_lock(Lockable& m_,system_time const& target_time);
        shared_lock(detail::thread_move_t<shared_lock<Lockable> > other);
        shared_lock(detail::thread_move_t<unique_lock<Lockable> > other);
        shared_lock(detail::thread_move_t<upgrade_lock<Lockable> > other);

        ~shared_lock();

        operator detail::thread_move_t<shared_lock<Lockable> >();
        detail::thread_move_t<shared_lock<Lockable> > move();

        shared_lock& operator=(detail::thread_move_t<shared_lock<Lockable> > other);
        shared_lock& operator=(detail::thread_move_t<unique_lock<Lockable> > other);
        shared_lock& operator=(detail::thread_move_t<upgrade_lock<Lockable> > other);
        void swap(shared_lock& other);

        void lock();
        bool try_lock();
        bool timed_lock(boost::system_time const& target_time);
        void unlock();

        operator ``['unspecified-bool-type]``() const;
        bool operator!() const;
        bool owns_lock() const;
    };

Like __unique_lock__, __shared_lock__ models the __lockable_concept__, but rather than acquiring unique ownership of the supplied
__lockable_concept_type__ object, locking an instance of __shared_lock__ acquires shared ownership.

Like __unique_lock__, not only does it provide for RAII-style locking, it also allows for deferring acquiring the lock until the
__lock_ref__ member function is called explicitly, or trying to acquire the lock in a non-blocking fashion, or with a
timeout. Consequently, __unlock_ref__ is only called in the destructor if the lock object has locked the __lockable_concept_type__
object, or otherwise adopted a lock on the __lockable_concept_type__ object.

An instance of __shared_lock__ is said to ['own] the lock state of a __lockable_concept_type__ `m` if __mutex_func_ref__ returns a
pointer to `m` and __owns_lock_ref__ returns `true`. If an object that ['owns] the lock state of a __lockable_concept_type__ object
is destroyed, then the destructor will invoke [unlock_shared_ref_link `mutex()->unlock_shared()`].

The member functions of __shared_lock__ are not thread-safe. In particular, __shared_lock__ is intended to model the shared
ownership of a __lockable_concept_type__ object by a particular thread, and the member functions that release ownership of the lock
state (including the destructor) must be called by the same thread that acquired ownership of the lock state.

[section:defaultconstructor `shared_lock()`]

[variablelist

[[Effects:] [Creates a lock object with no associated mutex.]]

[[Postcondition:] [__owns_lock_ref__ returns `false`. __mutex_func_ref__ returns `NULL`.]]

[[Throws:] [Nothing.]]

]

[endsect]

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

[variablelist

[[Effects:] [Stores a reference to `m`. Invokes [lock_shared_ref_link `m.lock_shared()`].]]

[[Postcondition:] [__owns_lock_shared_ref__ returns `true`. __mutex_func_ref__ returns `&m`.]]

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

]

[endsect]

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

[variablelist

[[Precondition:] [The current thread owns an exclusive lock on `m`.]]

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

[[Postcondition:] [__owns_lock_shared_ref__ returns `true`. __mutex_func_ref__ returns `&m`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:constructor_defer `shared_lock(Lockable & m,boost::defer_lock_t)`]

[variablelist

[[Effects:] [Stores a reference to `m`.]]

[[Postcondition:] [__owns_lock_shared_ref__ returns `false`. __mutex_func_ref__ returns `&m`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:constructor_try `shared_lock(Lockable & m,boost::try_to_lock_t)`]

[variablelist

[[Effects:] [Stores a reference to `m`. Invokes [try_lock_shared_ref_link
`m.try_lock_shared()`], and takes ownership of the lock state if the call returns
`true`.]]

[[Postcondition:] [__mutex_func_ref__ returns `&m`. If the call to __try_lock_shared_ref__
returned `true`, then __owns_lock_shared_ref__ returns `true`, otherwise __owns_lock_shared_ref__
returns `false`.]]

[[Throws:] [Nothing.]]

]