Chris@16: //////////////////////////////////////////////////////////////////////////////
Chris@16: //
Chris@16: // (C) Copyright Ion Gaztanaga 2005-2012. Distributed under the Boost
Chris@16: // Software License, Version 1.0. (See accompanying file
Chris@16: // LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
Chris@16: //
Chris@16: // See http://www.boost.org/libs/interprocess for documentation.
Chris@16: //
Chris@16: //////////////////////////////////////////////////////////////////////////////
Chris@16: //
Chris@16: // This interface is inspired by Howard Hinnant's lock proposal.
Chris@16: // http://home.twcny.rr.com/hinnant/cpp_extensions/threads_move.html
Chris@16: //
Chris@16: //////////////////////////////////////////////////////////////////////////////
Chris@16: 
Chris@16: #ifndef BOOST_INTERPROCESS_SCOPED_LOCK_HPP
Chris@16: #define BOOST_INTERPROCESS_SCOPED_LOCK_HPP
Chris@16: 
Chris@101: #ifndef BOOST_CONFIG_HPP
Chris@101: #  include <boost/config.hpp>
Chris@101: #endif
Chris@101: #
Chris@101: #if defined(BOOST_HAS_PRAGMA_ONCE)
Chris@16: #  pragma once
Chris@16: #endif
Chris@16: 
Chris@16: #include <boost/interprocess/detail/config_begin.hpp>
Chris@16: #include <boost/interprocess/detail/workaround.hpp>
Chris@16: #include <boost/interprocess/interprocess_fwd.hpp>
Chris@16: #include <boost/interprocess/sync/lock_options.hpp>
Chris@16: #include <boost/interprocess/exceptions.hpp>
Chris@16: #include <boost/interprocess/detail/mpl.hpp>
Chris@16: #include <boost/interprocess/detail/type_traits.hpp>
Chris@101: #include <boost/move/utility_core.hpp>
Chris@16: #include <boost/interprocess/detail/posix_time_types_wrk.hpp>
Chris@101: #include <boost/interprocess/detail/simple_swap.hpp>
Chris@16: 
Chris@16: //!\file
Chris@16: //!Describes the scoped_lock class.
Chris@16: 
Chris@16: namespace boost {
Chris@16: namespace interprocess {
Chris@16: 
Chris@16: 
Chris@16: //!scoped_lock is meant to carry out the tasks for locking, unlocking, try-locking
Chris@16: //!and timed-locking (recursive or not) for the Mutex. The Mutex need not supply all
Chris@16: //!of this functionality. If the client of scoped_lock<Mutex> does not use
Chris@16: //!functionality which the Mutex does not supply, no harm is done. Mutex ownership
Chris@16: //!transfer is supported through the syntax of move semantics. Ownership transfer
Chris@16: //!is allowed both by construction and assignment. The scoped_lock does not support
Chris@16: //!copy semantics. A compile time error results if copy construction or copy
Chris@16: //!assignment is attempted. Mutex ownership can also be moved from an
Chris@16: //!upgradable_lock and sharable_lock via constructor. In this role, scoped_lock
Chris@16: //!shares the same functionality as a write_lock.
Chris@16: template <class Mutex>
Chris@16: class scoped_lock
Chris@16: {
Chris@101:    #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
Chris@16:    private:
Chris@16:    typedef scoped_lock<Mutex> this_type;
Chris@16:    BOOST_MOVABLE_BUT_NOT_COPYABLE(scoped_lock)
Chris@16:    typedef bool this_type::*unspecified_bool_type;
Chris@101:    #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
Chris@16:    public:
Chris@16: 
Chris@16:    typedef Mutex mutex_type;
Chris@16: 
Chris@16:    //!Effects: Default constructs a scoped_lock.
Chris@16:    //!Postconditions: owns() == false and mutex() == 0.
Chris@16:    scoped_lock()
Chris@16:       : mp_mutex(0), m_locked(false)
Chris@16:    {}
Chris@16: 
Chris@16:    //!Effects: m.lock().
Chris@16:    //!Postconditions: owns() == true and mutex() == &m.
Chris@16:    //!Notes: The constructor will take ownership of the mutex. If another thread
Chris@16:    //!   already owns the mutex, this thread will block until the mutex is released.
Chris@16:    //!   Whether or not this constructor handles recursive locking depends upon the mutex.
Chris@16:    explicit scoped_lock(mutex_type& m)
Chris@16:       : mp_mutex(&m), m_locked(false)
Chris@16:    {  mp_mutex->lock();   m_locked = true;  }
Chris@16: 
Chris@16:    //!Postconditions: owns() == false, and mutex() == &m.
Chris@16:    //!Notes: The constructor will not take ownership of the mutex. There is no effect
Chris@16:    //!   required on the referenced mutex.
Chris@16:    scoped_lock(mutex_type& m, defer_lock_type)
Chris@16:       : mp_mutex(&m), m_locked(false)
Chris@16:    {}
Chris@16: 
Chris@16:    //!Postconditions: owns() == true, and mutex() == &m.
Chris@16:    //!Notes: The constructor will suppose that the mutex is already locked. There
Chris@16:    //!   is no effect required on the referenced mutex.
Chris@16:    scoped_lock(mutex_type& m, accept_ownership_type)
Chris@16:       : mp_mutex(&m), m_locked(true)
Chris@16:    {}
Chris@16: 
Chris@16:    //!Effects: m.try_lock().
Chris@16:    //!Postconditions: mutex() == &m. owns() == the return value of the
Chris@16:    //!   m.try_lock() executed within the constructor.
Chris@16:    //!Notes: The constructor will take ownership of the mutex if it can do
Chris@16:    //!   so without waiting. Whether or not this constructor handles recursive
Chris@16:    //!   locking depends upon the mutex. If the mutex_type does not support try_lock,
Chris@16:    //!   this constructor will fail at compile time if instantiated, but otherwise
Chris@16:    //!   have no effect.
Chris@16:    scoped_lock(mutex_type& m, try_to_lock_type)
Chris@16:       : mp_mutex(&m), m_locked(mp_mutex->try_lock())
Chris@16:    {}
Chris@16: 
Chris@16:    //!Effects: m.timed_lock(abs_time).
Chris@16:    //!Postconditions: mutex() == &m. owns() == the return value of the
Chris@16:    //!   m.timed_lock(abs_time) executed within the constructor.
Chris@16:    //!Notes: The constructor will take ownership of the mutex if it can do
Chris@16:    //!   it until abs_time is reached. Whether or not this constructor
Chris@16:    //!   handles recursive locking depends upon the mutex. If the mutex_type
Chris@16:    //!   does not support try_lock, this constructor will fail at compile
Chris@16:    //!   time if instantiated, but otherwise have no effect.
Chris@16:    scoped_lock(mutex_type& m, const boost::posix_time::ptime& abs_time)
Chris@16:       : mp_mutex(&m), m_locked(mp_mutex->timed_lock(abs_time))
Chris@16:    {}
Chris@16: 
Chris@16:    //!Postconditions: mutex() == the value scop.mutex() had before the
Chris@16:    //!   constructor executes. s1.mutex() == 0. owns() == the value of
Chris@16:    //!   scop.owns() before the constructor executes. scop.owns().
Chris@16:    //!Notes: If the scop scoped_lock owns the mutex, ownership is moved
Chris@16:    //!   to thisscoped_lock with no blocking. If the scop scoped_lock does not
Chris@16:    //!   own the mutex, then neither will this scoped_lock. Only a moved
Chris@16:    //!   scoped_lock's will match this signature. An non-moved scoped_lock
Chris@16:    //!   can be moved with the expression: "boost::move(lock);". This
Chris@16:    //!   constructor does not alter the state of the mutex, only potentially
Chris@16:    //!   who owns it.
Chris@16:    scoped_lock(BOOST_RV_REF(scoped_lock) scop)
Chris@16:       : mp_mutex(0), m_locked(scop.owns())
Chris@16:    {  mp_mutex = scop.release(); }
Chris@16: 
Chris@16:    //!Effects: If upgr.owns() then calls unlock_upgradable_and_lock() on the
Chris@16:    //!   referenced mutex. upgr.release() is called.
Chris@16:    //!Postconditions: mutex() == the value upgr.mutex() had before the construction.
Chris@16:    //!   upgr.mutex() == 0. owns() == upgr.owns() before the construction.
Chris@16:    //!   upgr.owns() == false after the construction.
Chris@16:    //!Notes: If upgr is locked, this constructor will lock this scoped_lock while
Chris@16:    //!   unlocking upgr. If upgr is unlocked, then this scoped_lock will be
Chris@16:    //!   unlocked as well. Only a moved upgradable_lock's will match this
Chris@16:    //!   signature. An non-moved upgradable_lock can be moved with
Chris@16:    //!   the expression: "boost::move(lock);" This constructor may block if
Chris@16:    //!   other threads hold a sharable_lock on this mutex (sharable_lock's can
Chris@16:    //!   share ownership with an upgradable_lock).
Chris@16:    template<class T>
Chris@16:    explicit scoped_lock(BOOST_RV_REF(upgradable_lock<T>) upgr
Chris@16:       , typename ipcdetail::enable_if< ipcdetail::is_same<T, Mutex> >::type * = 0)
Chris@16:       : mp_mutex(0), m_locked(false)
Chris@16:    {
Chris@16:       upgradable_lock<mutex_type> &u_lock = upgr;
Chris@16:       if(u_lock.owns()){
Chris@16:          u_lock.mutex()->unlock_upgradable_and_lock();
Chris@16:          m_locked = true;
Chris@16:       }
Chris@16:       mp_mutex = u_lock.release();
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: If upgr.owns() then calls try_unlock_upgradable_and_lock() on the
Chris@16:    //!referenced mutex:
Chris@16:    //!   a)if try_unlock_upgradable_and_lock() returns true then mutex() obtains
Chris@16:    //!      the value from upgr.release() and owns() is set to true.
Chris@16:    //!   b)if try_unlock_upgradable_and_lock() returns false then upgr is
Chris@16:    //!      unaffected and this scoped_lock construction as the same effects as
Chris@16:    //!      a default construction.
Chris@16:    //!   c)Else upgr.owns() is false. mutex() obtains the value from upgr.release()
Chris@16:    //!      and owns() is set to false
Chris@16:    //!Notes: This construction will not block. It will try to obtain mutex
Chris@16:    //!   ownership from upgr immediately, while changing the lock type from a
Chris@16:    //!   "read lock" to a "write lock". If the "read lock" isn't held in the
Chris@16:    //!   first place, the mutex merely changes type to an unlocked "write lock".
Chris@16:    //!   If the "read lock" is held, then mutex transfer occurs only if it can
Chris@16:    //!   do so in a non-blocking manner.
Chris@16:    template<class T>
Chris@16:    scoped_lock(BOOST_RV_REF(upgradable_lock<T>) upgr, try_to_lock_type
Chris@16:          , typename ipcdetail::enable_if< ipcdetail::is_same<T, Mutex> >::type * = 0)
Chris@16:       : mp_mutex(0), m_locked(false)
Chris@16:    {
Chris@16:       upgradable_lock<mutex_type> &u_lock = upgr;
Chris@16:       if(u_lock.owns()){
Chris@16:          if((m_locked = u_lock.mutex()->try_unlock_upgradable_and_lock()) == true){
Chris@16:             mp_mutex = u_lock.release();
Chris@16:          }
Chris@16:       }
Chris@16:       else{
Chris@16:          u_lock.release();
Chris@16:       }
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: If upgr.owns() then calls timed_unlock_upgradable_and_lock(abs_time)
Chris@16:    //!   on the referenced mutex:
Chris@16:    //!   a)if timed_unlock_upgradable_and_lock(abs_time) returns true then mutex()
Chris@16:    //!      obtains the value from upgr.release() and owns() is set to true.
Chris@16:    //!   b)if timed_unlock_upgradable_and_lock(abs_time) returns false then upgr
Chris@16:    //!      is unaffected and this scoped_lock construction as the same effects
Chris@16:    //!      as a default construction.
Chris@16:    //!   c)Else upgr.owns() is false. mutex() obtains the value from upgr.release()
Chris@16:    //!      and owns() is set to false
Chris@16:    //!Notes: This construction will not block. It will try to obtain mutex ownership
Chris@16:    //!   from upgr immediately, while changing the lock type from a "read lock" to a
Chris@16:    //!   "write lock". If the "read lock" isn't held in the first place, the mutex
Chris@16:    //!   merely changes type to an unlocked "write lock". If the "read lock" is held,
Chris@16:    //!   then mutex transfer occurs only if it can do so in a non-blocking manner.
Chris@16:    template<class T>
Chris@16:    scoped_lock(BOOST_RV_REF(upgradable_lock<T>) upgr, boost::posix_time::ptime &abs_time
Chris@16:                , typename ipcdetail::enable_if< ipcdetail::is_same<T, Mutex> >::type * = 0)
Chris@16:       : mp_mutex(0), m_locked(false)
Chris@16:    {
Chris@16:       upgradable_lock<mutex_type> &u_lock = upgr;
Chris@16:       if(u_lock.owns()){
Chris@16:          if((m_locked = u_lock.mutex()->timed_unlock_upgradable_and_lock(abs_time)) == true){
Chris@16:             mp_mutex = u_lock.release();
Chris@16:          }
Chris@16:       }
Chris@16:       else{
Chris@16:          u_lock.release();
Chris@16:       }
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: If shar.owns() then calls try_unlock_sharable_and_lock() on the
Chris@16:    //!referenced mutex.
Chris@16:    //!   a)if try_unlock_sharable_and_lock() returns true then mutex() obtains
Chris@16:    //!      the value from shar.release() and owns() is set to true.
Chris@16:    //!   b)if try_unlock_sharable_and_lock() returns false then shar is
Chris@16:    //!      unaffected and this scoped_lock construction has the same
Chris@16:    //!      effects as a default construction.
Chris@16:    //!   c)Else shar.owns() is false. mutex() obtains the value from
Chris@16:    //!      shar.release() and owns() is set to false
Chris@16:    //!Notes: This construction will not block. It will try to obtain mutex
Chris@16:    //!   ownership from shar immediately, while changing the lock type from a
Chris@16:    //!   "read lock" to a "write lock". If the "read lock" isn't held in the
Chris@16:    //!   first place, the mutex merely changes type to an unlocked "write lock".
Chris@16:    //!   If the "read lock" is held, then mutex transfer occurs only if it can
Chris@16:    //!   do so in a non-blocking manner.
Chris@16:    template<class T>
Chris@16:    scoped_lock(BOOST_RV_REF(sharable_lock<T>) shar, try_to_lock_type
Chris@16:       , typename ipcdetail::enable_if< ipcdetail::is_same<T, Mutex> >::type * = 0)
Chris@16:       : mp_mutex(0), m_locked(false)
Chris@16:    {
Chris@16:       sharable_lock<mutex_type> &s_lock = shar;
Chris@16:       if(s_lock.owns()){
Chris@16:          if((m_locked = s_lock.mutex()->try_unlock_sharable_and_lock()) == true){
Chris@16:             mp_mutex = s_lock.release();
Chris@16:          }
Chris@16:       }
Chris@16:       else{
Chris@16:          s_lock.release();
Chris@16:       }
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: if (owns()) mp_mutex->unlock().
Chris@16:    //!Notes: The destructor behavior ensures that the mutex lock is not leaked.*/
Chris@16:    ~scoped_lock()
Chris@16:    {
Chris@16:       try{  if(m_locked && mp_mutex)   mp_mutex->unlock();  }
Chris@16:       catch(...){}
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: If owns() before the call, then unlock() is called on mutex().
Chris@16:    //!   *this gets the state of scop and scop gets set to a default constructed state.
Chris@16:    //!Notes: With a recursive mutex it is possible that both this and scop own
Chris@16:    //!   the same mutex before the assignment. In this case, this will own the
Chris@16:    //!   mutex after the assignment (and scop will not), but the mutex's lock
Chris@16:    //!   count will be decremented by one.
Chris@16:    scoped_lock &operator=(BOOST_RV_REF(scoped_lock) scop)
Chris@16:    {
Chris@16:       if(this->owns())
Chris@16:          this->unlock();
Chris@16:       m_locked = scop.owns();
Chris@16:       mp_mutex = scop.release();
Chris@16:       return *this;
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: If mutex() == 0 or if already locked, throws a lock_exception()
Chris@16:    //!   exception. Calls lock() on the referenced mutex.
Chris@16:    //!Postconditions: owns() == true.
Chris@16:    //!Notes: The scoped_lock changes from a state of not owning the mutex, to
Chris@16:    //!   owning the mutex, blocking if necessary.
Chris@16:    void lock()
Chris@16:    {
Chris@16:       if(!mp_mutex || m_locked)
Chris@16:          throw lock_exception();
Chris@16:       mp_mutex->lock();
Chris@16:       m_locked = true;
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: If mutex() == 0 or if already locked, throws a lock_exception()
Chris@16:    //!   exception. Calls try_lock() on the referenced mutex.
Chris@16:    //!Postconditions: owns() == the value returned from mutex()->try_lock().
Chris@16:    //!Notes: The scoped_lock changes from a state of not owning the mutex, to
Chris@16:    //!   owning the mutex, but only if blocking was not required. If the
Chris@16:    //!   mutex_type does not support try_lock(), this function will fail at
Chris@16:    //!   compile time if instantiated, but otherwise have no effect.*/
Chris@16:    bool try_lock()
Chris@16:    {
Chris@16:       if(!mp_mutex || m_locked)
Chris@16:          throw lock_exception();
Chris@16:       m_locked = mp_mutex->try_lock();
Chris@16:       return m_locked;
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: If mutex() == 0 or if already locked, throws a lock_exception()
Chris@16:    //!   exception. Calls timed_lock(abs_time) on the referenced mutex.
Chris@16:    //!Postconditions: owns() == the value returned from mutex()-> timed_lock(abs_time).
Chris@16:    //!Notes: The scoped_lock changes from a state of not owning the mutex, to
Chris@16:    //!   owning the mutex, but only if it can obtain ownership by the specified
Chris@16:    //!   time. If the mutex_type does not support timed_lock (), this function
Chris@16:    //!   will fail at compile time if instantiated, but otherwise have no effect.*/
Chris@16:    bool timed_lock(const boost::posix_time::ptime& abs_time)
Chris@16:    {
Chris@16:       if(!mp_mutex || m_locked)
Chris@16:          throw lock_exception();
Chris@16:       m_locked = mp_mutex->timed_lock(abs_time);
Chris@16:       return m_locked;
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: If mutex() == 0 or if not locked, throws a lock_exception()
Chris@16:    //!   exception. Calls unlock() on the referenced mutex.
Chris@16:    //!Postconditions: owns() == false.
Chris@16:    //!Notes: The scoped_lock changes from a state of owning the mutex, to not
Chris@16:    //!   owning the mutex.*/
Chris@16:    void unlock()
Chris@16:    {
Chris@16:       if(!mp_mutex || !m_locked)
Chris@16:          throw lock_exception();
Chris@16:       mp_mutex->unlock();
Chris@16:       m_locked = false;
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: Returns true if this scoped_lock has acquired
Chris@16:    //!the referenced mutex.
Chris@16:    bool owns() const
Chris@16:    {  return m_locked && mp_mutex;  }
Chris@16: 
Chris@16:    //!Conversion to bool.
Chris@16:    //!Returns owns().
Chris@16:    operator unspecified_bool_type() const
Chris@16:    {  return m_locked? &this_type::m_locked : 0;   }
Chris@16: 
Chris@16:    //!Effects: Returns a pointer to the referenced mutex, or 0 if
Chris@16:    //!there is no mutex to reference.
Chris@16:    mutex_type* mutex() const
Chris@16:    {  return  mp_mutex;  }
Chris@16: 
Chris@16:    //!Effects: Returns a pointer to the referenced mutex, or 0 if there is no
Chris@16:    //!   mutex to reference.
Chris@16:    //!Postconditions: mutex() == 0 and owns() == false.
Chris@16:    mutex_type* release()
Chris@16:    {
Chris@16:       mutex_type *mut = mp_mutex;
Chris@16:       mp_mutex = 0;
Chris@16:       m_locked = false;
Chris@16:       return mut;
Chris@16:    }
Chris@16: 
Chris@16:    //!Effects: Swaps state with moved lock.
Chris@16:    //!Throws: Nothing.
Chris@16:    void swap( scoped_lock<mutex_type> &other)
Chris@16:    {
Chris@101:       (simple_swap)(mp_mutex, other.mp_mutex);
Chris@101:       (simple_swap)(m_locked, other.m_locked);
Chris@16:    }
Chris@16: 
Chris@101:    #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED)
Chris@16:    private:
Chris@16:    mutex_type *mp_mutex;
Chris@16:    bool        m_locked;
Chris@101:    #endif   //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED
Chris@16: };
Chris@16: 
Chris@16: } // namespace interprocess
Chris@16: } // namespace boost
Chris@16: 
Chris@16: #include <boost/interprocess/detail/config_end.hpp>
Chris@16: 
Chris@16: #endif // BOOST_INTERPROCESS_SCOPED_LOCK_HPP