folly::Synchronized< T, Mutex > Struct Template Reference

#include <Synchronized.h>

Inheritance diagram for folly::Synchronized< T, Mutex >:

Public Types
using	LockedPtr = typename Base::LockedPtr
using	ConstLockedPtr = typename Base::ConstLockedPtr
using	DataType = T
using	MutexType = Mutex

Public Member Functions
	Synchronized ()=default
	Synchronized (typename std::conditional< std::is_copy_constructible< T >::value, const Synchronized &, NonImplementedType >::type rhs)
	Synchronized (Synchronized &&rhs) noexcept(nxMoveCtor)
	Synchronized (const T &rhs) noexcept(nxCopyCtor)
	Synchronized (T &&rhs) noexcept(nxMoveCtor)
template<typename... Args>
	Synchronized (in_place_t, Args &&...args)
template<typename... DatumArgs, typename... MutexArgs>
	Synchronized (std::piecewise_construct_t, std::tuple< DatumArgs... > datumArgs, std::tuple< MutexArgs... > mutexArgs)
Synchronized &	operator= (typename std::conditional< std::is_copy_constructible< T >::value &&std::is_move_assignable< T >::value, const Synchronized &, NonImplementedType >::type rhs)
Synchronized &	operator= (Synchronized &&rhs)
Synchronized &	operator= (const T &rhs)
Synchronized &	operator= (T &&rhs)
LockedPtr	contextualLock ()
ConstLockedPtr	contextualLock () const
template<class Rep , class Period >
LockedPtr	contextualLock (const std::chrono::duration< Rep, Period > &timeout)
template<class Rep , class Period >
ConstLockedPtr	contextualLock (const std::chrono::duration< Rep, Period > &timeout) const
ConstLockedPtr	contextualRLock () const
template<class Rep , class Period >
ConstLockedPtr	contextualRLock (const std::chrono::duration< Rep, Period > &timeout) const
LockedPtr	operator-> ()
ConstLockedPtr	operator-> () const
LockedPtr	timedAcquire (unsigned int milliseconds)
ConstLockedPtr	timedAcquire (unsigned int milliseconds) const
void	swap (Synchronized &rhs)
void	swap (T &rhs)
T	exchange (T &&rhs)
void	copy (T *target) const
T	copy () const

Private Types
using	Base = SynchronizedBase< Synchronized< T, Mutex >, MutexLevelValue< Mutex >::value >

Private Member Functions
	Synchronized (const Synchronized &rhs, const ConstLockedPtr &) noexcept(nxCopyCtor)
	Synchronized (Synchronized &&rhs, const LockedPtr &) noexcept(nxMoveCtor)
template<typename... DatumArgs, typename... MutexArgs, std::size_t... IndicesOne, std::size_t... IndicesTwo>
	Synchronized (std::piecewise_construct_t, std::tuple< DatumArgs... > datumArgs, std::tuple< MutexArgs... > mutexArgs, index_sequence< IndicesOne... >, index_sequence< IndicesTwo... >)

Private Attributes
T	datum_
Mutex	mutex_

Static Private Attributes
static constexpr bool	nxCopyCtor
static constexpr bool	nxMoveCtor

Friends
template<class LockedType , class MutexType , class LockPolicy >
class	folly::LockedPtrBase
template<class LockedType , class LockPolicy >
class	folly::LockedPtr

Detailed Description

template<class T, class Mutex = SharedMutex>
struct folly::Synchronized< T, Mutex >

Synchronized<T> encapsulates an object of type T (a "datum") paired with a mutex. The only way to access the datum is while the mutex is locked, and Synchronized makes it virtually impossible to do otherwise. The code that would access the datum in unsafe ways would look odd and convoluted, thus readily alerting the human reviewer. In contrast, the code that uses Synchronized<T> correctly looks simple and intuitive.

The second parameter must be a mutex type. Any mutex type supported by LockTraits<Mutex> can be used. By default any class with lock() and unlock() methods will work automatically. LockTraits can be specialized to teach Synchronized how to use other custom mutex types. See the documentation in LockTraits.h for additional details.

Supported mutexes that work by default include std::mutex, std::recursive_mutex, std::timed_mutex, std::recursive_timed_mutex, folly::SharedMutex, folly::RWSpinLock, and folly::SpinLock. Include LockTraitsBoost.h to get additional LockTraits specializations to support the following boost mutex types: boost::mutex, boost::recursive_mutex, boost::shared_mutex, boost::timed_mutex, and boost::recursive_timed_mutex.

