base/threading/thread_local_storage.h

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