| Home | Libraries | People | FAQ | More

## Synchronized Data Structures

### Synchronized values - EXPERIMENTAL

| Warning
These features are experimental and subject to change in future versions. There are not too much tests yet, so it is possible that you can find out some trivial bugs :(

#### Tutorial

| Note
This tutorial is an adaptation of the paper of Anthony Williams "Enforcing Correct Mutex Usage with Synchronized Values" to the Boost library.

##### The Problem with Mutexes

The key problem with protecting shared data with a mutex is that there is no easy way to associate the mutex with the data. It is thus relatively easy to accidentally write code that fails to lock the right mutex - or even locks the wrong mutex - and the compiler will not help you.

    std::mutex m1;
    int value1;
    std::mutex m2;
    int value2;

    int readValue1()
    {
      boost::lock_guard<boost::mutex> lk(m1);
      return value1;
    }
    int readValue2()
    {
      boost::lock_guard<boost::mutex> lk(m1); // oops: wrong mutex
      return value2;
    }

Moreover, managing the mutex lock also clutters the source code, making it harder to see what is really going on.

The use of synchronized_value solves both these problems - the mutex is intimately tied to the value, so you cannot access it without a lock, and yet access semantics are still straightforward. For simple accesses, synchronized_value behaves like a pointer-to-T; for example:

    boost::synchronized_value<std::string> value3;
    std::string readValue3()
    {
      return *value3;
    }
    void setValue3(std::string const& newVal)
    {
      *value3=newVal;
    }
    void appendToValue3(std::string const& extra)
    {
      value3->append(extra);
    }

Both forms of pointer dereference return a proxy object rather than a real reference, to ensure that the lock on the mutex is held across the assignment or method call, but this is transparent to the user.

##### Beyond Simple Accesses

The pointer-like semantics work very well for simple accesses such as assignment and calls to member functions. However, sometimes you need to perform an operation that requires multiple accesses under protection of the same lock, and that's what the synchronize() method provides.

By calling synchronize() you obtain an strict_lock_ptr object that holds a lock on the mutex protecting the data, and which can be used to access the protected data. The lock is held until the strict_lock_ptr object is destroyed, so you can safely perform multi-part operations. The strict_lock_ptr object also acts as a pointer-to-T, just like synchronized_value does, but this time the lock is already held. For example, the following function adds a trailing slash to a path held in a synchronized_value. The use of the strict_lock_ptr object ensures that the string hasn't changed in between the query and the update.

    void addTrailingSlashIfMissing(boost::synchronized_value<std::string> & path)
    {
      boost::strict_lock_ptr<std::string> u=path.synchronize();

      if(u->empty() || (*u->rbegin()!='/'))
      {
        *u+='/';
      }
    }

##### Operations Across Multiple Objects

Though synchronized_value works very well for protecting a single object of type T, nothing that we've seen so far solves the problem of operations that require atomic access to multiple objects unless those objects can be combined within a single structure protected by a single mutex.

One way to protect access to two synchronized_value objects is to construct a strict_lock_ptr for each object and use those to access the respective protected values; for instance:

    synchronized_value<std::queue<MessageType> > q1,q2;
    void transferMessage()
    {
      strict_lock_ptr<std::queue<MessageType> > u1 = q1.synchronize();
      strict_lock_ptr<std::queue<MessageType> > u2 = q2.synchronize();

      if(!u1->empty())
      {
        u2->push_back(u1->front());
        u1->pop_front();
      }
    }

This works well in some scenarios, but not all -- if the same two objects are updated together in different sections of code then you need to take care to ensure that the strict_lock_ptr objects are constructed in the same sequence in all cases, otherwise you have the potential for deadlock. This is just the same as when acquiring any two mutexes.

In order to be able to use the dead-lock free lock algorithms we need to use instead unique_lock_ptr, which is Lockable.

    synchronized_value<std::queue<MessageType> > q1,q2;
    void transferMessage()
    {
      unique_lock_ptr<std::queue<MessageType> > u1 = q1.unique_synchronize(boost::defer_lock);
      unique_lock_ptr<std::queue<MessageType> > u2 = q2.unique_synchronize(boost::defer_lock);
      boost::lock(u1,u2); // dead-lock free algorithm

      if(!u1->empty())
      {
        u2->push_back(u1->front());
        u1->pop_front();
      }
    }

While the preceding takes care of dead-lock, the access to the synchronized_value via unique_lock_ptr requires a lock that is not forced by the interface. An alternative on compilers providing a standard library that supports movable std::tuple is to use the free synchronize function, which will lock all the mutexes associated to the synchronized values and return a tuple os strict_lock_ptr.

    synchronized_value<std::queue<MessageType> > q1,q2;
    void transferMessage()
    {
      auto lks = synchronize(u1,u2); // dead-lock free algorithm

      if(!std::get<1>(lks)->empty())
      {
        std::get<2>(lks)->push_back(u1->front());
        std::get<1>(lks)->pop_front();
      }
    }

##### Value semantics

synchronized_value has value semantics even if the syntax lets is close to a pointer (this is just because we are unable to define smart references).

#### Reference

    #include <boost/thread/synchronized_value.hpp>
    namespace boost
    {

      template<typename T, typename Lockable = mutex>
      class synchronized_value;

      // Specialized swap algorithm
      template <typename T, typename L>
      void swap(synchronized_value<T,L> & lhs, synchronized_value<T,L> & rhs);
      template <typename T, typename L>
      void swap(synchronized_value<T,L> & lhs, T & rhs);
      template <typename T, typename L>
      void swap(T & lhs, synchronized_value<T,L> & rhs);

      // Hash support
      template<typename T, typename L>
      struct hash<synchronized_value<T,L> >;

      // Comparison
      template <typename T, typename L>
      bool operator==(synchronized_value<T,L> const&lhs, synchronized_value<T,L> const& rhs)
      template <typename T, typename L>
      bool operator!=(synchronized_value<T,L> const&lhs, synchronized_value<T,L> const& rhs)
      template <typename T, typename L>
      bool operator<(synchronized_value<T,L> const&lhs, synchronized_value<T,L> const& rhs)
      template <typename T, typename L>
      bool operator<=(synchronized_value<T,L> const&lhs, synchronized_value<T,L> const& rhs)
      template <typename T, typename L>
      bool operator>(synchronized_value<T,L> const&lhs, synchronized_value<T,L> const& rhs)
      template <typename T, typename L>
      bool operator>=(synchronized_value<T,L> const&lhs, synchronized_value<T,L> const& rhs)

      // Comparison with T
      template <typename T, typename L>
      bool operator==(T const& lhs, synchronized_value<T,L> const&rhs);
      template <typename T, typename L>
      bool operator!=(T const& lhs, synchronized_value<T,L> const&rhs);
      template <typename T, typename L>
      bool operator<(T const& lhs, synchronized_value<T,L> const&rhs);
      template <typename T, typename L>
      bool operator<=(T const& lhs, synchronized_value<T,L> const&rhs);
      template <typename T, typename L>
      bool operator>(T const& lhs, synchronized_value<T,L> const&rhs);
      template <typename T, typename L>
      bool operator>=(T const& lhs, synchronized_value<T,L> const&rhs);

      template <typename T, typename L>
      bool operator==(synchronized_value<T,L> const& lhs, T const& rhs);
      template <typename T, typename L>
      bool operator!=(synchronized_value<T,L> const& lhs, T const& rhs);
      template <typename T, typename L>
      bool operator<(synchronized_value<T,L> const& lhs, T const& rhs);
      template <typename T, typename L>
      bool operator<=(synchronized_value<T,L> const& lhs, T const& rhs);
      template <typename T, typename L>
      bool operator>(synchronized_value<T,L> const& lhs, T const& rhs);
      template <typename T, typename L>
      bool operator>=(synchronized_value<T,L> const& lhs, T const& rhs);

    #if ! defined(BOOST_THREAD_NO_SYNCHRONIZE)
      template <typename ...SV>
      std::tuple<typename synchronized_value_strict_lock_ptr<SV>::type ...> synchronize(SV& ...sv);
    #endif
    }

##### Class `synchronized_value`

    #include <boost/thread/synchronized_value.hpp>

    namespace boost
    {

      template<typename T, typename Lockable = mutex>
      class synchronized_value
      {
      public:
        typedef T value_type;
        typedef Lockable mutex_type;

        synchronized_value() noexept(is_nothrow_default_constructible<T>::value);
        synchronized_value(T const& other) noexept(is_nothrow_copy_constructible<T>::value);
        synchronized_value(T&& other) noexept(is_nothrow_move_constructible<T>::value);
        synchronized_value(synchronized_value const& rhs);
        synchronized_value(synchronized_value&& other);

        // mutation
        synchronized_value& operator=(synchronized_value const& rhs);
        synchronized_value& operator=(value_type const& val);
        void swap(synchronized_value & rhs);
        void swap(value_type & rhs);

        //observers
        T get() const;
      #if ! defined(BOOST_NO_CXX11_EXPLICIT_CONVERSION_OPERATORS)
        explicit operator T() const;
      #endif

        strict_lock_ptr<T,Lockable> operator->();
        const_strict_lock_ptr<T,Lockable> operator->() const;
        strict_lock_ptr<T,Lockable> synchronize();
        const_strict_lock_ptr<T,Lockable> synchronize() const;

        deref_value operator*();;
        const_deref_value operator*() const;

      private:
        T value_; // for exposition only
        mutable mutex_type mtx_;  // for exposition only
      };
    }

Requires:

  `Lockable` is `Lockable`.

###### `synchronized_value()`

    synchronized_value() noexept(is_nothrow_default_constructible<T>::value);

Requires:

  `T` is `DefaultConstructible`.

Effects:

  Default constructs the cloaked value_type

Throws:

  Any exception thrown by `value_type()`.

###### `synchronized_value(T const&)`

    synchronized_value(T const& other) noexept(is_nothrow_copy_constructible<T>::value);

Requires:

  `T` is `CopyConstructible`.

Effects:

  Copy constructs the cloaked value_type using the parameter `other`

Throws:

  Any exception thrown by `value_type(other)`.

###### `synchronized_value(synchronized_value const&)`

    synchronized_value(synchronized_value const& rhs);

Requires:

  `T` is `DefaultConstructible` and `Assignable`.

Effects:

  Assigns the value on a scope protected by the mutex of the rhs. The mutex is not copied.

Throws:

  Any exception thrown by `value_type()` or `value_type& operator=(value_type&)` or `mtx_.lock()`.

###### `synchronized_value(T&&)`

    synchronized_value(T&& other) noexept(is_nothrow_move_constructible<T>::value);

Requires:

  `T` is `CopyMovable` .

Effects:

  Move constructs the cloaked value_type

Throws:

  Any exception thrown by `value_type(value_type&&)`.

###### `synchronized_value(synchronized_value&&)`

    synchronized_value(synchronized_value&& other);

Requires:

  `T` is `CopyMovable` .

Effects:

  Move constructs the cloaked value_type

Throws:

  Any exception thrown by `value_type(value_type&&)` or `mtx_.lock()`.

###### `operator=(synchronized_value const&)`

    synchronized_value& operator=(synchronized_value const& rhs);

Requires:

  `T` is `Assignale`.

Effects:

  Copies the underlying value on a scope protected by the two mutexes. The mutex is not copied. The locks are acquired avoiding deadlock. For example, there is no problem if one thread assigns `a = b` and the other assigns `b = a`.

Return:

  `*this`

Throws:

  Any exception thrown by `value_type& operator(value_type const&)` or `mtx_.lock()`.

###### `operator=(T const&)`

    synchronized_value& operator=(value_type const& val);

Requires:

  `T` is `Assignale`.

Effects:

  Copies the value on a scope protected by the mutex.

Return:

  `*this`

Throws:

  Any exception thrown by `value_type& operator(value_type const&)` or `mtx_.lock()`.

###### `get() const`

    T get() const;

Requires:

  `T` is `CopyConstructible`.

Return:

  `A copy of the protected value obtained on a scope protected by the mutex.`

Throws:

  Any exception thrown by `value_type(value_type const&)` or `mtx_.lock()`.

###### `operator T() const`

    #if ! defined(BOOST_NO_CXX11_EXPLICIT_CONVERSION_OPERATORS)
      explicit operator T() const;
    #endif

Requires:

  `T` is `CopyConstructible`.

Return:

  `A copy of the protected value obtained on a scope protected by the mutex.`

Throws:

  Any exception thrown by `value_type(value_type const&)` or `mtx_.lock()`.

###### `swap(synchronized_value&)`

    void swap(synchronized_value & rhs);

Requires:

  `T` is `Assignale`.

Effects:

  Swaps the data on a scope protected by both mutex. Both mutex are acquired to avoid dead-lock. The mutexes are not swapped.

Throws:

  Any exception thrown by `swap(value_, rhs.value)` or `mtx_.lock()` or `rhs_.mtx_.lock()`.

###### `swap(synchronized_value&)`

    void swap(value_type & rhs);

Requires:

  `T` is `Swapable`.

Effects:

  Swaps the data on a scope protected by both mutex. Both mutex are acquired to avoid dead-lock. The mutexes are not swapped.

Throws:

  Any exception thrown by `swap(value_, rhs)` or `mtx_.lock()`.

###### `operator->()`

    strict_lock_ptr<T,Lockable> operator->();

Essentially calling a method `obj->foo(x, y, z)` calls the method `foo(x, y, z)` inside a critical section as long-lived as the call itself.

Return:

  `A strict_lock_ptr<>.`

Throws:

  Nothing.

###### `operator->() const`

    const_strict_lock_ptr<T,Lockable> operator->() const;

If the `synchronized_value` object involved is const-qualified, then you'll only be able to call const methods through `operator->`. So, for example, `vec->push_back("xyz")` won't work if `vec` were const-qualified. The locking mechanism capitalizes on the assumption that const methods don't modify their underlying data.

Return:

  `A const_strict_lock_ptr <>.`

Throws:

  Nothing.

###### `synchronize()`

    strict_lock_ptr<T,Lockable> synchronize();

The synchronize() factory make easier to lock on a scope. As discussed, `operator->` can only lock over the duration of a call, so it is insufficient for complex operations. With `synchronize()` you get to lock the object in a scoped and to directly access the object inside that scope.

Example:

    void fun(synchronized_value<vector<int>> & vec) {
      auto vec2=vec.synchronize();
      vec2.push_back(42);
      assert(vec2.back() == 42);
    }

Return:

  `A strict_lock_ptr <>.`

Throws:

  Nothing.

###### `synchronize() const`

    const_strict_lock_ptr<T,Lockable> synchronize() const;

Return:

  `A const_strict_lock_ptr <>.`

Throws:

  Nothing.

###### `operator*()`

    deref_value operator*();;

Return:

  `A an instance of a class that locks the mutex on construction and unlocks it on destruction and provides implicit conversion to a reference to the protected value.`

Throws:

  Nothing.

###### `operator*() const`

    const_deref_value operator*() const;

Return:

  `A an instance of a class that locks the mutex on construction and unlocks it on destruction and provides implicit conversion to a constant reference to the protected value.`

Throws:

  Nothing.

##### Non-Member Function `synchronize`

    #include <boost/thread/synchronized_value.hpp>
    namespace boost
    {
    #if ! defined(BOOST_THREAD_NO_SYNCHRONIZE)
      template <typename ...SV>
      std::tuple<typename synchronized_value_strict_lock_ptr<SV>::type ...> synchronize(SV& ...sv);
    #endif
    }