Definition at line 438 of file Synchronized.h.

Member Typedef Documentation

template<class T, class Mutex = SharedMutex>

using folly::Synchronized< T, Mutex >::Base = SynchronizedBase<Synchronized<T, Mutex>, MutexLevelValue<Mutex>::value>

private

Definition at line 443 of file Synchronized.h.

template<class T, class Mutex = SharedMutex>

using folly::Synchronized< T, Mutex >::ConstLockedPtr = typename Base::ConstLockedPtr

Definition at line 454 of file Synchronized.h.

template<class T, class Mutex = SharedMutex>

using folly::Synchronized< T, Mutex >::DataType = T

Definition at line 455 of file Synchronized.h.

template<class T, class Mutex = SharedMutex>

using folly::Synchronized< T, Mutex >::LockedPtr = typename Base::LockedPtr

Definition at line 453 of file Synchronized.h.

template<class T, class Mutex = SharedMutex>

using folly::Synchronized< T, Mutex >::MutexType = Mutex

Definition at line 456 of file Synchronized.h.

Constructor & Destructor Documentation

template<class T, class Mutex = SharedMutex>

folly::Synchronized< T, Mutex >::Synchronized ( )

default

Default constructor leaves both members call their own default constructor.

template<class T, class Mutex = SharedMutex>

folly::Synchronized< T, Mutex >::Synchronized ( typename std::conditional< std::is_copy_constructible< T >::value, const Synchronized< T, Mutex > &, NonImplementedType >::type  rhs )

inline

Copy constructor; deprecated

Enabled only when the data type is copy-constructible.

Takes a shared-or-exclusive lock on the source mutex while performing the copy-construction of the destination data from the source data. No lock is taken on the destination mutex.

May throw even when the data type is is nothrow-copy-constructible because acquiring a lock may throw.

Definition at line 477 of file Synchronized.h.

      : Synchronized(rhs.copy()) {}

template<class T, class Mutex = SharedMutex>

folly::Synchronized< T, Mutex >::Synchronized ( Synchronized< T, Mutex > &&  rhs )

inlinenoexcept

Move constructor; deprecated

Move-constructs from the source data without locking either the source or the destination mutex.

Semantically, assumes that the source object is a true rvalue and therefore that no synchronization is required for accessing it.

Definition at line 492 of file Synchronized.h.

      : Synchronized(std::move(rhs.datum_)) {}

template<class T, class Mutex = SharedMutex>

folly::Synchronized< T, Mutex >::Synchronized ( const T &  rhs )

inlineexplicitnoexcept

Constructor taking a datum as argument copies it. There is no need to lock the constructing object.

Definition at line 499 of file Synchronized.h.

: datum_(rhs) {}

template<class T, class Mutex = SharedMutex>

folly::Synchronized< T, Mutex >::Synchronized ( T &&  rhs )

inlineexplicitnoexcept

Constructor taking a datum rvalue as argument moves it. Again, there is no need to lock the constructing object.

Definition at line 505 of file Synchronized.h.

      : datum_(std::move(rhs)) {}

template<class T, class Mutex = SharedMutex>

template<typename... Args>

folly::Synchronized< T, Mutex >::Synchronized ( in_place_t  , Args &&...  args  )

inlineexplicit

Lets you construct non-movable types in-place. Use the constexpr instance in_place as the first argument.

Definition at line 513 of file Synchronized.h.

      : datum_(std::forward<Args>(args)...) {}

template<class T, class Mutex = SharedMutex>

template<typename... DatumArgs, typename... MutexArgs>

folly::Synchronized< T, Mutex >::Synchronized ( std::piecewise_construct_t  , std::tuple< DatumArgs... >  datumArgs, std::tuple< MutexArgs... >  mutexArgs  )

inline

Lets you construct the synchronized object and also pass construction parameters to the underlying mutex if desired

Definition at line 521 of file Synchronized.h.

      : Synchronized{std::piecewise_construct,
                     std::move(datumArgs),
                     std::move(mutexArgs),
                     make_index_sequence<sizeof...(DatumArgs)>{},
                     make_index_sequence<sizeof...(MutexArgs)>{}} {}

template<class T, class Mutex = SharedMutex>

folly::Synchronized< T, Mutex >::Synchronized ( const Synchronized< T, Mutex > &  rhs, const ConstLockedPtr &    )

