folly/PackedSyncPtr.h

   1 /*
   2  * Copyright 2012 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 #ifndef FOLLY_PACKEDSYNCPTR_H_
  18 #define FOLLY_PACKEDSYNCPTR_H_
  19
  20 #ifndef __x86_64__
  21 # error "PackedSyncPtr is x64-specific code."
  22 #endif
  23
  24 /*
  25  * An 8-byte pointer with an integrated spin lock and 15-bit integer
  26  * (you can use this for a size of the allocation, if you want, or
  27  * something else, or nothing).
  28  *
  29  * This is using an x64-specific detail about the effective virtual
  30  * address space.  Long story short: the upper two bytes of all our
  31  * pointers will be zero in reality---and if you have a couple billion
  32  * such pointers in core, it makes pretty good sense to try to make
  33  * use of that memory.  The exact details can be perused here:
  34  *
  35  *    http://en.wikipedia.org/wiki/X86-64#Canonical_form_addresses
  36  *
  37  * This is not a "smart" pointer: nothing automagical is going on
  38  * here.  Locking is up to the user.  Resource deallocation is up to
  39  * the user.  Locks are never acquired or released outside explicit
  40  * calls to lock() and unlock().
  41  *
  42  * Change the value of the raw pointer with set(), but you must hold
  43  * the lock when calling this function if multiple threads could be
  44  * using this class.
  45  *
  46  * TODO(jdelong): should we use the low order bit for the lock, so we
  47  * get a whole 16-bits for our integer?  (There's also 2 more bits
  48  * down there if the pointer comes from malloc.)
  49  *
  50  * @author Spencer Ahrens <sahrens@fb.com>
  51  * @author Jordan DeLong <delong.j@fb.com>
  52  */
  53
  54 #include "folly/SmallLocks.h"
  55 #include <type_traits>
  56 #include <glog/logging.h>
  57
  58 namespace folly {
  59
  60 template<class T>
  61 class PackedSyncPtr {
  62   // This just allows using this class even with T=void.  Attempting
  63   // to use the operator* or operator[] on a PackedSyncPtr<void> will
  64   // still properly result in a compile error.
  65   typedef typename std::add_lvalue_reference<T>::type reference;
  66
  67 public:
  68   /*
  69    * If you default construct one of these, you must call this init()
  70    * function before using it.
  71    *
  72    * (We are avoiding a constructor to ensure gcc allows us to put
  73    * this class in packed structures.)
  74    */
  75   void init(T* initialPtr = 0, uint16_t initialExtra = 0) {
  76     auto intPtr = reinterpret_cast<uintptr_t>(initialPtr);
  77     CHECK(!(intPtr >> 48));
  78     data_.init(intPtr);
  79     setExtra(initialExtra);
  80   }
  81
  82   /*
  83    * Sets a new pointer.  You must hold the lock when calling this
  84    * function, or else be able to guarantee no other threads could be
  85    * using this PackedSyncPtr<>.
  86    */
  87   void set(T* t) {
  88     auto intPtr = reinterpret_cast<uintptr_t>(t);
  89     auto shiftedExtra = uintptr_t(extra()) << 48;
  90     CHECK(!(intPtr >> 48));
  91     data_.setData(intPtr | shiftedExtra);
  92   }
  93
  94   /*
  95    * Get the pointer.
  96    *
  97    * You can call any of these without holding the lock, with the
  98    * normal types of behavior you'll get on x64 from reading a pointer
  99    * without locking.
 100    */
 101   T* get() const {
 102     return reinterpret_cast<T*>(data_.getData() & (-1ull >> 16));
 103   }
 104   T* operator->() const { return get(); }
 105   reference operator*() const { return *get(); }
 106   reference operator[](std::ptrdiff_t i) const { return get()[i]; }
 107
 108   // Syncronization (logically const, even though this mutates our
 109   // locked state: you can lock a const PackedSyncPtr<T> to read it).
 110   void lock() const { data_.lock(); }
 111   void unlock() const { data_.unlock(); }
 112   bool try_lock() const { return data_.try_lock(); }
 113
 114   /*
 115    * Access extra data stored in unused bytes of the pointer.
 116    *
 117    * It is ok to call this without holding the lock.
 118    */
 119   uint16_t extra() const {
 120     return data_.getData() >> 48;
 121   }
 122
 123   /*
 124    * Don't try to put anything into this that has the high bit set:
 125    * that's what we're using for the mutex.
 126    *
 127    * Don't call this without holding the lock.
 128    */
 129   void setExtra(uint16_t extra) {
 130     CHECK(!(extra & 0x8000));
 131     auto ptr = data_.getData() & (-1ull >> 16);
 132     data_.setData((uintptr_t(extra) << 48) | ptr);
 133   }
 134
 135   // Logically private, but we can't have private data members and
 136   // still be considered a POD.  (In C++11 we are still a standard
 137   // layout struct if this is private, but it doesn't matter, since
 138   // gcc (4.6) won't let us use this with attribute packed still in
 139   // that case.)
 140   PicoSpinLock<uintptr_t> data_;
 141 };
 142
 143 static_assert(sizeof(PackedSyncPtr<void>) == 8,
 144               "PackedSyncPtr should be only 8 bytes---something is "
 145               "messed up");
 146
 147 }
 148
 149 #endif
 150