| Home | Libraries | People | FAQ | More

## Class template upgradable_lock

boost::interprocess::upgradable_lock

## Synopsis

    // In header: <boost/interprocess/sync/upgradable_lock.hpp>

    template<typename UpgradableMutex>
    class upgradable_lock {
    public:
      // types
      typedef UpgradableMutex mutex_type;

      // construct/copy/destruct
      upgradable_lock();
      explicit upgradable_lock(mutex_type &);
      upgradable_lock(mutex_type &, defer_lock_type);
      upgradable_lock(mutex_type &, accept_ownership_type);
      upgradable_lock(mutex_type &, try_to_lock_type);
      upgradable_lock(mutex_type &, const boost::posix_time::ptime &);
      upgradable_lock(upgradable_lock< mutex_type > &&);
      template<typename T> upgradable_lock(scoped_lock< T > &&, unspecified = 0);
      template<typename T>
        upgradable_lock(sharable_lock< T > &&, try_to_lock_type, unspecified = 0);
      upgradable_lock& operator=(upgradable_lock &&);
      ~upgradable_lock();

      // public member functions
      void lock();
      bool try_lock();
      bool timed_lock(const boost::posix_time::ptime &);
      void unlock();
      bool owns() const;
      operator unspecified_bool_type() const;
      mutex_type * mutex() const;
      mutex_type * release();
      void swap(upgradable_lock< mutex_type > &);
    };

## Description

upgradable_lock is meant to carry out the tasks for read-locking, unlocking, try-read-locking and timed-read-locking (recursive or not) for the Mutex. Additionally the upgradable_lock can transfer ownership to a scoped_lock using transfer_lock syntax. The Mutex need not supply all of the functionality. If the client of upgradable_lock<Mutex> does not use functionality which the Mutex does not supply, no harm is done. Mutex ownership can be shared among read_locks, and a single upgradable_lock. upgradable_lock does not support copy semantics. However upgradable_lock supports ownership transfer from a upgradable_locks or scoped_locks via transfer_lock syntax.

### `upgradable_lock` public construct/copy/destruct

1.     upgradable_lock();

   Effects: Default constructs a `upgradable_lock`. Postconditions: owns() == false and mutex() == 0.

2.     explicit upgradable_lock(mutex_type & m);

3.     upgradable_lock(mutex_type & m, defer_lock_type);

   Postconditions: owns() == false, and mutex() == &m. Notes: The constructor will not take ownership of the mutex. There is no effect required on the referenced mutex.

4.     upgradable_lock(mutex_type & m, accept_ownership_type);

   Postconditions: owns() == true, and mutex() == &m. Notes: The constructor will suppose that the mutex is already upgradable locked. There is no effect required on the referenced mutex.

5.     upgradable_lock(mutex_type & m, try_to_lock_type);

   Effects: m.try_lock_upgradable(). Postconditions: mutex() == &m. owns() == the return value of the m.try_lock_upgradable() executed within the constructor. Notes: The constructor will take upgradable-ownership of the mutex if it can do so without waiting. Whether or not this constructor handles recursive locking depends upon the mutex. If the mutex_type does not support try_lock_upgradable, this constructor will fail at compile time if instantiated, but otherwise have no effect.

6.     upgradable_lock(mutex_type & m, const boost::posix_time::ptime & abs_time);

   Effects: m.timed_lock_upgradable(abs_time) Postconditions: mutex() == &m. owns() == the return value of the m.timed_lock_upgradable() executed within the constructor. Notes: The constructor will take upgradable-ownership of the mutex if it can do so within the time specified. Whether or not this constructor handles recursive locking depends upon the mutex. If the mutex_type does not support timed_lock_upgradable, this constructor will fail at compile time if instantiated, but otherwise have no effect.

7.     upgradable_lock(upgradable_lock< mutex_type > && upgr);

   Effects: No effects on the underlying mutex. Postconditions: mutex() == the value upgr.mutex() had before the construction. upgr.mutex() == 0. owns() == upgr.owns() before the construction. upgr.owns() == false. Notes: If upgr is locked, this constructor will lock this `upgradable_lock` while unlocking upgr. If upgr is unlocked, then this `upgradable_lock` will be unlocked as well. Only a moved upgradable_lock's will match this signature. An non-moved `upgradable_lock` can be moved with the expression: "boost::move(lock);". This constructor does not alter the state of the mutex, only potentially who owns it.

