2 * Copyright 2013 Facebook, Inc.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
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).
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.
27 * Intended use is for frequent write, infrequent read data access patterns such
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.
34 * @author Spencer Ahrens (sahrens)
37 #ifndef FOLLY_THREADLOCAL_H_
38 #define FOLLY_THREADLOCAL_H_
40 #include "folly/Portability.h"
41 #include <boost/iterator/iterator_facade.hpp>
42 #include "folly/Likely.h"
43 #include <type_traits>
45 // Use noexcept on gcc 4.6 or higher
48 # ifdef HAVE_FEATURES_H
49 # include <features.h>
50 # if __GNUC_PREREQ(4,6)
51 # define FOLLY_NOEXCEPT noexcept
52 # define FOLLY_ASSERT(x) x
57 #ifndef FOLLY_NOEXCEPT
58 # define FOLLY_NOEXCEPT
59 # define FOLLY_ASSERT(x) /**/
63 enum class TLPDestructionMode {
69 #include "folly/detail/ThreadLocalDetail.h"
73 template<class T, class Tag> class ThreadLocalPtr;
75 template<class T, class Tag=void>
82 if (LIKELY(ptr != nullptr)) {
86 // separated new item creation out to speed up the fast path.
90 T* operator->() const {
94 T& operator*() const {
98 void reset(T* newPtr = nullptr) {
102 typedef typename ThreadLocalPtr<T,Tag>::Accessor Accessor;
103 Accessor accessAllThreads() const {
104 return tlp_.accessAllThreads();
108 ThreadLocal(ThreadLocal&&) = default;
109 ThreadLocal& operator=(ThreadLocal&&) = default;
113 ThreadLocal(const ThreadLocal&) = delete;
114 ThreadLocal& operator=(const ThreadLocal&) = delete;
122 mutable ThreadLocalPtr<T,Tag> tlp_;
126 * The idea here is that __thread is faster than pthread_getspecific, so we
127 * keep a __thread array of pointers to objects (ThreadEntry::elements) where
128 * each array has an index for each unique instance of the ThreadLocalPtr
129 * object. Each ThreadLocalPtr object has a unique id that is an index into
130 * these arrays so we can fetch the correct object from thread local storage
133 * In order to prevent unbounded growth of the id space and thus huge
134 * ThreadEntry::elements, arrays, for example due to continuous creation and
135 * destruction of ThreadLocalPtr objects, we keep a set of all active
136 * instances. When an instance is destroyed we remove it from the active
137 * set and insert the id into freeIds_ for reuse. These operations require a
138 * global mutex, but only happen at construction and destruction time.
140 * We use a single global pthread_key_t per Tag to manage object destruction and
141 * memory cleanup upon thread exit because there is a finite number of
142 * pthread_key_t's available per machine.
145 template<class T, class Tag=void>
146 class ThreadLocalPtr {
148 ThreadLocalPtr() : id_(threadlocal_detail::StaticMeta<Tag>::create()) { }
150 ThreadLocalPtr(ThreadLocalPtr&& other) : id_(other.id_) {
154 ThreadLocalPtr& operator=(ThreadLocalPtr&& other) {
155 assert(this != &other);
167 return static_cast<T*>(threadlocal_detail::StaticMeta<Tag>::get(id_).ptr);
170 T* operator->() const {
174 T& operator*() const {
178 void reset(T* newPtr = nullptr) {
179 threadlocal_detail::ElementWrapper& w =
180 threadlocal_detail::StaticMeta<Tag>::get(id_);
181 if (w.ptr != newPtr) {
182 w.dispose(TLPDestructionMode::THIS_THREAD);
187 explicit operator bool() const {
188 return get() != nullptr;
192 * reset() with a custom deleter:
193 * deleter(T* ptr, TLPDestructionMode mode)
194 * "mode" is ALL_THREADS if we're destructing this ThreadLocalPtr (and thus
195 * deleting pointers for all threads), and THIS_THREAD if we're only deleting
196 * the member for one thread (because of thread exit or reset())
198 template <class Deleter>
199 void reset(T* newPtr, Deleter deleter) {
200 threadlocal_detail::ElementWrapper& w =
201 threadlocal_detail::StaticMeta<Tag>::get(id_);
202 if (w.ptr != newPtr) {
203 w.dispose(TLPDestructionMode::THIS_THREAD);
204 w.set(newPtr, deleter);
208 // Holds a global lock for iteration through all thread local child objects.
209 // Can be used as an iterable container.
210 // Use accessAllThreads() to obtain one.
212 friend class ThreadLocalPtr<T,Tag>;
214 threadlocal_detail::StaticMeta<Tag>& meta_;
220 friend class Iterator;
222 // The iterators obtained from Accessor are bidirectional iterators.
223 class Iterator : public boost::iterator_facade<
226 boost::bidirectional_traversal_tag> { // traversal
227 friend class Accessor;
228 friend class boost::iterator_core_access;
229 const Accessor* const accessor_;
230 threadlocal_detail::ThreadEntry* e_;
242 T& dereference() const {
243 return *static_cast<T*>(e_->elements[accessor_->id_].ptr);
246 bool equal(const Iterator& other) const {
247 return (accessor_->id_ == other.accessor_->id_ &&
251 explicit Iterator(const Accessor* accessor)
252 : accessor_(accessor),
253 e_(&accessor_->meta_.head_) {
257 return (e_->elements &&
258 accessor_->id_ < e_->elementsCapacity &&
259 e_->elements[accessor_->id_].ptr);
262 void incrementToValid() {
263 for (; e_ != &accessor_->meta_.head_ && !valid(); e_ = e_->next) { }
266 void decrementToValid() {
267 for (; e_ != &accessor_->meta_.head_ && !valid(); e_ = e_->prev) { }
275 Iterator begin() const {
276 return ++Iterator(this);
279 Iterator end() const {
280 return Iterator(this);
283 Accessor(const Accessor&) = delete;
284 Accessor& operator=(const Accessor&) = delete;
286 Accessor(Accessor&& other) FOLLY_NOEXCEPT
287 : meta_(other.meta_),
291 other.lock_ = nullptr;
294 Accessor& operator=(Accessor&& other) FOLLY_NOEXCEPT {
295 // Each Tag has its own unique meta, and accessors with different Tags
296 // have different types. So either *this is empty, or this and other
297 // have the same tag. But if they have the same tag, they have the same
298 // meta (and lock), so they'd both hold the lock at the same time,
299 // which is impossible, which leaves only one possible scenario --
300 // *this is empty. Assert it.
301 assert(&meta_ == &other.meta_);
302 assert(lock_ == nullptr);
304 swap(lock_, other.lock_);
305 swap(id_, other.id_);
309 : meta_(threadlocal_detail::StaticMeta<Tag>::instance()),
315 explicit Accessor(int id)
316 : meta_(threadlocal_detail::StaticMeta<Tag>::instance()),
317 lock_(&meta_.lock_) {
331 // accessor allows a client to iterate through all thread local child
332 // elements of this ThreadLocal instance. Holds a global lock for each <Tag>
333 Accessor accessAllThreads() const {
334 FOLLY_ASSERT(static_assert(!std::is_same<Tag, void>::value,
335 "Must use a unique Tag to use the accessAllThreads feature"));
336 return Accessor(id_);
342 threadlocal_detail::StaticMeta<Tag>::destroy(id_);
347 ThreadLocalPtr(const ThreadLocalPtr&) = delete;
348 ThreadLocalPtr& operator=(const ThreadLocalPtr&) = delete;
350 int id_; // every instantiation has a unique id
353 #undef FOLLY_NOEXCEPT
357 #endif /* FOLLY_THREADLOCAL_H_ */