inlineprivatenoexcept

Helper constructors to enable Synchronized for non-default constructible types T. Guards are created in actual public constructors and are alive for the time required to construct the object

Definition at line 746 of file Synchronized.h.

      : datum_(rhs.datum_) {}

template<class T, class Mutex = SharedMutex>

folly::Synchronized< T, Mutex >::Synchronized ( Synchronized< T, Mutex > &&  rhs, const LockedPtr &    )

inlineprivatenoexcept

Definition at line 751 of file Synchronized.h.

      : datum_(std::move(rhs.datum_)) {}

template<class T, class Mutex = SharedMutex>

template<typename... DatumArgs, typename... MutexArgs, std::size_t... IndicesOne, std::size_t... IndicesTwo>

folly::Synchronized< T, Mutex >::Synchronized ( std::piecewise_construct_t  , std::tuple< DatumArgs... >  datumArgs, std::tuple< MutexArgs... >  mutexArgs, index_sequence< IndicesOne... >  , index_sequence< IndicesTwo... >    )

inlineprivate

Definition at line 760 of file Synchronized.h.

      : datum_{std::get<IndicesOne>(std::move(datumArgs))...},
        mutex_{std::get<IndicesTwo>(std::move(mutexArgs))...} {}

Member Function Documentation

template<class T, class Mutex = SharedMutex>

LockedPtr folly::Synchronized< T, Mutex >::contextualLock ( )

inline

Acquire an appropriate lock based on the context.

If the mutex is a shared mutex, and the Synchronized instance is const, this acquires a shared lock. Otherwise this acquires an exclusive lock.

In general, prefer using the explicit rlock() and wlock() methods for read-write locks, and lock() for purely exclusive locks.

contextualLock() is primarily intended for use in other template functions that do not necessarily know the lock type.

Definition at line 601 of file Synchronized.h.

Referenced by folly::sync_tests::testBasicImpl(), folly::sync_tests::testConcurrency(), folly::sync_tests::testTimed(), folly::sync_tests::testTimedShared(), folly::sync_tests::testTimedSynchronized(), and folly::sync_tests::testTimedSynchronizedWithConst().

                             {
    return LockedPtr(this);
  }

template<class T, class Mutex = SharedMutex>

ConstLockedPtr folly::Synchronized< T, Mutex >::contextualLock ( ) const

inline

Definition at line 604 of file Synchronized.h.

                                        {
    return ConstLockedPtr(this);
  }

template<class T, class Mutex = SharedMutex>

template<class Rep , class Period >

LockedPtr folly::Synchronized< T, Mutex >::contextualLock ( const std::chrono::duration< Rep, Period > &  timeout )

inline

Definition at line 608 of file Synchronized.h.

                                                                          {
    return LockedPtr(this, timeout);
  }

template<class T, class Mutex = SharedMutex>

template<class Rep , class Period >

ConstLockedPtr folly::Synchronized< T, Mutex >::contextualLock ( const std::chrono::duration< Rep, Period > &  timeout ) const

inline

Definition at line 612 of file Synchronized.h.

                                                           {
    return ConstLockedPtr(this, timeout);
  }

template<class T, class Mutex = SharedMutex>

ConstLockedPtr folly::Synchronized< T, Mutex >::contextualRLock ( ) const

inline

contextualRLock() acquires a read lock if the mutex type is shared, or a regular exclusive lock for non-shared mutex types.

contextualRLock() when you know that you prefer a read lock (if available), even if the Synchronized<T> object itself is non-const.

Definition at line 623 of file Synchronized.h.

Referenced by folly::sync_tests::testTimed(), folly::sync_tests::testTimedShared(), folly::sync_tests::testTimedSynchronized(), and folly::sync_tests::testTimedSynchronizedWithConst().

                                         {
    return ConstLockedPtr(this);
  }

template<class T, class Mutex = SharedMutex>

template<class Rep , class Period >

ConstLockedPtr folly::Synchronized< T, Mutex >::contextualRLock ( const std::chrono::duration< Rep, Period > &  timeout ) const

inline

Definition at line 627 of file Synchronized.h.

                                                           {
    return ConstLockedPtr(this, timeout);
  }

template<class T, class Mutex = SharedMutex>

void folly::Synchronized< T, Mutex >::copy ( T *  target ) const

inline

Copies datum to a given target.

Definition at line 721 of file Synchronized.h.

