2 * Copyright 2016 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)
39 #include <folly/Portability.h>
40 #include <boost/iterator/iterator_facade.hpp>
41 #include <folly/Likely.h>
42 #include <type_traits>
46 enum class TLPDestructionMode {
52 #include <folly/detail/ThreadLocalDetail.h>
56 template<class T, class Tag> class ThreadLocalPtr;
58 template<class T, class Tag=void>
61 constexpr ThreadLocal() : constructor_([]() {
65 explicit ThreadLocal(std::function<T*()> constructor) :
66 constructor_(constructor) {
71 if (LIKELY(ptr != nullptr)) {
75 // separated new item creation out to speed up the fast path.
79 T* operator->() const {
83 T& operator*() const {
87 void reset(T* newPtr = nullptr) {
91 typedef typename ThreadLocalPtr<T,Tag>::Accessor Accessor;
92 Accessor accessAllThreads() const {
93 return tlp_.accessAllThreads();
97 ThreadLocal(ThreadLocal&&) = default;
98 ThreadLocal& operator=(ThreadLocal&&) = default;
102 ThreadLocal(const ThreadLocal&) = delete;
103 ThreadLocal& operator=(const ThreadLocal&) = delete;
106 auto ptr = constructor_();
111 mutable ThreadLocalPtr<T,Tag> tlp_;
112 std::function<T*()> constructor_;
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
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.
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.
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)
141 template<class T, class Tag=void>
142 class ThreadLocalPtr {
144 typedef threadlocal_detail::StaticMeta<Tag> StaticMeta;
146 constexpr ThreadLocalPtr() : id_() {}
148 ThreadLocalPtr(ThreadLocalPtr&& other) noexcept :
149 id_(std::move(other.id_)) {
152 ThreadLocalPtr& operator=(ThreadLocalPtr&& other) {
153 assert(this != &other);
155 id_ = std::move(other.id_);
164 threadlocal_detail::ElementWrapper& w = StaticMeta::instance().get(&id_);
165 return static_cast<T*>(w.ptr);
168 T* operator->() const {
172 T& operator*() const {
177 threadlocal_detail::ElementWrapper& w = StaticMeta::instance().get(&id_);
179 return static_cast<T*>(w.release());
182 void reset(T* newPtr = nullptr) {
183 threadlocal_detail::ElementWrapper& w = StaticMeta::instance().get(&id_);
185 if (w.ptr != newPtr) {
186 w.dispose(TLPDestructionMode::THIS_THREAD);
191 explicit operator bool() const {
192 return get() != nullptr;
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())
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);
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.
215 friend class ThreadLocalPtr<T,Tag>;
217 threadlocal_detail::StaticMetaBase& meta_;
223 friend class Iterator;
225 // The iterators obtained from Accessor are bidirectional iterators.
226 class Iterator : public boost::iterator_facade<
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_;
245 T& dereference() const {
246 return *static_cast<T*>(e_->elements[accessor_->id_].ptr);
249 bool equal(const Iterator& other) const {
250 return (accessor_->id_ == other.accessor_->id_ &&
254 explicit Iterator(const Accessor* accessor)
255 : accessor_(accessor),
256 e_(&accessor_->meta_.head_) {
260 return (e_->elements &&
261 accessor_->id_ < e_->elementsCapacity &&
262 e_->elements[accessor_->id_].ptr);
265 void incrementToValid() {
266 for (; e_ != &accessor_->meta_.head_ && !valid(); e_ = e_->next) { }
269 void decrementToValid() {
270 for (; e_ != &accessor_->meta_.head_ && !valid(); e_ = e_->prev) { }
278 Iterator begin() const {
279 return ++Iterator(this);
282 Iterator end() const {
283 return Iterator(this);
286 Accessor(const Accessor&) = delete;
287 Accessor& operator=(const Accessor&) = delete;
289 Accessor(Accessor&& other) noexcept
290 : meta_(other.meta_),
294 other.lock_ = nullptr;
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);
307 swap(lock_, other.lock_);
308 swap(id_, other.id_);
312 : meta_(threadlocal_detail::StaticMeta<Tag>::instance()),
318 explicit Accessor(uint32_t id)
319 : meta_(threadlocal_detail::StaticMeta<Tag>::instance()),
320 lock_(&meta_.lock_) {
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()));
344 StaticMeta::instance().destroy(&id_);
348 ThreadLocalPtr(const ThreadLocalPtr&) = delete;
349 ThreadLocalPtr& operator=(const ThreadLocalPtr&) = delete;
351 mutable typename StaticMeta::EntryID id_;