mutex_concepts.qbk

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

[endsect]

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

[variablelist

[[Effects:] [Stores a reference to `m`. Invokes [timed_lock_shared_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_shared_ref__
returned `true`, then __owns_lock_shared_ref__ returns `true`, otherwise __owns_lock_shared_ref__
returns `false`.]]

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

]

[endsect]

[section:destructor `~shared_lock()`]

[variablelist

[[Effects:] [Invokes __mutex_func_ref__`->`[unlock_shared_ref_link `unlock_shared()`] if
__owns_lock_shared_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_shared_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_shared_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_shared_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_shared_ref__ returns `false`.]]

]

[endsect]

[endsect]

[section:upgrade_lock Class template `upgrade_lock`]

    #include <boost/thread/locks.hpp>

    template<typename Lockable>
    class upgrade_lock
    {
    public:
        explicit upgrade_lock(Lockable& m_);

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

        ~upgrade_lock();

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

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

        void swap(upgrade_lock& other);

        void lock();
        void unlock();

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

Like __unique_lock__, __upgrade_lock__ models the __lockable_concept__, but rather than acquiring unique ownership of the supplied
__lockable_concept_type__ object, locking an instance of __upgrade_lock__ acquires upgrade 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 __upgrade_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_upgrade_ref_link `mutex()->unlock_upgrade()`].

The member functions of __upgrade_lock__ are not thread-safe. In particular, __upgrade_lock__ is intended to model the upgrade
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.

[endsect]

[section:upgrade_to_unique_lock Class template `upgrade_to_unique_lock`]

    #include <boost/thread/locks.hpp>

    template <class Lockable>
    class upgrade_to_unique_lock
    {
    public:
        explicit upgrade_to_unique_lock(upgrade_lock<Lockable>& m_);

        ~upgrade_to_unique_lock();

        upgrade_to_unique_lock(detail::thread_move_t<upgrade_to_unique_lock<Lockable> > other);
        upgrade_to_unique_lock& operator=(detail::thread_move_t<upgrade_to_unique_lock<Lockable> > other);
        void swap(upgrade_to_unique_lock& other);

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

__upgrade_to_unique_lock__ allows for a temporary upgrade of an __upgrade_lock__ to exclusive ownership. When constructed with a
reference to an instance of __upgrade_lock__, if that instance has upgrade ownership on some __lockable_concept_type__ object, that
ownership is upgraded to exclusive ownership. When the __upgrade_to_unique_lock__ instance is destroyed, the ownership of the
__lockable_concept_type__ is downgraded back to ['upgrade ownership].

[endsect]

[section:scoped_try_lock Mutex-specific class `scoped_try_lock`]

    class MutexType::scoped_try_lock
    {
    private:
        MutexType::scoped_try_lock(MutexType::scoped_try_lock<MutexType>& other);
        MutexType::scoped_try_lock& operator=(MutexType::scoped_try_lock<MutexType>& other);
    public:
        MutexType::scoped_try_lock();
        explicit MutexType::scoped_try_lock(MutexType& m);
        MutexType::scoped_try_lock(MutexType& m_,adopt_lock_t);
        MutexType::scoped_try_lock(MutexType& m_,defer_lock_t);
        MutexType::scoped_try_lock(MutexType& m_,try_to_lock_t);

        MutexType::scoped_try_lock(MutexType::scoped_try_lock<MutexType>&& other);
        MutexType::scoped_try_lock& operator=(MutexType::scoped_try_lock<MutexType>&& other);

        void swap(MutexType::scoped_try_lock&& other);

        void lock();
        bool try_lock();
        void unlock();
        bool owns_lock() const;

        MutexType* mutex() const;
        MutexType* release();
        bool operator!() const;

        typedef ``['unspecified-bool-type]`` bool_type;
        operator bool_type() const;
    };

The member typedef `scoped_try_lock` is provided for each distinct
`MutexType` as a typedef to a class with the preceding definition. The
semantics of each constructor and member function are identical to
those of [unique_lock_link `boost::unique_lock<MutexType>`] for the same `MutexType`, except
that the constructor that takes a single reference to a mutex will
call [try_lock_ref_link `m.try_lock()`] rather than `m.lock()`.


[endsect]

[endsect]

[section:lock_functions Lock functions]

[section:lock_multiple Non-member function `lock(Lockable1,Lockable2,...)`]

    template<typename Lockable1,typename Lockable2>
    void lock(Lockable1& l1,Lockable2& l2);

    template<typename Lockable1,typename Lockable2,typename Lockable3>
    void lock(Lockable1& l1,Lockable2& l2,Lockable3& l3);

    template<typename Lockable1,typename Lockable2,typename Lockable3,typename Lockable4>
    void lock(Lockable1& l1,Lockable2& l2,Lockable3& l3,Lockable4& l4);

    template<typename Lockable1,typename Lockable2,typename Lockable3,typename Lockable4,typename Lockable5>
    void lock(Lockable1& l1,Lockable2& l2,Lockable3& l3,Lockable4& l4,Lockable5& l5);

[variablelist

[[Effects:] [Locks the __lockable_concept_type__ objects supplied as
arguments in an unspecified and indeterminate order in a way that
avoids deadlock. It is safe to call this function concurrently from
multiple threads with the same mutexes (or other lockable objects) in
different orders without risk of deadlock. If any of the __lock_ref__
or __try_lock_ref__ operations on the supplied
__lockable_concept_type__ objects throws an exception any locks
acquired by the function will be released before the function exits.]]

[[Throws:] [Any exceptions thrown by calling __lock_ref__ or
__try_lock_ref__ on the supplied __lockable_concept_type__ objects.]]

[[Postcondition:] [All the supplied __lockable_concept_type__ objects
are locked by the calling thread.]]

]

[endsect]

[section:lock_range Non-member function `lock(begin,end)`]

    template<typename ForwardIterator>
    void lock(ForwardIterator begin,ForwardIterator end);

[variablelist

[[Preconditions:] [The `value_type` of `ForwardIterator` must implement the __lockable_concept__]]

[[Effects:] [Locks all the __lockable_concept_type__ objects in the
supplied range in an unspecified and indeterminate order in a way that
avoids deadlock. It is safe to call this function concurrently from
multiple threads with the same mutexes (or other lockable objects) in
different orders without risk of deadlock. If any of the __lock_ref__
or __try_lock_ref__ operations on the __lockable_concept_type__
objects in the supplied range throws an exception any locks acquired
by the function will be released before the function exits.]]

[[Throws:] [Any exceptions thrown by calling __lock_ref__ or
__try_lock_ref__ on the supplied __lockable_concept_type__ objects.]]

[[Postcondition:] [All the __lockable_concept_type__ objects in the
supplied range are locked by the calling thread.]]

]

[endsect]

[section:try_lock_multiple Non-member function `try_lock(Lockable1,Lockable2,...)`]

    template<typename Lockable1,typename Lockable2>
    int try_lock(Lockable1& l1,Lockable2& l2);

    template<typename Lockable1,typename Lockable2,typename Lockable3>
    int try_lock(Lockable1& l1,Lockable2& l2,Lockable3& l3);

    template<typename Lockable1,typename Lockable2,typename Lockable3,typename Lockable4>
    int try_lock(Lockable1& l1,Lockable2& l2,Lockable3& l3,Lockable4& l4);

    template<typename Lockable1,typename Lockable2,typename Lockable3,typename Lockable4,typename Lockable5>
    int try_lock(Lockable1& l1,Lockable2& l2,Lockable3& l3,Lockable4& l4,Lockable5& l5);

[variablelist

[[Effects:] [Calls __try_lock_ref__ on each of the
__lockable_concept_type__ objects supplied as arguments. If any of the
calls to __try_lock_ref__ returns `false` then all locks acquired are
released and the zero-based index of the failed lock is returned.

If any of the __try_lock_ref__ operations on the supplied
__lockable_concept_type__ objects throws an exception any locks
acquired by the function will be released before the function exits.]]

[[Returns:] [`-1` if all the supplied __lockable_concept_type__ objects
are now locked by the calling thread, the zero-based index of the
object which could not be locked otherwise.]]

[[Throws:] [Any exceptions thrown by calling __try_lock_ref__ on the
supplied __lockable_concept_type__ objects.]]

[[Postcondition:] [If the function returns `-1`, all the supplied
__lockable_concept_type__ objects are locked by the calling
thread. Otherwise any locks acquired by this function will have been
released.]]

]

[endsect]

[section:try_lock_range Non-member function `try_lock(begin,end)`]

    template<typename ForwardIterator>
    ForwardIterator try_lock(ForwardIterator begin,ForwardIterator end);

[variablelist

[[Preconditions:] [The `value_type` of `ForwardIterator` must implement the __lockable_concept__]]

[[Effects:] [Calls __try_lock_ref__ on each of the
__lockable_concept_type__ objects in the supplied range. If any of the
calls to __try_lock_ref__ returns `false` then all locks acquired are
released and an iterator referencing the failed lock is returned.

If any of the __try_lock_ref__ operations on the supplied
__lockable_concept_type__ objects throws an exception any locks
acquired by the function will be released before the function exits.]]

[[Returns:] [`end` if all the supplied __lockable_concept_type__
objects are now locked by the calling thread, an iterator referencing
the object which could not be locked otherwise.]]

[[Throws:] [Any exceptions thrown by calling __try_lock_ref__ on the
supplied __lockable_concept_type__ objects.]]

[[Postcondition:] [If the function returns `end` then all the
__lockable_concept_type__ objects in the supplied range are locked by
the calling thread, otherwise all locks acquired by the function have
been released.]]

]

[endsect]


[endsect]