Referenced by folly::observer::detail::ObserverCreatorContext< Observable, Traits >::get(), folly::Synchronized< std::vector< detail::folly::detail::TypeDescriptor >, folly::SharedMutexImpl >::operator=(), folly::observer_detail::Core::refresh(), folly::sync_tests::testConstCopy(), folly::sync_tests::testExchange(), and folly::observer::detail::ObserverCreatorContext< Observable, Traits >::~ObserverCreatorContext().

                             {
    ConstLockedPtr guard(this);
    *target = datum_;
  }

template<class T, class Mutex = SharedMutex>

T folly::Synchronized< T, Mutex >::copy ( ) const

inline

Returns a fresh copy of the datum.

Definition at line 729 of file Synchronized.h.

                 {
    ConstLockedPtr guard(this);
    return datum_;
  }

template<class T, class Mutex = SharedMutex>

T folly::Synchronized< T, Mutex >::exchange ( T &&  rhs )

inline

Assign another datum and return the original value. Recommended because it keeps the mutex held only briefly.

Definition at line 713 of file Synchronized.h.

Referenced by folly::sync_tests::testExchange().

                      {
    swap(rhs);
    return std::move(rhs);
  }

template<class T, class Mutex = SharedMutex>

LockedPtr folly::Synchronized< T, Mutex >::operator-> ( )

inline

This accessor offers a LockedPtr. In turn, LockedPtr offers operator-> returning a pointer to T. The operator-> keeps expanding until it reaches a pointer, so syncobj->foo() will lock the object and call foo() against it.

NOTE: This API is planned to be deprecated in an upcoming diff. Prefer using lock(), wlock(), or rlock() instead.

Definition at line 641 of file Synchronized.h.

                         {
    return LockedPtr(this);
  }

template<class T, class Mutex = SharedMutex>

ConstLockedPtr folly::Synchronized< T, Mutex >::operator-> ( ) const

inline

Obtain a ConstLockedPtr.

NOTE: This API is planned to be deprecated in an upcoming diff. Prefer using lock(), wlock(), or rlock() instead.

Definition at line 651 of file Synchronized.h.

                                    {
    return ConstLockedPtr(this);
  }

template<class T, class Mutex = SharedMutex>

Synchronized& folly::Synchronized< T, Mutex >::operator= ( typename std::conditional< std::is_copy_constructible< T >::value &&std::is_move_assignable< T >::value, const Synchronized< T, Mutex > &, NonImplementedType >::type  rhs )

inline

Copy assignment operator; deprecated

Enabled only when the data type is copy-constructible and move-assignable.

Move-assigns from a copy of the source data.

Takes a shared-or-exclusive lock on the source mutex while copying the source data to a temporary. Takes an exclusive lock on the destination mutex while move-assigning from the temporary.

This technique consts an extra temporary but avoids the need to take locks on both mutexes together.

Definition at line 545 of file Synchronized.h.

                                                       {
    return *this = rhs.copy();
  }

template<class T, class Mutex = SharedMutex>

Synchronized& folly::Synchronized< T, Mutex >::operator= ( Synchronized< T, Mutex > &&  rhs )

inline

Move assignment operator; deprecated

Takes an exclusive lock on the destination mutex while move-assigning the destination data from the source data. The source mutex is not locked or otherwise accessed.

Semantically, assumes that the source object is a true rvalue and therefore that no synchronization is required for accessing it.

Definition at line 563 of file Synchronized.h.

                                              {
    return *this = std::move(rhs.datum_);
  }

template<class T, class Mutex = SharedMutex>

Synchronized& folly::Synchronized< T, Mutex >::operator= ( const T &  rhs )

inline

Lock object, assign datum.

Definition at line 570 of file Synchronized.h.

                                        {
    if (&datum_ != &rhs) {
      auto guard = operator->();
      datum_ = rhs;
    }
    return *this;
  }

template<class T, class Mutex = SharedMutex>

Synchronized& folly::Synchronized< T, Mutex >::operator= ( T &&  rhs )

inline

Lock object, move-assign datum.

Definition at line 581 of file Synchronized.h.

                                   {
    if (&datum_ != &rhs) {
      auto guard = operator->();
      datum_ = std::move(rhs);
    }
    return *this;
  }

template<class T, class Mutex = SharedMutex>

void folly::Synchronized< T, Mutex >::swap ( Synchronized< T, Mutex > &  rhs )

