Boost.Threads

basic_timedlock

This template class defines a lock type that allows a program to attempt to lock the associated mutex model blocking only for a specified amount of time. The timed_mutex and recursive_timed_mutex use this template to define their timed_lock types.

Like all the Boost.Threads lock models, the basic_timedlock is meant to be short lived and is not thread safe, so should not be shared between threads.

Header

#include <boost/thread/xlock.hpp>
   This header is usually not included directly by programmers.  Instead it's
   included by the mutex model that exposes it.

Public Interface

    template <typename M>
    class basic_timedlock : private boost::noncopyable
    {
    public:
        typedef M mutex_type;

        basic_timedlock(M& mx, const boost::xtime& xt);
        basic_timedlock(M& mx, bool lock_it);
        ~basic_timedlock();
        
        void lock();
        bool timed_lock(const xtime& xt);
        void unlock();
        
        operator const void*() const;
    };

Constructors

    basic_timedlock(M& mx, const xtime& xt);

Constructs a basic_timedlock and calls timed_lock with xt.

    basic_timedlock(M& mx, bool lock_it);

Constructs a basic_timedlock and if lock_it is true then calls lock.

Destructor

    ~basic_timedlock();

Destructs the basic_timedlock and if locked calls unlock.

lock

    void lock();

Locks the associated mutex model. If the basic_timedlock is already locked then a lock_error is thrown. Depending on the locking strategy of the mutex model if the calling thread already owns a lock through another lock model this may cause a deadlock or for a lock_error to be thrown.

timed_lock

    bool timed_lock(const xtime& xt);

Attempts to lock the associated mutex model. If the basic_timedlock is already locked then a lock_error is thrown. If the mutex model is already locked by another thread this operation will wait until xt before returning false.

unlock

    void unlock();

Unlocks the associated mutex model. If the basic_timedlock is not already locked then a lock_error is thrown.

const void* Conversion

    operator const void*() const;

Implicitly converts the lock to a value that can be used in boolean expressions to test if the lock is currently locked or not.

Example Usage

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

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

The output is:

locked