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.
17 #ifndef FOLLY_PACKEDSYNCPTR_H_
18 #define FOLLY_PACKEDSYNCPTR_H_
21 # error "PackedSyncPtr is x64-specific code."
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).
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:
35 * http://en.wikipedia.org/wiki/X86-64#Canonical_form_addresses
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().
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
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.)
50 * @author Spencer Ahrens <sahrens@fb.com>
51 * @author Jordan DeLong <delong.j@fb.com>
54 #include "folly/SmallLocks.h"
55 #include <type_traits>
56 #include <glog/logging.h>
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;
69 * If you default construct one of these, you must call this init()
70 * function before using it.
72 * (We are avoiding a constructor to ensure gcc allows us to put
73 * this class in packed structures.)
75 void init(T* initialPtr = 0, uint16_t initialExtra = 0) {
76 auto intPtr = reinterpret_cast<uintptr_t>(initialPtr);
77 CHECK(!(intPtr >> 48));
79 setExtra(initialExtra);
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<>.
88 auto intPtr = reinterpret_cast<uintptr_t>(t);
89 auto shiftedExtra = uintptr_t(extra()) << 48;
90 CHECK(!(intPtr >> 48));
91 data_.setData(intPtr | shiftedExtra);
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
102 return reinterpret_cast<T*>(data_.getData() & (-1ull >> 16));
104 T* operator->() const { return get(); }
105 reference operator*() const { return *get(); }
106 reference operator[](std::ptrdiff_t i) const { return get()[i]; }
108 // Synchronization (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(); }
115 * Access extra data stored in unused bytes of the pointer.
117 * It is ok to call this without holding the lock.
119 uint16_t extra() const {
120 return data_.getData() >> 48;
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.
127 * Don't call this without holding the lock.
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);
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
140 PicoSpinLock<uintptr_t> data_;
143 static_assert(sizeof(PackedSyncPtr<void>) == 8,
144 "PackedSyncPtr should be only 8 bytes---something is "