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_UPGRADABLE_LOCK_HPP Chris@16: #define BOOST_INTERPROCESS_UPGRADABLE_LOCK_HPP Chris@16: Chris@101: #ifndef BOOST_CONFIG_HPP Chris@101: # include 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 Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: Chris@16: #include Chris@101: #include Chris@16: #include Chris@16: Chris@16: //!\file Chris@16: //!Describes the upgradable_lock class that serves to acquire the upgradable Chris@16: //!lock of a mutex. Chris@16: Chris@16: namespace boost { Chris@16: namespace interprocess { Chris@16: Chris@16: //!upgradable_lock is meant to carry out the tasks for read-locking, unlocking, Chris@16: //!try-read-locking and timed-read-locking (recursive or not) for the Mutex. Chris@16: //!Additionally the upgradable_lock can transfer ownership to a scoped_lock Chris@16: //!using transfer_lock syntax. The Mutex need not supply all of the functionality. Chris@16: //!If the client of upgradable_lock does not use functionality which the Chris@16: //!Mutex does not supply, no harm is done. Mutex ownership can be shared among Chris@16: //!read_locks, and a single upgradable_lock. upgradable_lock does not support Chris@16: //!copy semantics. However upgradable_lock supports ownership transfer from Chris@16: //!a upgradable_locks or scoped_locks via transfer_lock syntax. Chris@16: template Chris@16: class upgradable_lock Chris@16: { Chris@16: public: Chris@16: typedef UpgradableMutex mutex_type; Chris@101: #if !defined(BOOST_INTERPROCESS_DOXYGEN_INVOKED) Chris@16: private: Chris@16: typedef upgradable_lock this_type; Chris@16: explicit upgradable_lock(scoped_lock&); Chris@16: typedef bool this_type::*unspecified_bool_type; Chris@16: BOOST_MOVABLE_BUT_NOT_COPYABLE(upgradable_lock) Chris@101: #endif //#ifndef BOOST_INTERPROCESS_DOXYGEN_INVOKED Chris@16: public: Chris@16: Chris@16: //!Effects: Default constructs a upgradable_lock. Chris@16: //!Postconditions: owns() == false and mutex() == 0. Chris@16: upgradable_lock() Chris@16: : mp_mutex(0), m_locked(false) Chris@16: {} Chris@16: Chris@16: explicit upgradable_lock(mutex_type& m) Chris@16: : mp_mutex(&m), m_locked(false) Chris@16: { mp_mutex->lock_upgradable(); 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: upgradable_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 upgradable Chris@16: //! locked. There is no effect required on the referenced mutex. Chris@16: upgradable_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_upgradable(). Chris@16: //!Postconditions: mutex() == &m. owns() == the return value of the Chris@16: //! m.try_lock_upgradable() executed within the constructor. Chris@16: //!Notes: The constructor will take upgradable-ownership of the mutex Chris@16: //! if it can do so without waiting. 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_upgradable, this constructor will fail at Chris@16: //! compile time if instantiated, but otherwise have no effect. Chris@16: upgradable_lock(mutex_type& m, try_to_lock_type) Chris@16: : mp_mutex(&m), m_locked(false) Chris@16: { m_locked = mp_mutex->try_lock_upgradable(); } Chris@16: Chris@16: //!Effects: m.timed_lock_upgradable(abs_time) Chris@16: //!Postconditions: mutex() == &m. owns() == the return value of the Chris@16: //! m.timed_lock_upgradable() executed within the constructor. Chris@16: //!Notes: The constructor will take upgradable-ownership of the mutex if it Chris@16: //! can do so within the time specified. Whether or not this constructor Chris@16: //! handles recursive locking depends upon the mutex. If the mutex_type Chris@16: //! does not support timed_lock_upgradable, this constructor will fail Chris@16: //! at compile time if instantiated, but otherwise have no effect. Chris@16: upgradable_lock(mutex_type& m, const boost::posix_time::ptime& abs_time) Chris@16: : mp_mutex(&m), m_locked(false) Chris@16: { m_locked = mp_mutex->timed_lock_upgradable(abs_time); } Chris@16: Chris@16: //!Effects: No effects on the underlying mutex. Chris@16: //!Postconditions: mutex() == the value upgr.mutex() had before the Chris@16: //! construction. upgr.mutex() == 0. owns() == upgr.owns() before the Chris@16: //! construction. upgr.owns() == false. Chris@16: //!Notes: If upgr is locked, this constructor will lock this upgradable_lock Chris@16: //! while unlocking upgr. If upgr is unlocked, then this upgradable_lock will Chris@16: //! be unlocked as well. Only a moved upgradable_lock's will match this Chris@16: //! signature. An non-moved upgradable_lock can be moved with the Chris@16: //! expression: "boost::move(lock);". This constructor does not alter the Chris@16: //! state of the mutex, only potentially who owns it. Chris@16: upgradable_lock(BOOST_RV_REF(upgradable_lock) upgr) Chris@16: : mp_mutex(0), m_locked(upgr.owns()) Chris@16: { mp_mutex = upgr.release(); } Chris@16: Chris@16: //!Effects: If scop.owns(), m_.unlock_and_lock_upgradable(). Chris@16: //!Postconditions: mutex() == the value scop.mutex() had before the construction. Chris@16: //! scop.mutex() == 0. owns() == scop.owns() before the constructor. After the Chris@16: //! construction, scop.owns() == false. Chris@16: //!Notes: If scop is locked, this constructor will transfer the exclusive-ownership Chris@16: //! to an upgradable-ownership of this upgradable_lock. Chris@16: //! Only a moved sharable_lock's will match this Chris@16: //! signature. An non-moved sharable_lock can be moved with the Chris@16: //! expression: "boost::move(lock);". Chris@16: template Chris@16: upgradable_lock(BOOST_RV_REF(scoped_lock) scop Chris@16: , typename ipcdetail::enable_if< ipcdetail::is_same >::type * = 0) Chris@16: : mp_mutex(0), m_locked(false) Chris@16: { Chris@16: scoped_lock &u_lock = scop; Chris@16: if(u_lock.owns()){ Chris@16: u_lock.mutex()->unlock_and_lock_upgradable(); Chris@16: m_locked = true; Chris@16: } Chris@16: mp_mutex = u_lock.release(); Chris@16: } Chris@16: Chris@16: //!Effects: If shar.owns() then calls try_unlock_sharable_and_lock_upgradable() Chris@16: //! on the referenced mutex. Chris@16: //! a)if try_unlock_sharable_and_lock_upgradable() returns true then mutex() Chris@16: //! obtains the value from shar.release() and owns() is set to true. Chris@16: //! b)if try_unlock_sharable_and_lock_upgradable() returns false then shar is Chris@16: //! unaffected and this upgradable_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 shar.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 shar immediately, while changing the lock type from a Chris@16: //! "read lock" to an "upgradable lock". If the "read lock" isn't held Chris@16: //! in the first place, the mutex merely changes type to an unlocked Chris@16: //! "upgradable lock". If the "read lock" is held, then mutex transfer Chris@16: //! occurs only if it can do so in a non-blocking manner. Chris@16: template Chris@16: upgradable_lock( BOOST_RV_REF(sharable_lock) shar, try_to_lock_type Chris@16: , typename ipcdetail::enable_if< ipcdetail::is_same >::type * = 0) Chris@16: : mp_mutex(0), m_locked(false) Chris@16: { Chris@16: sharable_lock &s_lock = shar; Chris@16: if(s_lock.owns()){ Chris@16: if((m_locked = s_lock.mutex()->try_unlock_sharable_and_lock_upgradable()) == 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()) m_->unlock_upgradable(). Chris@16: //!Notes: The destructor behavior ensures that the mutex lock is not leaked. Chris@16: ~upgradable_lock() Chris@16: { Chris@16: try{ Chris@16: if(m_locked && mp_mutex) mp_mutex->unlock_upgradable(); Chris@16: } Chris@16: catch(...){} Chris@16: } Chris@16: Chris@16: //!Effects: If owns(), then unlock_upgradable() is called on mutex(). Chris@16: //! *this gets the state of upgr and upgr gets set to a default constructed state. Chris@16: //!Notes: With a recursive mutex it is possible that both this and upgr own the Chris@16: //! mutex before the assignment. In this case, this will own the mutex Chris@16: //! after the assignment (and upgr will not), but the mutex's upgradable lock Chris@16: //! count will be decremented by one. Chris@16: upgradable_lock &operator=(BOOST_RV_REF(upgradable_lock) upgr) Chris@16: { Chris@16: if(this->owns()) Chris@16: this->unlock(); Chris@16: m_locked = upgr.owns(); Chris@16: mp_mutex = upgr.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_upgradable() on the referenced mutex. Chris@16: //!Postconditions: owns() == true. Chris@16: //!Notes: The sharable_lock changes from a state of not owning the mutex, Chris@16: //! to 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_upgradable(); 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_upgradable() on the referenced mutex. Chris@16: //!Postconditions: owns() == the value returned from Chris@16: //! mutex()->try_lock_upgradable(). Chris@16: //!Notes: The upgradable_lock changes from a state of not owning the mutex, Chris@16: //! to owning the mutex, but only if blocking was not required. If the Chris@16: //! mutex_type does not support try_lock_upgradable(), this function will Chris@16: //! fail at 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_upgradable(); 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_upgradable(abs_time) on the referenced mutex. Chris@16: //!Postconditions: owns() == the value returned from Chris@16: //! mutex()->timed_lock_upgradable(abs_time). Chris@16: //!Notes: The upgradable_lock changes from a state of not owning the mutex, Chris@16: //! to owning the mutex, but only if it can obtain ownership within the Chris@16: //! specified time. If the mutex_type does not support Chris@16: //! timed_lock_upgradable(abs_time), this function will fail at compile Chris@16: //! 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_upgradable(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_upgradable() on the referenced mutex. Chris@16: //!Postconditions: owns() == false. Chris@16: //!Notes: The upgradable_lock changes from a state of owning the mutex, Chris@16: //! to not 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_upgradable(); Chris@16: m_locked = false; Chris@16: } Chris@16: Chris@16: //!Effects: Returns true if this scoped_lock has acquired the Chris@16: //!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(upgradable_lock &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 Chris@16: Chris@16: #endif // BOOST_INTERPROCESS_UPGRADABLE_LOCK_HPP