folly/ThreadLocal.h

   1 /*
   2  * Copyright 2016 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * Improved thread local storage for non-trivial types (similar speed as
  19  * pthread_getspecific but only consumes a single pthread_key_t, and 4x faster
  20  * than boost::thread_specific_ptr).
  21  *
  22  * Also includes an accessor interface to walk all the thread local child
  23  * objects of a parent.  accessAllThreads() initializes an accessor which holds
  24  * a global lock *that blocks all creation and destruction of ThreadLocal
  25  * objects with the same Tag* and can be used as an iterable container.
  26  *
  27  * Intended use is for frequent write, infrequent read data access patterns such
  28  * as counters.
  29  *
  30  * There are two classes here - ThreadLocal and ThreadLocalPtr.  ThreadLocalPtr
  31  * has semantics similar to boost::thread_specific_ptr. ThreadLocal is a thin
  32  * wrapper around ThreadLocalPtr that manages allocation automatically.
  33  *
  34  * @author Spencer Ahrens (sahrens)
  35  */
  36
  37 #pragma once
  38
  39 #include <folly/Portability.h>
  40 #include <boost/iterator/iterator_facade.hpp>
  41 #include <folly/Likely.h>
  42 #include <type_traits>
  43
  44
  45 namespace folly {
  46 enum class TLPDestructionMode {
  47   THIS_THREAD,
  48   ALL_THREADS
  49 };
  50 }  // namespace
  51
  52 #include <folly/detail/ThreadLocalDetail.h>
  53
  54 namespace folly {
  55
  56 template<class T, class Tag> class ThreadLocalPtr;
  57
  58 template<class T, class Tag=void>
  59 class ThreadLocal {
  60  public:
  61   constexpr ThreadLocal() : constructor_([]() {
  62       return new T();
  63     }) {}
  64
  65   explicit ThreadLocal(std::function<T*()> constructor) :
  66       constructor_(constructor) {
  67   }
  68
  69   T* get() const {
  70     T* ptr = tlp_.get();
  71     if (LIKELY(ptr != nullptr)) {
  72       return ptr;
  73     }
  74
  75     // separated new item creation out to speed up the fast path.
  76     return makeTlp();
  77   }
  78
  79   T* operator->() const {
  80     return get();
  81   }
  82
  83   T& operator*() const {
  84     return *get();
  85   }
  86
  87   void reset(T* newPtr = nullptr) {
  88     tlp_.reset(newPtr);
  89   }
  90
  91   typedef typename ThreadLocalPtr<T,Tag>::Accessor Accessor;
  92   Accessor accessAllThreads() const {
  93     return tlp_.accessAllThreads();
  94   }
  95
  96   // movable
  97   ThreadLocal(ThreadLocal&&) = default;
  98   ThreadLocal& operator=(ThreadLocal&&) = default;
  99
 100  private:
 101   // non-copyable
 102   ThreadLocal(const ThreadLocal&) = delete;
 103   ThreadLocal& operator=(const ThreadLocal&) = delete;
 104
 105   T* makeTlp() const {
 106     auto ptr = constructor_();
 107     tlp_.reset(ptr);
 108     return ptr;
 109   }
 110
 111   mutable ThreadLocalPtr<T,Tag> tlp_;
 112   std::function<T*()> constructor_;
 113 };
 114
 115 /*
 116  * The idea here is that __thread is faster than pthread_getspecific, so we
 117  * keep a __thread array of pointers to objects (ThreadEntry::elements) where
 118  * each array has an index for each unique instance of the ThreadLocalPtr
 119  * object.  Each ThreadLocalPtr object has a unique id that is an index into
 120  * these arrays so we can fetch the correct object from thread local storage
 121  * very efficiently.
 122  *
 123  * In order to prevent unbounded growth of the id space and thus huge
 124  * ThreadEntry::elements, arrays, for example due to continuous creation and
 125  * destruction of ThreadLocalPtr objects, we keep a set of all active
 126  * instances.  When an instance is destroyed we remove it from the active
 127  * set and insert the id into freeIds_ for reuse.  These operations require a
 128  * global mutex, but only happen at construction and destruction time.
 129  *
 130  * We use a single global pthread_key_t per Tag to manage object destruction and
 131  * memory cleanup upon thread exit because there is a finite number of
 132  * pthread_key_t's available per machine.
 133  *
 134  * NOTE: Apple platforms don't support the same semantics for __thread that
 135  *       Linux does (and it's only supported at all on i386). For these, use
 136  *       pthread_setspecific()/pthread_getspecific() for the per-thread
 137  *       storage.  Windows (MSVC and GCC) does support the same semantics
 138  *       with __declspec(thread)
 139  */
 140
 141 template<class T, class Tag=void>
 142 class ThreadLocalPtr {
 143  private:
 144   typedef threadlocal_detail::StaticMeta<Tag> StaticMeta;
 145  public:
 146   constexpr ThreadLocalPtr() : id_() {}
 147
 148   ThreadLocalPtr(ThreadLocalPtr&& other) noexcept :
 149     id_(std::move(other.id_)) {
 150   }
 151
 152   ThreadLocalPtr& operator=(ThreadLocalPtr&& other) {
 153     assert(this != &other);
 154     destroy();
 155     id_ = std::move(other.id_);
 156     return *this;
 157   }
 158
 159   ~ThreadLocalPtr() {
 160     destroy();
 161   }
 162
 163   T* get() const {
 164     threadlocal_detail::ElementWrapper& w = StaticMeta::instance().get(&id_);
 165     return static_cast<T*>(w.ptr);
 166   }
 167
 168   T* operator->() const {
 169     return get();
 170   }
 171
 172   T& operator*() const {
 173     return *get();
 174   }
 175
 176   T* release() {
 177     threadlocal_detail::ElementWrapper& w = StaticMeta::instance().get(&id_);
 178
 179     return static_cast<T*>(w.release());
 180   }
 181
 182   void reset(T* newPtr = nullptr) {
 183     threadlocal_detail::ElementWrapper& w = StaticMeta::instance().get(&id_);
 184
 185     if (w.ptr != newPtr) {
 186       w.dispose(TLPDestructionMode::THIS_THREAD);
 187       w.set(newPtr);
 188     }
 189   }
 190
 191   explicit operator bool() const {
 192     return get() != nullptr;
 193   }
 194
 195   /**
 196    * reset() with a custom deleter:
 197    * deleter(T* ptr, TLPDestructionMode mode)
 198    * "mode" is ALL_THREADS if we're destructing this ThreadLocalPtr (and thus
 199    * deleting pointers for all threads), and THIS_THREAD if we're only deleting
 200    * the member for one thread (because of thread exit or reset())
 201    */
 202   template <class Deleter>
 203   void reset(T* newPtr, Deleter deleter) {
 204     threadlocal_detail::ElementWrapper& w = StaticMeta::instance().get(&id_);
 205     if (w.ptr != newPtr) {
 206       w.dispose(TLPDestructionMode::THIS_THREAD);
 207       w.set(newPtr, deleter);
 208     }
 209   }
 210
 211   // Holds a global lock for iteration through all thread local child objects.
 212   // Can be used as an iterable container.
 213   // Use accessAllThreads() to obtain one.
 214   class Accessor {
 215     friend class ThreadLocalPtr<T,Tag>;
 216
 217     threadlocal_detail::StaticMetaBase& meta_;
 218     std::mutex* lock_;
 219     uint32_t id_;
 220
 221    public:
 222     class Iterator;
 223     friend class Iterator;
 224
 225     // The iterators obtained from Accessor are bidirectional iterators.
 226     class Iterator : public boost::iterator_facade<
 227           Iterator,                               // Derived
 228           T,                                      // value_type
 229           boost::bidirectional_traversal_tag> {   // traversal
 230       friend class Accessor;
 231       friend class boost::iterator_core_access;
 232       const Accessor* accessor_;
 233       threadlocal_detail::ThreadEntry* e_;
 234
 235       void increment() {
 236         e_ = e_->next;
 237         incrementToValid();
 238       }
 239
 240       void decrement() {
 241         e_ = e_->prev;
 242         decrementToValid();
 243       }
 244
 245       T& dereference() const {
 246         return *static_cast<T*>(e_->elements[accessor_->id_].ptr);
 247       }
 248
 249       bool equal(const Iterator& other) const {
 250         return (accessor_->id_ == other.accessor_->id_ &&
 251                 e_ == other.e_);
 252       }
 253
 254       explicit Iterator(const Accessor* accessor)
 255         : accessor_(accessor),
 256           e_(&accessor_->meta_.head_) {
 257       }
 258
 259       bool valid() const {
 260         return (e_->elements &&
 261                 accessor_->id_ < e_->elementsCapacity &&
 262                 e_->elements[accessor_->id_].ptr);
 263       }
 264
 265       void incrementToValid() {
 266         for (; e_ != &accessor_->meta_.head_ && !valid(); e_ = e_->next) { }
 267       }
 268
 269       void decrementToValid() {
 270         for (; e_ != &accessor_->meta_.head_ && !valid(); e_ = e_->prev) { }
 271       }
 272     };
 273
 274     ~Accessor() {
 275       release();
 276     }
 277
 278     Iterator begin() const {
 279       return ++Iterator(this);
 280     }
 281
 282     Iterator end() const {
 283       return Iterator(this);
 284     }
 285
 286     Accessor(const Accessor&) = delete;
 287     Accessor& operator=(const Accessor&) = delete;
 288
 289     Accessor(Accessor&& other) noexcept
 290       : meta_(other.meta_),
 291         lock_(other.lock_),
 292         id_(other.id_) {
 293       other.id_ = 0;
 294       other.lock_ = nullptr;
 295     }
 296
 297     Accessor& operator=(Accessor&& other) noexcept {
 298       // Each Tag has its own unique meta, and accessors with different Tags
 299       // have different types.  So either *this is empty, or this and other
 300       // have the same tag.  But if they have the same tag, they have the same
 301       // meta (and lock), so they'd both hold the lock at the same time,
 302       // which is impossible, which leaves only one possible scenario --
 303       // *this is empty.  Assert it.
 304       assert(&meta_ == &other.meta_);
 305       assert(lock_ == nullptr);
 306       using std::swap;
 307       swap(lock_, other.lock_);
 308       swap(id_, other.id_);
 309     }
 310
 311     Accessor()
 312       : meta_(threadlocal_detail::StaticMeta<Tag>::instance()),
 313         lock_(nullptr),
 314         id_(0) {
 315     }
 316
 317    private:
 318     explicit Accessor(uint32_t id)
 319       : meta_(threadlocal_detail::StaticMeta<Tag>::instance()),
 320         lock_(&meta_.lock_) {
 321       lock_->lock();
 322       id_ = id;
 323     }
 324
 325     void release() {
 326       if (lock_) {
 327         lock_->unlock();
 328         id_ = 0;
 329         lock_ = nullptr;
 330       }
 331     }
 332   };
 333
 334   // accessor allows a client to iterate through all thread local child
 335   // elements of this ThreadLocal instance.  Holds a global lock for each <Tag>
 336   Accessor accessAllThreads() const {
 337     static_assert(!std::is_same<Tag, void>::value,
 338                   "Must use a unique Tag to use the accessAllThreads feature");
 339     return Accessor(id_.getOrAllocate(StaticMeta::instance()));
 340   }
 341
 342  private:
 343   void destroy() {
 344     StaticMeta::instance().destroy(&id_);
 345   }
 346
 347   // non-copyable
 348   ThreadLocalPtr(const ThreadLocalPtr&) = delete;
 349   ThreadLocalPtr& operator=(const ThreadLocalPtr&) = delete;
 350
 351   mutable typename StaticMeta::EntryID id_;
 352 };
 353
 354 }  // namespace folly