8.     template<typename T>
         upgradable_lock(scoped_lock< T > && scop, unspecified = 0);

   Effects: If scop.owns(), m_.unlock_and_lock_upgradable(). Postconditions: mutex() == the value scop.mutex() had before the construction. scop.mutex() == 0. owns() == scop.owns() before the constructor. After the construction, scop.owns() == false. Notes: If scop is locked, this constructor will transfer the exclusive-ownership to an upgradable-ownership of this `upgradable_lock`. Only a moved sharable_lock's will match this signature. An non-moved `sharable_lock` can be moved with the expression: "boost::move(lock);".

9.     template<typename T>
         upgradable_lock(sharable_lock< T > && shar, try_to_lock_type,
                         unspecified = 0);

   Effects: If shar.owns() then calls try_unlock_sharable_and_lock_upgradable() on the referenced mutex. a)if try_unlock_sharable_and_lock_upgradable() returns true then mutex() obtains the value from shar.release() and owns() is set to true. b)if try_unlock_sharable_and_lock_upgradable() returns false then shar is unaffected and this `upgradable_lock` construction has the same effects as a default construction. c)Else shar.owns() is false. mutex() obtains the value from shar.release() and owns() is set to false. Notes: This construction will not block. It will try to obtain mutex ownership from shar immediately, while changing the lock type from a "read lock" to an "upgradable lock". If the "read lock" isn't held in the first place, the mutex merely changes type to an unlocked "upgradable lock". If the "read lock" is held, then mutex transfer occurs only if it can do so in a non-blocking manner.

10.     upgradable_lock& operator=(upgradable_lock && upgr);

    Effects: If owns(), then unlock_upgradable() is called on mutex(). this gets the state of upgr and upgr gets set to a default constructed state. Notes: With a recursive mutex it is possible that both this and upgr own the mutex before the assignment. In this case, this will own the mutex after the assignment (and upgr will not), but the mutex's upgradable lock count will be decremented by one.

11.     ~upgradable_lock();

    Effects: if (owns()) m_->unlock_upgradable(). Notes: The destructor behavior ensures that the mutex lock is not leaked.

### `upgradable_lock` public member functions

1.     void lock();

   Effects: If mutex() == 0 or if already locked, throws a lock_exception() exception. Calls lock_upgradable() on the referenced mutex. Postconditions: owns() == true. Notes: The `sharable_lock` changes from a state of not owning the mutex, to owning the mutex, blocking if necessary.

2.     bool try_lock();

   Effects: If mutex() == 0 or if already locked, throws a lock_exception() exception. Calls try_lock_upgradable() on the referenced mutex. Postconditions: owns() == the value returned from mutex()->try_lock_upgradable(). Notes: The `upgradable_lock` changes from a state of not owning the mutex, to owning the mutex, but only if blocking was not required. If the mutex_type does not support try_lock_upgradable(), this function will fail at compile time if instantiated, but otherwise have no effect.

3.     bool timed_lock(const boost::posix_time::ptime & abs_time);

   Effects: If mutex() == 0 or if already locked, throws a lock_exception() exception. Calls timed_lock_upgradable(abs_time) on the referenced mutex. Postconditions: owns() == the value returned from mutex()->timed_lock_upgradable(abs_time). Notes: The `upgradable_lock` changes from a state of not owning the mutex, to owning the mutex, but only if it can obtain ownership within the specified time. If the mutex_type does not support timed_lock_upgradable(abs_time), this function will fail at compile time if instantiated, but otherwise have no effect.

4.     void unlock();

   Effects: If mutex() == 0 or if not locked, throws a lock_exception() exception. Calls unlock_upgradable() on the referenced mutex. Postconditions: owns() == false. Notes: The `upgradable_lock` changes from a state of owning the mutex, to not owning the mutex.

5.     bool owns() const;

   Effects: Returns true if this `scoped_lock` has acquired the referenced mutex.

6.     operator unspecified_bool_type() const;

   Conversion to bool. Returns owns().

7.     mutex_type * mutex() const;

   Effects: Returns a pointer to the referenced mutex, or 0 if there is no mutex to reference.

8.     mutex_type * release();

   Effects: Returns a pointer to the referenced mutex, or 0 if there is no mutex to reference. Postconditions: mutex() == 0 and owns() == false.

9.     void swap(upgradable_lock< mutex_type > & other);

   Effects: Swaps state with moved lock. Throws: Nothing.