###  | # Boost.Threads ## scoped_timed_lock

Introduction
Header
Synopsis
Members
Example

## Introduction

This class template defines a generic lock type which meets the ScopedTimedLock requirements. The timed_mutex and recursive_timed_mutex classes use this template to define their `scoped_timed_lock` types.

Like all the Boost.Threads lock models, `scoped_timed_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_timed_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.

The type used to instantiate the class must meet the TimedMutex requirements.

Although this class is an implementation detail, it is publicly documented here because of its importance.

## Header

    #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>

## Synopsis

    namespace boost { namespace detail { namespace thread {
        template <typename TimedMutex>
        class scoped_timed_lock : private boost::noncopyable // Exposition only.
            // Class scoped_timed_lock meets the NonCopyable requirement.
        {
        public:
            typedef TimedMutex mutex_type;

            scoped_timed_lock(TimedMutex& mx, const boost::xtime& xt);
            scoped_timed_lock(TimedMutex& mx, bool initially_locked);
            ~scoped_timed_lock();

            void lock();
            bool timed_lock(const xtime& xt);
            void unlock();

            operator const void*() const;
        };
    } // namespace thread
    } // namesapce detail
    } // namespace boost

## Members

### Constructor

        scoped_timed_lock(TimedMutex& mx, const xtime& xt);

Effects: Associates mutex `mx` with `*this`. Calls `timed_lock`( `xt`)

        scoped_timed_lock(TimedMutex& mx, bool initially_locked);

Effects: Associates mutex `mx` with `*this`. If `initially_locked` is `true`, calls `lock()`.

### Destructor

        ~scoped_timed_lock();

Effects: If `locked()`, calls `unlock()`. Destroys `*this`.

### lock

        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.

### timed_lock

        bool timed_lock(const xtime& xt);

Effects: Same as `lock()`, except that if xt is reached, places the current thread in the Ready state without further ado.

Returns: `locked()`.

Throws: lock_error if `locked()` or as indicated in Effects.

### unlock

        void unlock();

Effects: Unlocks the associated mutex.

Throws: lock_error if `!locked()`.

### const void* Conversion

        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`.

### locked

        bool locked() const;

Returns: `this->operator const void*() != 0`.

## Example Usage

    #include <boost/thread/mutex.hpp>
    #include <iostream>

    int main(int, char*[])
    {
       boost::timed_mutex mutex;
       boost::xtime xt;
       boost::get_xtime(&xt, boost::TIME_UTC);
       xt.sec += 1;
       boost::mutex::scoped_timed_lock scope_timed_lock(mutex, xt);
       if (scope_timed_lock.locked())
          std::cout << "locked" << std::endl;
       else
          std::cout << "unlocked" << std::endl;
       return 0;
    }

The output is:

    locked

Revised November 05, 2001

© Copyright William E. Kempf 2001 all rights reserved.