1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_THREADING_THREAD_LOCAL_STORAGE_H_ 6 #define BASE_THREADING_THREAD_LOCAL_STORAGE_H_ 7 8 #include "base/base_export.h" 9 #include "base/basictypes.h" 10 11 #if defined(OS_WIN) 12 #include <windows.h> 13 #elif defined(OS_POSIX) 14 #include <pthread.h> 15 #endif 16 17 namespace base { 18 19 namespace internal { 20 21 // WARNING: You should *NOT* be using this class directly. 22 // PlatformThreadLocalStorage is low-level abstraction to the OS's TLS 23 // interface, you should instead be using ThreadLocalStorage::StaticSlot/Slot. 24 class BASE_EXPORT PlatformThreadLocalStorage { 25 public: 26 27 #if defined(OS_WIN) 28 typedef unsigned long TLSKey; 29 enum { TLS_KEY_OUT_OF_INDEXES = TLS_OUT_OF_INDEXES }; 30 #elif defined(OS_POSIX) 31 typedef pthread_key_t TLSKey; 32 // The following is a "reserved key" which is used in our generic Chromium 33 // ThreadLocalStorage implementation. We expect that an OS will not return 34 // such a key, but if it is returned (i.e., the OS tries to allocate it) we 35 // will just request another key. 36 enum { TLS_KEY_OUT_OF_INDEXES = 0x7FFFFFFF }; 37 #endif 38 39 // The following methods need to be supported on each OS platform, so that 40 // the Chromium ThreadLocalStore functionality can be constructed. 41 // Chromium will use these methods to acquire a single OS slot, and then use 42 // that to support a much larger number of Chromium slots (independent of the 43 // OS restrictions). 44 // The following returns true if it successfully is able to return an OS 45 // key in |key|. 46 static bool AllocTLS(TLSKey* key); 47 // Note: FreeTLS() doesn't have to be called, it is fine with this leak, OS 48 // might not reuse released slot, you might just reset the TLS value with 49 // SetTLSValue(). 50 static void FreeTLS(TLSKey key); 51 static void SetTLSValue(TLSKey key, void* value); 52 static void* GetTLSValue(TLSKey key); 53 54 // Each platform (OS implementation) is required to call this method on each 55 // terminating thread when the thread is about to terminate. This method 56 // will then call all registered destructors for slots in Chromium 57 // ThreadLocalStorage, until there are no slot values remaining as having 58 // been set on this thread. 59 // Destructors may end up being called multiple times on a terminating 60 // thread, as other destructors may re-set slots that were previously 61 // destroyed. 62 #if defined(OS_WIN) 63 // Since Windows which doesn't support TLS destructor, the implementation 64 // should use GetTLSValue() to retrieve the value of TLS slot. 65 static void OnThreadExit(); 66 #elif defined(OS_POSIX) 67 // |Value| is the data stored in TLS slot, The implementation can't use 68 // GetTLSValue() to retrieve the value of slot as it has already been reset 69 // in Posix. 70 static void OnThreadExit(void* value); 71 #endif 72 }; 73 74 } // namespace internal 75 76 // Wrapper for thread local storage. This class doesn't do much except provide 77 // an API for portability. 78 class BASE_EXPORT ThreadLocalStorage { 79 public: 80 81 // Prototype for the TLS destructor function, which can be optionally used to 82 // cleanup thread local storage on thread exit. 'value' is the data that is 83 // stored in thread local storage. 84 typedef void (*TLSDestructorFunc)(void* value); 85 86 // StaticSlot uses its own struct initializer-list style static 87 // initialization, as base's LINKER_INITIALIZED requires a constructor and on 88 // some compilers (notably gcc 4.4) this still ends up needing runtime 89 // initialization. 90 #define TLS_INITIALIZER {0} 91 92 // A key representing one value stored in TLS. 93 // Initialize like 94 // ThreadLocalStorage::StaticSlot my_slot = TLS_INITIALIZER; 95 // If you're not using a static variable, use the convenience class 96 // ThreadLocalStorage::Slot (below) instead. 97 struct BASE_EXPORT StaticSlot { 98 // Set up the TLS slot. Called by the constructor. 99 // 'destructor' is a pointer to a function to perform per-thread cleanup of 100 // this object. If set to NULL, no cleanup is done for this TLS slot. 101 // Returns false on error. 102 bool Initialize(TLSDestructorFunc destructor); 103 104 // Free a previously allocated TLS 'slot'. 105 // If a destructor was set for this slot, removes 106 // the destructor so that remaining threads exiting 107 // will not free data. 108 void Free(); 109 110 // Get the thread-local value stored in slot 'slot'. 111 // Values are guaranteed to initially be zero. 112 void* Get() const; 113 114 // Set the thread-local value stored in slot 'slot' to 115 // value 'value'. 116 void Set(void* value); 117 initializedStaticSlot118 bool initialized() const { return initialized_; } 119 120 // The internals of this struct should be considered private. 121 bool initialized_; 122 int slot_; 123 }; 124 125 // A convenience wrapper around StaticSlot with a constructor. Can be used 126 // as a member variable. 127 class BASE_EXPORT Slot : public StaticSlot { 128 public: 129 // Calls StaticSlot::Initialize(). 130 explicit Slot(TLSDestructorFunc destructor = NULL); 131 132 private: 133 using StaticSlot::initialized_; 134 using StaticSlot::slot_; 135 136 DISALLOW_COPY_AND_ASSIGN(Slot); 137 }; 138 139 DISALLOW_COPY_AND_ASSIGN(ThreadLocalStorage); 140 }; 141 142 } // namespace base 143 144 #endif // BASE_THREADING_THREAD_LOCAL_STORAGE_H_ 145