inline

Swaps with another Synchronized. Protected against self-swap. Only data is swapped. Locks are acquired in increasing address order.

Definition at line 684 of file Synchronized.h.

Referenced by folly::VirtualEventBase::destroyImpl(), folly::LoggerDB::finishConfigUpdate(), folly::Synchronized< std::vector< detail::folly::detail::TypeDescriptor >, folly::SharedMutexImpl >::swap(), folly::swap(), folly::sync_tests::testAcquireLocked(), folly::sync_tests::testAcquireLockedWithConst(), folly::sync_tests::testConcurrency(), folly::sync_tests::testDualLocking(), folly::sync_tests::testDualLockingWithConst(), folly::sync_tests::testTimed(), folly::sync_tests::testTimedShared(), folly::sync_tests::testTimedSynchronized(), folly::sync_tests::testTimedSynchronizedWithConst(), and folly::observer::detail::ObserverCreatorContext< Observable, Traits >::updateValue().

                               {
    if (this == &rhs) {
      return;
    }
    if (this > &rhs) {
      return rhs.swap(*this);
    }
    auto guard1 = operator->();
    auto guard2 = rhs.operator->();

    using std::swap;
    swap(datum_, rhs.datum_);
  }

template<class T, class Mutex = SharedMutex>

void folly::Synchronized< T, Mutex >::swap ( T &  rhs )

inline

Swap with another datum. Recommended because it keeps the mutex held only briefly.

Definition at line 702 of file Synchronized.h.

                    {
    LockedPtr guard(this);

    using std::swap;
    swap(datum_, rhs);
  }

template<class T, class Mutex = SharedMutex>

LockedPtr folly::Synchronized< T, Mutex >::timedAcquire ( unsigned int  milliseconds )

inline

Attempts to acquire for a given number of milliseconds. If acquisition is unsuccessful, the returned LockedPtr is nullptr.

NOTE: This API is deprecated. Use lock(), wlock(), or rlock() instead. In the future it will be marked with a deprecation attribute to emit build-time warnings, and then it will be removed entirely.

Definition at line 663 of file Synchronized.h.

                                                    {
    return LockedPtr(this, std::chrono::milliseconds(milliseconds));
  }

template<class T, class Mutex = SharedMutex>

ConstLockedPtr folly::Synchronized< T, Mutex >::timedAcquire ( unsigned int  milliseconds ) const

inline

Attempts to acquire for a given number of milliseconds. If acquisition is unsuccessful, the returned ConstLockedPtr is nullptr.

NOTE: This API is deprecated. Use lock(), wlock(), or rlock() instead. In the future it will be marked with a deprecation attribute to emit build-time warnings, and then it will be removed entirely.

Definition at line 675 of file Synchronized.h.

                                                               {
    return ConstLockedPtr(this, std::chrono::milliseconds(milliseconds));
  }

Friends And Related Function Documentation

template<class T, class Mutex = SharedMutex>

template<class LockedType , class LockPolicy >

friend class folly::LockedPtr

friend

Definition at line 738 of file Synchronized.h.

template<class T, class Mutex = SharedMutex>

template<class LockedType , class MutexType , class LockPolicy >

friend class folly::LockedPtrBase

friend

Definition at line 736 of file Synchronized.h.

Member Data Documentation

template<class T, class Mutex = SharedMutex>

T folly::Synchronized< T, Mutex >::datum_

private

Definition at line 770 of file Synchronized.h.

Referenced by folly::Synchronized< std::vector< detail::folly::detail::TypeDescriptor >, folly::SharedMutexImpl >::swap().

template<class T, class Mutex = SharedMutex>

Mutex folly::Synchronized< T, Mutex >::mutex_

mutableprivate

Definition at line 771 of file Synchronized.h.

template<class T, class Mutex = SharedMutex>

constexpr bool folly::Synchronized< T, Mutex >::nxCopyCtor

staticprivate

Initial value:

{
      std::is_nothrow_copy_constructible<T>::value}

Definition at line 444 of file Synchronized.h.

template<class T, class Mutex = SharedMutex>

constexpr bool folly::Synchronized< T, Mutex >::nxMoveCtor

staticprivate

Initial value:

{
      std::is_nothrow_move_constructible<T>::value}

Definition at line 446 of file Synchronized.h.

---

The documentation for this struct was generated from the following file:

• proxygen/folly/folly/Synchronized.h