folly::Tearable< T > Class Template Reference

#include <Tearable.h>

Classes
struct	AtomicWord
union	RawWord

Public Member Functions
	Tearable ()=default
	Tearable (const T &val)
void	load (T &dst) const
void	store (const T &val)

Private Attributes
AtomicWord	data_ [kNumDataWords]

Static Private Attributes
static const std::size_t	kNumDataWords

Detailed Description

template<typename T>
class folly::Tearable< T >

This class allows you to perform torn loads and stores on the bits of a trivially-copyable type T without triggering undefined behavior. You may encounter corrupt data, but should not encounter nasal demons.

This class provides no atomicity or memory ordering. Loads and stores are expected often to be data races. Synchronization is expected to be provided externally, and this class is helpful in building higher-level optimistic concurrency tools in combination with externally-provided synchronization.

To see why this is useful, consider the guarantees provided by std::atomic<T>. It ensures that every load returns a T that was stored in the atomic. If T is too large to be read/written with a single load/store instruction, std::atomic<T> falls back to locking to provide this guarantee. Users pay this cost even if they have some higher-level mechanism (an external lock, version numbers, other application-level reasoning) that makes them resilient to torn reads. Tearable<T> allows concurrent access without these costs.

For types smaller than the processor word size, prefer std::atomic<T>.

Definition at line 48 of file Tearable.h.

Constructor & Destructor Documentation

template<typename T>

folly::Tearable< T >::Tearable ( )

default

template<typename T>

folly::Tearable< T >::Tearable ( const T &  val )

inline

Definition at line 58 of file Tearable.h.

References folly::Tearable< T >::store().

                         : Tearable() {
    store(val);
  }

Member Function Documentation

template<typename T>

void folly::Tearable< T >::load ( T &  dst ) const

inline

Definition at line 65 of file Tearable.h.

References folly::Tearable< T >::data_, i, folly::Tearable< T >::kNumDataWords, and folly::T.

                          {
    RawWord newDst[kNumDataWords];

    for (std::size_t i = 0; i < kNumDataWords; ++i) {
      newDst[i] = data_[i].load(std::memory_order_relaxed);
    }
    std::memcpy(&dst, newDst, sizeof(T));
  }

template<typename T>

void folly::Tearable< T >::store ( const T &  val )

inline

Definition at line 74 of file Tearable.h.

References folly::Tearable< T >::data_, i, folly::Tearable< T >::kNumDataWords, and folly::T.

Referenced by folly::Tearable< T >::Tearable().

                           {
    RawWord newData[kNumDataWords];
    std::memcpy(newData, &val, sizeof(T));

    for (std::size_t i = 0; i < kNumDataWords; ++i) {
      data_[i].store(newData[i], std::memory_order_relaxed);
    }
  }

Member Data Documentation

template<typename T>

AtomicWord folly::Tearable< T >::data_[kNumDataWords]

private

Definition at line 98 of file Tearable.h.

Referenced by folly::Tearable< T >::load(), and folly::Tearable< T >::store().

template<typename T>

const std::size_t folly::Tearable< T >::kNumDataWords

staticprivate

Initial value:

=
      (sizeof(T) + sizeof(RawWord) - 1) / sizeof(RawWord)

Definition at line 95 of file Tearable.h.

Referenced by folly::Tearable< T >::load(), and folly::Tearable< T >::store().

---

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

• proxygen/folly/folly/synchronization/Tearable.h