Move folly/Hash.h to folly/hash/
[folly.git] / folly / Synchronized.h
1 /*
2  * Copyright 2017 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 /**
18  * This module implements a Synchronized abstraction useful in
19  * mutex-based concurrency.
20  *
21  * The Synchronized<T, Mutex> class is the primary public API exposed by this
22  * module.  See folly/docs/Synchronized.md for a more complete explanation of
23  * this class and its benefits.
24  */
25
26 #pragma once
27
28 #include <folly/Likely.h>
29 #include <folly/LockTraits.h>
30 #include <folly/Preprocessor.h>
31 #include <folly/SharedMutex.h>
32 #include <folly/Traits.h>
33 #include <glog/logging.h>
34 #include <mutex>
35 #include <type_traits>
36
37 namespace folly {
38
39 template <class LockedType, class Mutex, class LockPolicy>
40 class LockedPtrBase;
41 template <class LockedType, class LockPolicy>
42 class LockedPtr;
43 template <class LockedType, class LockPolicy = LockPolicyExclusive>
44 class LockedGuardPtr;
45
46 /**
47  * Public version of LockInterfaceDispatcher that contains the MutexLevel enum
48  * for the passed in mutex type
49  *
50  * This is decoupled from MutexLevelValueImpl in LockTraits.h because this
51  * ensures that a heterogenous mutex with a different API can be used.  For
52  * example - if a mutex does not have a lock_shared() method but the
53  * LockTraits specialization for it supports a static non member
54  * lock_shared(Mutex&) it can be used as a shared mutex and will provide
55  * rlock() and wlock() functions.
56  */
57 template <class Mutex>
58 using MutexLevelValue = detail::MutexLevelValueImpl<
59     true,
60     LockTraits<Mutex>::is_shared,
61     LockTraits<Mutex>::is_upgrade>;
62
63 /**
64  * SynchronizedBase is a helper parent class for Synchronized<T>.
65  *
66  * It provides wlock() and rlock() methods for shared mutex types,
67  * or lock() methods for purely exclusive mutex types.
68  */
69 template <class Subclass, detail::MutexLevel level>
70 class SynchronizedBase;
71
72 /**
73  * SynchronizedBase specialization for shared mutex types.
74  *
75  * This class provides wlock() and rlock() methods for acquiring the lock and
76  * accessing the data.
77  */
78 template <class Subclass>
79 class SynchronizedBase<Subclass, detail::MutexLevel::SHARED> {
80  public:
81   using LockedPtr = ::folly::LockedPtr<Subclass, LockPolicyExclusive>;
82   using ConstWLockedPtr =
83       ::folly::LockedPtr<const Subclass, LockPolicyExclusive>;
84   using ConstLockedPtr = ::folly::LockedPtr<const Subclass, LockPolicyShared>;
85
86   /**
87    * Acquire an exclusive lock, and return a LockedPtr that can be used to
88    * safely access the datum.
89    *
90    * LockedPtr offers operator -> and * to provide access to the datum.
91    * The lock will be released when the LockedPtr is destroyed.
92    */
93   LockedPtr wlock() {
94     return LockedPtr(static_cast<Subclass*>(this));
95   }
96   ConstWLockedPtr wlock() const {
97     return ConstWLockedPtr(static_cast<const Subclass*>(this));
98   }
99
100   /**
101    * Acquire a read lock, and return a ConstLockedPtr that can be used to
102    * safely access the datum.
103    */
104   ConstLockedPtr rlock() const {
105     return ConstLockedPtr(static_cast<const Subclass*>(this));
106   }
107
108   /**
109    * Attempts to acquire the lock, or fails if the timeout elapses first.
110    * If acquisition is unsuccessful, the returned LockedPtr will be null.
111    *
112    * (Use LockedPtr::isNull() to check for validity.)
113    */
114   template <class Rep, class Period>
115   LockedPtr wlock(const std::chrono::duration<Rep, Period>& timeout) {
116     return LockedPtr(static_cast<Subclass*>(this), timeout);
117   }
118   template <class Rep, class Period>
119   ConstWLockedPtr wlock(
120       const std::chrono::duration<Rep, Period>& timeout) const {
121     return ConstWLockedPtr(static_cast<const Subclass*>(this), timeout);
122   }
123
124   /**
125    * Attempts to acquire the lock, or fails if the timeout elapses first.
126    * If acquisition is unsuccessful, the returned LockedPtr will be null.
127    *
128    * (Use LockedPtr::isNull() to check for validity.)
129    */
130   template <class Rep, class Period>
131   ConstLockedPtr rlock(
132       const std::chrono::duration<Rep, Period>& timeout) const {
133     return ConstLockedPtr(static_cast<const Subclass*>(this), timeout);
134   }
135
136   /*
137    * Note: C++ 17 adds guaranteed copy elision.  (http://wg21.link/P0135)
138    * Once compilers support this, it would be nice to add wguard() and rguard()
139    * methods that return LockedGuardPtr objects.
140    */
141
142   /**
143    * Invoke a function while holding the lock exclusively.
144    *
145    * A reference to the datum will be passed into the function as its only
146    * argument.
147    *
148    * This can be used with a lambda argument for easily defining small critical
149    * sections in the code.  For example:
150    *
151    *   auto value = obj.withWLock([](auto& data) {
152    *     data.doStuff();
153    *     return data.getValue();
154    *   });
155    */
156   template <class Function>
157   auto withWLock(Function&& function) {
158     LockedGuardPtr<Subclass, LockPolicyExclusive> guardPtr(
159         static_cast<Subclass*>(this));
160     return function(*guardPtr);
161   }
162   template <class Function>
163   auto withWLock(Function&& function) const {
164     LockedGuardPtr<const Subclass, LockPolicyExclusive> guardPtr(
165         static_cast<const Subclass*>(this));
166     return function(*guardPtr);
167   }
168
169   /**
170    * Invoke a function while holding the lock exclusively.
171    *
172    * This is similar to withWLock(), but the function will be passed a
173    * LockedPtr rather than a reference to the data itself.
174    *
175    * This allows scopedUnlock() to be called on the LockedPtr argument if
176    * desired.
177    */
178   template <class Function>
179   auto withWLockPtr(Function&& function) {
180     return function(wlock());
181   }
182   template <class Function>
183   auto withWLockPtr(Function&& function) const {
184     return function(wlock());
185   }
186
187   /**
188    * Invoke a function while holding an the lock in shared mode.
189    *
190    * A const reference to the datum will be passed into the function as its
191    * only argument.
192    */
193   template <class Function>
194   auto withRLock(Function&& function) const {
195     LockedGuardPtr<const Subclass, LockPolicyShared> guardPtr(
196         static_cast<const Subclass*>(this));
197     return function(*guardPtr);
198   }
199
200   template <class Function>
201   auto withRLockPtr(Function&& function) const {
202     return function(rlock());
203   }
204 };
205
206 /**
207  * SynchronizedBase specialization for upgrade mutex types.
208  *
209  * This class provides all the functionality provided by the SynchronizedBase
210  * specialization for shared mutexes and a ulock() method that returns an
211  * upgradable lock RAII proxy
212  */
213 template <class Subclass>
214 class SynchronizedBase<Subclass, detail::MutexLevel::UPGRADE>
215     : public SynchronizedBase<Subclass, detail::MutexLevel::SHARED> {
216  public:
217   using UpgradeLockedPtr = ::folly::LockedPtr<Subclass, LockPolicyUpgrade>;
218   using ConstUpgradeLockedPtr =
219       ::folly::LockedPtr<const Subclass, LockPolicyUpgrade>;
220   using UpgradeLockedGuardPtr =
221       ::folly::LockedGuardPtr<Subclass, LockPolicyUpgrade>;
222   using ConstUpgradeLockedGuardPtr =
223       ::folly::LockedGuardPtr<const Subclass, LockPolicyUpgrade>;
224
225   /**
226    * Acquire an upgrade lock and return a LockedPtr that can be used to safely
227    * access the datum
228    *
229    * And the const version
230    */
231   UpgradeLockedPtr ulock() {
232     return UpgradeLockedPtr(static_cast<Subclass*>(this));
233   }
234   ConstUpgradeLockedPtr ulock() const {
235     return ConstUpgradeLockedPtr(static_cast<const Subclass*>(this));
236   }
237
238   /**
239    * Acquire an upgrade lock and return a LockedPtr that can be used to safely
240    * access the datum
241    *
242    * And the const version
243    */
244   template <class Rep, class Period>
245   UpgradeLockedPtr ulock(const std::chrono::duration<Rep, Period>& timeout) {
246     return UpgradeLockedPtr(static_cast<Subclass*>(this), timeout);
247   }
248   template <class Rep, class Period>
249   UpgradeLockedPtr ulock(
250       const std::chrono::duration<Rep, Period>& timeout) const {
251     return ConstUpgradeLockedPtr(static_cast<const Subclass*>(this), timeout);
252   }
253
254   /**
255    * Invoke a function while holding the lock.
256    *
257    * A reference to the datum will be passed into the function as its only
258    * argument.
259    *
260    * This can be used with a lambda argument for easily defining small critical
261    * sections in the code.  For example:
262    *
263    *   auto value = obj.withULock([](auto& data) {
264    *     data.doStuff();
265    *     return data.getValue();
266    *   });
267    *
268    * This is probably not the function you want.  If the intent is to read the
269    * data object and determine whether you should upgrade to a write lock then
270    * the withULockPtr() method should be called instead, since it gives access
271    * to the LockedPtr proxy (which can be upgraded via the
272    * moveFromUpgradeToWrite() method)
273    */
274   template <class Function>
275   auto withULock(Function&& function) const {
276     ConstUpgradeLockedGuardPtr guardPtr(static_cast<const Subclass*>(this));
277     return function(*guardPtr);
278   }
279
280   /**
281    * Invoke a function while holding the lock exclusively.
282    *
283    * This is similar to withULock(), but the function will be passed a
284    * LockedPtr rather than a reference to the data itself.
285    *
286    * This allows scopedUnlock() and getUniqueLock() to be called on the
287    * LockedPtr argument.
288    *
289    * This also allows you to upgrade the LockedPtr proxy to a write state so
290    * that changes can be made to the underlying data
291    */
292   template <class Function>
293   auto withULockPtr(Function&& function) {
294     return function(ulock());
295   }
296   template <class Function>
297   auto withULockPtr(Function&& function) const {
298     return function(ulock());
299   }
300 };
301
302 /**
303  * SynchronizedBase specialization for non-shared mutex types.
304  *
305  * This class provides lock() methods for acquiring the lock and accessing the
306  * data.
307  */
308 template <class Subclass>
309 class SynchronizedBase<Subclass, detail::MutexLevel::UNIQUE> {
310  public:
311   using LockedPtr = ::folly::LockedPtr<Subclass, LockPolicyExclusive>;
312   using ConstLockedPtr =
313       ::folly::LockedPtr<const Subclass, LockPolicyExclusive>;
314
315   /**
316    * Acquire a lock, and return a LockedPtr that can be used to safely access
317    * the datum.
318    */
319   LockedPtr lock() {
320     return LockedPtr(static_cast<Subclass*>(this));
321   }
322
323   /**
324    * Acquire a lock, and return a ConstLockedPtr that can be used to safely
325    * access the datum.
326    */
327   ConstLockedPtr lock() const {
328     return ConstLockedPtr(static_cast<const Subclass*>(this));
329   }
330
331   /**
332    * Attempts to acquire the lock, or fails if the timeout elapses first.
333    * If acquisition is unsuccessful, the returned LockedPtr will be null.
334    */
335   template <class Rep, class Period>
336   LockedPtr lock(const std::chrono::duration<Rep, Period>& timeout) {
337     return LockedPtr(static_cast<Subclass*>(this), timeout);
338   }
339
340   /**
341    * Attempts to acquire the lock, or fails if the timeout elapses first.
342    * If acquisition is unsuccessful, the returned LockedPtr will be null.
343    */
344   template <class Rep, class Period>
345   ConstLockedPtr lock(const std::chrono::duration<Rep, Period>& timeout) const {
346     return ConstLockedPtr(static_cast<const Subclass*>(this), timeout);
347   }
348
349   /*
350    * Note: C++ 17 adds guaranteed copy elision.  (http://wg21.link/P0135)
351    * Once compilers support this, it would be nice to add guard() methods that
352    * return LockedGuardPtr objects.
353    */
354
355   /**
356    * Invoke a function while holding the lock.
357    *
358    * A reference to the datum will be passed into the function as its only
359    * argument.
360    *
361    * This can be used with a lambda argument for easily defining small critical
362    * sections in the code.  For example:
363    *
364    *   auto value = obj.withLock([](auto& data) {
365    *     data.doStuff();
366    *     return data.getValue();
367    *   });
368    */
369   template <class Function>
370   auto withLock(Function&& function) {
371     LockedGuardPtr<Subclass, LockPolicyExclusive> guardPtr(
372         static_cast<Subclass*>(this));
373     return function(*guardPtr);
374   }
375   template <class Function>
376   auto withLock(Function&& function) const {
377     LockedGuardPtr<const Subclass, LockPolicyExclusive> guardPtr(
378         static_cast<const Subclass*>(this));
379     return function(*guardPtr);
380   }
381
382   /**
383    * Invoke a function while holding the lock exclusively.
384    *
385    * This is similar to withWLock(), but the function will be passed a
386    * LockedPtr rather than a reference to the data itself.
387    *
388    * This allows scopedUnlock() and getUniqueLock() to be called on the
389    * LockedPtr argument.
390    */
391   template <class Function>
392   auto withLockPtr(Function&& function) {
393     return function(lock());
394   }
395   template <class Function>
396   auto withLockPtr(Function&& function) const {
397     return function(lock());
398   }
399 };
400
401 /**
402  * Synchronized<T> encapsulates an object of type T (a "datum") paired
403  * with a mutex. The only way to access the datum is while the mutex
404  * is locked, and Synchronized makes it virtually impossible to do
405  * otherwise. The code that would access the datum in unsafe ways
406  * would look odd and convoluted, thus readily alerting the human
407  * reviewer. In contrast, the code that uses Synchronized<T> correctly
408  * looks simple and intuitive.
409  *
410  * The second parameter must be a mutex type.  Any mutex type supported by
411  * LockTraits<Mutex> can be used.  By default any class with lock() and
412  * unlock() methods will work automatically.  LockTraits can be specialized to
413  * teach Synchronized how to use other custom mutex types.  See the
414  * documentation in LockTraits.h for additional details.
415  *
416  * Supported mutexes that work by default include std::mutex,
417  * std::recursive_mutex, std::timed_mutex, std::recursive_timed_mutex,
418  * folly::SharedMutex, folly::RWSpinLock, and folly::SpinLock.
419  * Include LockTraitsBoost.h to get additional LockTraits specializations to
420  * support the following boost mutex types: boost::mutex,
421  * boost::recursive_mutex, boost::shared_mutex, boost::timed_mutex, and
422  * boost::recursive_timed_mutex.
423  */
424 template <class T, class Mutex = SharedMutex>
425 struct Synchronized : public SynchronizedBase<
426                           Synchronized<T, Mutex>,
427                           MutexLevelValue<Mutex>::value> {
428  private:
429   using Base =
430       SynchronizedBase<Synchronized<T, Mutex>, MutexLevelValue<Mutex>::value>;
431   static constexpr bool nxCopyCtor{
432       std::is_nothrow_copy_constructible<T>::value};
433   static constexpr bool nxMoveCtor{
434       std::is_nothrow_move_constructible<T>::value};
435
436   // used to disable copy construction and assignment
437   class NonImplementedType;
438
439  public:
440   using LockedPtr = typename Base::LockedPtr;
441   using ConstLockedPtr = typename Base::ConstLockedPtr;
442   using DataType = T;
443   using MutexType = Mutex;
444
445   /**
446    * Default constructor leaves both members call their own default
447    * constructor.
448    */
449   Synchronized() = default;
450
451   /**
452    * Copy constructor copies the data (with locking the source and
453    * all) but does NOT copy the mutex. Doing so would result in
454    * deadlocks.
455    *
456    * Note that the copy constructor may throw because it acquires a lock in
457    * the contextualRLock() method
458    */
459  public:
460   /* implicit */ Synchronized(typename std::conditional<
461                               std::is_copy_constructible<T>::value,
462                               const Synchronized&,
463                               NonImplementedType>::type rhs) /* may throw */
464       : Synchronized(rhs, rhs.contextualRLock()) {}
465
466   /**
467    * Move constructor moves the data (with locking the source and all)
468    * but does not move the mutex.
469    *
470    * Note that the move constructor may throw because it acquires a lock.
471    * Since the move constructor is not declared noexcept, when objects of this
472    * class are used as elements in a vector or a similar container.  The
473    * elements might not be moved around when resizing.  They might be copied
474    * instead.  You have been warned.
475    */
476   Synchronized(Synchronized&& rhs) /* may throw */
477       : Synchronized(std::move(rhs), rhs.contextualLock()) {}
478
479   /**
480    * Constructor taking a datum as argument copies it. There is no
481    * need to lock the constructing object.
482    */
483   explicit Synchronized(const T& rhs) noexcept(nxCopyCtor) : datum_(rhs) {}
484
485   /**
486    * Constructor taking a datum rvalue as argument moves it. Again,
487    * there is no need to lock the constructing object.
488    */
489   explicit Synchronized(T&& rhs) noexcept(nxMoveCtor)
490       : datum_(std::move(rhs)) {}
491
492   /**
493    * Lets you construct non-movable types in-place. Use the constexpr
494    * instance `in_place` as the first argument.
495    */
496   template <typename... Args>
497   explicit Synchronized(in_place_t, Args&&... args)
498       : datum_(std::forward<Args>(args)...) {}
499
500   /**
501    * The canonical assignment operator only assigns the data, NOT the
502    * mutex. It locks the two objects in ascending order of their
503    * addresses.
504    */
505   Synchronized& operator=(typename std::conditional<
506                           std::is_copy_assignable<T>::value,
507                           const Synchronized&,
508                           NonImplementedType>::type rhs) {
509     if (this == &rhs) {
510       // Self-assignment, pass.
511     } else if (this < &rhs) {
512       auto guard1 = operator->();
513       auto guard2 = rhs.operator->();
514       datum_ = rhs.datum_;
515     } else {
516       auto guard1 = rhs.operator->();
517       auto guard2 = operator->();
518       datum_ = rhs.datum_;
519     }
520     return *this;
521   }
522
523   /**
524    * Move assignment operator, only assigns the data, NOT the
525    * mutex. It locks the two objects in ascending order of their
526    * addresses.
527    */
528   Synchronized& operator=(Synchronized&& rhs) {
529     if (this == &rhs) {
530       // Self-assignment, pass.
531     } else if (this < &rhs) {
532       auto guard1 = operator->();
533       auto guard2 = rhs.operator->();
534       datum_ = std::move(rhs.datum_);
535     } else {
536       auto guard1 = rhs.operator->();
537       auto guard2 = operator->();
538       datum_ = std::move(rhs.datum_);
539     }
540     return *this;
541   }
542
543   /**
544    * Lock object, assign datum.
545    */
546   Synchronized& operator=(const T& rhs) {
547     auto guard = operator->();
548     datum_ = rhs;
549     return *this;
550   }
551
552   /**
553    * Lock object, move-assign datum.
554    */
555   Synchronized& operator=(T&& rhs) {
556     auto guard = operator->();
557     datum_ = std::move(rhs);
558     return *this;
559   }
560
561   /**
562    * Acquire an appropriate lock based on the context.
563    *
564    * If the mutex is a shared mutex, and the Synchronized instance is const,
565    * this acquires a shared lock.  Otherwise this acquires an exclusive lock.
566    *
567    * In general, prefer using the explicit rlock() and wlock() methods
568    * for read-write locks, and lock() for purely exclusive locks.
569    *
570    * contextualLock() is primarily intended for use in other template functions
571    * that do not necessarily know the lock type.
572    */
573   LockedPtr contextualLock() {
574     return LockedPtr(this);
575   }
576   ConstLockedPtr contextualLock() const {
577     return ConstLockedPtr(this);
578   }
579   template <class Rep, class Period>
580   LockedPtr contextualLock(const std::chrono::duration<Rep, Period>& timeout) {
581     return LockedPtr(this, timeout);
582   }
583   template <class Rep, class Period>
584   ConstLockedPtr contextualLock(
585       const std::chrono::duration<Rep, Period>& timeout) const {
586     return ConstLockedPtr(this, timeout);
587   }
588   /**
589    * contextualRLock() acquires a read lock if the mutex type is shared,
590    * or a regular exclusive lock for non-shared mutex types.
591    *
592    * contextualRLock() when you know that you prefer a read lock (if
593    * available), even if the Synchronized<T> object itself is non-const.
594    */
595   ConstLockedPtr contextualRLock() const {
596     return ConstLockedPtr(this);
597   }
598   template <class Rep, class Period>
599   ConstLockedPtr contextualRLock(
600       const std::chrono::duration<Rep, Period>& timeout) const {
601     return ConstLockedPtr(this, timeout);
602   }
603
604   /**
605    * This accessor offers a LockedPtr. In turn, LockedPtr offers
606    * operator-> returning a pointer to T. The operator-> keeps
607    * expanding until it reaches a pointer, so syncobj->foo() will lock
608    * the object and call foo() against it.
609    *
610    * NOTE: This API is planned to be deprecated in an upcoming diff.
611    * Prefer using lock(), wlock(), or rlock() instead.
612    */
613   LockedPtr operator->() {
614     return LockedPtr(this);
615   }
616
617   /**
618    * Obtain a ConstLockedPtr.
619    *
620    * NOTE: This API is planned to be deprecated in an upcoming diff.
621    * Prefer using lock(), wlock(), or rlock() instead.
622    */
623   ConstLockedPtr operator->() const {
624     return ConstLockedPtr(this);
625   }
626
627   /**
628    * Attempts to acquire for a given number of milliseconds. If
629    * acquisition is unsuccessful, the returned LockedPtr is nullptr.
630    *
631    * NOTE: This API is deprecated.  Use lock(), wlock(), or rlock() instead.
632    * In the future it will be marked with a deprecation attribute to emit
633    * build-time warnings, and then it will be removed entirely.
634    */
635   LockedPtr timedAcquire(unsigned int milliseconds) {
636     return LockedPtr(this, std::chrono::milliseconds(milliseconds));
637   }
638
639   /**
640    * Attempts to acquire for a given number of milliseconds. If
641    * acquisition is unsuccessful, the returned ConstLockedPtr is nullptr.
642    *
643    * NOTE: This API is deprecated.  Use lock(), wlock(), or rlock() instead.
644    * In the future it will be marked with a deprecation attribute to emit
645    * build-time warnings, and then it will be removed entirely.
646    */
647   ConstLockedPtr timedAcquire(unsigned int milliseconds) const {
648     return ConstLockedPtr(this, std::chrono::milliseconds(milliseconds));
649   }
650
651   /**
652    * Sometimes, although you have a mutable object, you only want to
653    * call a const method against it. The most efficient way to achieve
654    * that is by using a read lock. You get to do so by using
655    * obj.asConst()->method() instead of obj->method().
656    *
657    * NOTE: This API is planned to be deprecated in an upcoming diff.
658    * Use rlock() instead.
659    */
660   const Synchronized& asConst() const {
661     return *this;
662   }
663
664   /**
665    * Swaps with another Synchronized. Protected against
666    * self-swap. Only data is swapped. Locks are acquired in increasing
667    * address order.
668    */
669   void swap(Synchronized& rhs) {
670     if (this == &rhs) {
671       return;
672     }
673     if (this > &rhs) {
674       return rhs.swap(*this);
675     }
676     auto guard1 = operator->();
677     auto guard2 = rhs.operator->();
678
679     using std::swap;
680     swap(datum_, rhs.datum_);
681   }
682
683   /**
684    * Swap with another datum. Recommended because it keeps the mutex
685    * held only briefly.
686    */
687   void swap(T& rhs) {
688     LockedPtr guard(this);
689
690     using std::swap;
691     swap(datum_, rhs);
692   }
693
694   /**
695    * Copies datum to a given target.
696    */
697   void copy(T* target) const {
698     ConstLockedPtr guard(this);
699     *target = datum_;
700   }
701
702   /**
703    * Returns a fresh copy of the datum.
704    */
705   T copy() const {
706     ConstLockedPtr guard(this);
707     return datum_;
708   }
709
710  private:
711   template <class LockedType, class MutexType, class LockPolicy>
712   friend class folly::LockedPtrBase;
713   template <class LockedType, class LockPolicy>
714   friend class folly::LockedPtr;
715   template <class LockedType, class LockPolicy>
716   friend class folly::LockedGuardPtr;
717
718   /**
719    * Helper constructors to enable Synchronized for
720    * non-default constructible types T.
721    * Guards are created in actual public constructors and are alive
722    * for the time required to construct the object
723    */
724   Synchronized(
725       const Synchronized& rhs,
726       const ConstLockedPtr& /*guard*/) noexcept(nxCopyCtor)
727       : datum_(rhs.datum_) {}
728
729   Synchronized(Synchronized&& rhs, const LockedPtr& /*guard*/) noexcept(
730       nxMoveCtor)
731       : datum_(std::move(rhs.datum_)) {}
732
733   // Synchronized data members
734   T datum_;
735   mutable Mutex mutex_;
736 };
737
738 template <class SynchronizedType, class LockPolicy>
739 class ScopedUnlocker;
740
741 namespace detail {
742 /*
743  * A helper alias that resolves to "const T" if the template parameter
744  * is a const Synchronized<T>, or "T" if the parameter is not const.
745  */
746 template <class SynchronizedType>
747 using SynchronizedDataType = typename std::conditional<
748     std::is_const<SynchronizedType>::value,
749     typename SynchronizedType::DataType const,
750     typename SynchronizedType::DataType>::type;
751 /*
752  * A helper alias that resolves to a ConstLockedPtr if the template parameter
753  * is a const Synchronized<T>, or a LockedPtr if the parameter is not const.
754  */
755 template <class SynchronizedType>
756 using LockedPtrType = typename std::conditional<
757     std::is_const<SynchronizedType>::value,
758     typename SynchronizedType::ConstLockedPtr,
759     typename SynchronizedType::LockedPtr>::type;
760 } // namespace detail
761
762 /**
763  * A helper base class for implementing LockedPtr.
764  *
765  * The main reason for having this as a separate class is so we can specialize
766  * it for std::mutex, so we can expose a std::unique_lock to the caller
767  * when std::mutex is being used.  This allows callers to use a
768  * std::condition_variable with the mutex from a Synchronized<T, std::mutex>.
769  *
770  * We don't use std::unique_lock with other Mutex types since it makes the
771  * LockedPtr class slightly larger, and it makes the logic to support
772  * ScopedUnlocker slightly more complicated.  std::mutex is the only one that
773  * really seems to benefit from the unique_lock.  std::condition_variable
774  * itself only supports std::unique_lock<std::mutex>, so there doesn't seem to
775  * be any real benefit to exposing the unique_lock with other mutex types.
776  *
777  * Note that the SynchronizedType template parameter may or may not be const
778  * qualified.
779  */
780 template <class SynchronizedType, class Mutex, class LockPolicy>
781 class LockedPtrBase {
782  public:
783   using MutexType = Mutex;
784   friend class folly::ScopedUnlocker<SynchronizedType, LockPolicy>;
785
786   /**
787    * Destructor releases.
788    */
789   ~LockedPtrBase() {
790     if (parent_) {
791       LockPolicy::unlock(parent_->mutex_);
792     }
793   }
794
795   /**
796    * Unlock the synchronized data.
797    *
798    * The LockedPtr can no longer be dereferenced after unlock() has been
799    * called.  isValid() will return false on an unlocked LockedPtr.
800    *
801    * unlock() can only be called on a LockedPtr that is valid.
802    */
803   void unlock() {
804     DCHECK(parent_ != nullptr);
805     LockPolicy::unlock(parent_->mutex_);
806     parent_ = nullptr;
807   }
808
809  protected:
810   LockedPtrBase() {}
811   explicit LockedPtrBase(SynchronizedType* parent) : parent_(parent) {
812     LockPolicy::lock(parent_->mutex_);
813   }
814   template <class Rep, class Period>
815   LockedPtrBase(
816       SynchronizedType* parent,
817       const std::chrono::duration<Rep, Period>& timeout) {
818     if (LockPolicy::try_lock_for(parent->mutex_, timeout)) {
819       this->parent_ = parent;
820     }
821   }
822   LockedPtrBase(LockedPtrBase&& rhs) noexcept : parent_(rhs.parent_) {
823     rhs.parent_ = nullptr;
824   }
825   LockedPtrBase& operator=(LockedPtrBase&& rhs) noexcept {
826     if (parent_) {
827       LockPolicy::unlock(parent_->mutex_);
828     }
829
830     parent_ = rhs.parent_;
831     rhs.parent_ = nullptr;
832     return *this;
833   }
834
835   using UnlockerData = SynchronizedType*;
836
837   /**
838    * Get a pointer to the Synchronized object from the UnlockerData.
839    *
840    * In the generic case UnlockerData is just the Synchronized pointer,
841    * so we return it as is.  (This function is more interesting in the
842    * std::mutex specialization below.)
843    */
844   static SynchronizedType* getSynchronized(UnlockerData data) {
845     return data;
846   }
847
848   UnlockerData releaseLock() {
849     DCHECK(parent_ != nullptr);
850     auto current = parent_;
851     parent_ = nullptr;
852     LockPolicy::unlock(current->mutex_);
853     return current;
854   }
855   void reacquireLock(UnlockerData&& data) {
856     DCHECK(parent_ == nullptr);
857     parent_ = data;
858     LockPolicy::lock(parent_->mutex_);
859   }
860
861   SynchronizedType* parent_ = nullptr;
862 };
863
864 /**
865  * LockedPtrBase specialization for use with std::mutex.
866  *
867  * When std::mutex is used we use a std::unique_lock to hold the mutex.
868  * This makes it possible to use std::condition_variable with a
869  * Synchronized<T, std::mutex>.
870  */
871 template <class SynchronizedType, class LockPolicy>
872 class LockedPtrBase<SynchronizedType, std::mutex, LockPolicy> {
873  public:
874   using MutexType = std::mutex;
875   friend class folly::ScopedUnlocker<SynchronizedType, LockPolicy>;
876
877   /**
878    * Destructor releases.
879    */
880   ~LockedPtrBase() {
881     // The std::unique_lock will automatically release the lock when it is
882     // destroyed, so we don't need to do anything extra here.
883   }
884
885   LockedPtrBase(LockedPtrBase&& rhs) noexcept
886       : lock_(std::move(rhs.lock_)), parent_(rhs.parent_) {
887     rhs.parent_ = nullptr;
888   }
889   LockedPtrBase& operator=(LockedPtrBase&& rhs) noexcept {
890     lock_ = std::move(rhs.lock_);
891     parent_ = rhs.parent_;
892     rhs.parent_ = nullptr;
893     return *this;
894   }
895
896   /**
897    * Get a reference to the std::unique_lock.
898    *
899    * This is provided so that callers can use Synchronized<T, std::mutex>
900    * with a std::condition_variable.
901    *
902    * While this API could be used to bypass the normal Synchronized APIs and
903    * manually interact with the underlying unique_lock, this is strongly
904    * discouraged.
905    */
906   std::unique_lock<std::mutex>& getUniqueLock() {
907     return lock_;
908   }
909
910   /**
911    * Unlock the synchronized data.
912    *
913    * The LockedPtr can no longer be dereferenced after unlock() has been
914    * called.  isValid() will return false on an unlocked LockedPtr.
915    *
916    * unlock() can only be called on a LockedPtr that is valid.
917    */
918   void unlock() {
919     DCHECK(parent_ != nullptr);
920     lock_.unlock();
921     parent_ = nullptr;
922   }
923
924  protected:
925   LockedPtrBase() {}
926   explicit LockedPtrBase(SynchronizedType* parent)
927       : lock_(parent->mutex_), parent_(parent) {}
928
929   using UnlockerData =
930       std::pair<std::unique_lock<std::mutex>, SynchronizedType*>;
931
932   static SynchronizedType* getSynchronized(const UnlockerData& data) {
933     return data.second;
934   }
935
936   UnlockerData releaseLock() {
937     DCHECK(parent_ != nullptr);
938     UnlockerData data(std::move(lock_), parent_);
939     parent_ = nullptr;
940     data.first.unlock();
941     return data;
942   }
943   void reacquireLock(UnlockerData&& data) {
944     lock_ = std::move(data.first);
945     lock_.lock();
946     parent_ = data.second;
947   }
948
949   // The specialization for std::mutex does have to store slightly more
950   // state than the default implementation.
951   std::unique_lock<std::mutex> lock_;
952   SynchronizedType* parent_ = nullptr;
953 };
954
955 /**
956  * This class temporarily unlocks a LockedPtr in a scoped manner.
957  */
958 template <class SynchronizedType, class LockPolicy>
959 class ScopedUnlocker {
960  public:
961   explicit ScopedUnlocker(LockedPtr<SynchronizedType, LockPolicy>* p)
962       : ptr_(p), data_(ptr_->releaseLock()) {}
963   ScopedUnlocker(const ScopedUnlocker&) = delete;
964   ScopedUnlocker& operator=(const ScopedUnlocker&) = delete;
965   ScopedUnlocker(ScopedUnlocker&& other) noexcept
966       : ptr_(other.ptr_), data_(std::move(other.data_)) {
967     other.ptr_ = nullptr;
968   }
969   ScopedUnlocker& operator=(ScopedUnlocker&& other) = delete;
970
971   ~ScopedUnlocker() {
972     if (ptr_) {
973       ptr_->reacquireLock(std::move(data_));
974     }
975   }
976
977   /**
978    * Return a pointer to the Synchronized object used by this ScopedUnlocker.
979    */
980   SynchronizedType* getSynchronized() const {
981     return LockedPtr<SynchronizedType, LockPolicy>::getSynchronized(data_);
982   }
983
984  private:
985   using Data = typename LockedPtr<SynchronizedType, LockPolicy>::UnlockerData;
986   LockedPtr<SynchronizedType, LockPolicy>* ptr_{nullptr};
987   Data data_;
988 };
989
990 /**
991  * A LockedPtr keeps a Synchronized<T> object locked for the duration of
992  * LockedPtr's existence.
993  *
994  * It provides access the datum's members directly by using operator->() and
995  * operator*().
996  *
997  * The LockPolicy parameter controls whether or not the lock is acquired in
998  * exclusive or shared mode.
999  */
1000 template <class SynchronizedType, class LockPolicy>
1001 class LockedPtr : public LockedPtrBase<
1002                       SynchronizedType,
1003                       typename SynchronizedType::MutexType,
1004                       LockPolicy> {
1005  private:
1006   using Base = LockedPtrBase<
1007       SynchronizedType,
1008       typename SynchronizedType::MutexType,
1009       LockPolicy>;
1010   using UnlockerData = typename Base::UnlockerData;
1011   // CDataType is the DataType with the appropriate const-qualification
1012   using CDataType = detail::SynchronizedDataType<SynchronizedType>;
1013
1014  public:
1015   using DataType = typename SynchronizedType::DataType;
1016   using MutexType = typename SynchronizedType::MutexType;
1017   using Synchronized = typename std::remove_const<SynchronizedType>::type;
1018   friend class ScopedUnlocker<SynchronizedType, LockPolicy>;
1019
1020   /**
1021    * Creates an uninitialized LockedPtr.
1022    *
1023    * Dereferencing an uninitialized LockedPtr is not allowed.
1024    */
1025   LockedPtr() {}
1026
1027   /**
1028    * Takes a Synchronized<T> and locks it.
1029    */
1030   explicit LockedPtr(SynchronizedType* parent) : Base(parent) {}
1031
1032   /**
1033    * Takes a Synchronized<T> and attempts to lock it, within the specified
1034    * timeout.
1035    *
1036    * Blocks until the lock is acquired or until the specified timeout expires.
1037    * If the timeout expired without acquiring the lock, the LockedPtr will be
1038    * null, and LockedPtr::isNull() will return true.
1039    */
1040   template <class Rep, class Period>
1041   LockedPtr(
1042       SynchronizedType* parent,
1043       const std::chrono::duration<Rep, Period>& timeout)
1044       : Base(parent, timeout) {}
1045
1046   /**
1047    * Move constructor.
1048    */
1049   LockedPtr(LockedPtr&& rhs) noexcept = default;
1050
1051   /**
1052    * Move assignment operator.
1053    */
1054   LockedPtr& operator=(LockedPtr&& rhs) noexcept = default;
1055
1056   /*
1057    * Copy constructor and assignment operator are deleted.
1058    */
1059   LockedPtr(const LockedPtr& rhs) = delete;
1060   LockedPtr& operator=(const LockedPtr& rhs) = delete;
1061
1062   /**
1063    * Destructor releases.
1064    */
1065   ~LockedPtr() {}
1066
1067   /**
1068    * Check if this LockedPtr is uninitialized, or points to valid locked data.
1069    *
1070    * This method can be used to check if a timed-acquire operation succeeded.
1071    * If an acquire operation times out it will result in a null LockedPtr.
1072    *
1073    * A LockedPtr is always either null, or holds a lock to valid data.
1074    * Methods such as scopedUnlock() reset the LockedPtr to null for the
1075    * duration of the unlock.
1076    */
1077   bool isNull() const {
1078     return this->parent_ == nullptr;
1079   }
1080
1081   /**
1082    * Explicit boolean conversion.
1083    *
1084    * Returns !isNull()
1085    */
1086   explicit operator bool() const {
1087     return this->parent_ != nullptr;
1088   }
1089
1090   /**
1091    * Access the locked data.
1092    *
1093    * This method should only be used if the LockedPtr is valid.
1094    */
1095   CDataType* operator->() const {
1096     return &this->parent_->datum_;
1097   }
1098
1099   /**
1100    * Access the locked data.
1101    *
1102    * This method should only be used if the LockedPtr is valid.
1103    */
1104   CDataType& operator*() const {
1105     return this->parent_->datum_;
1106   }
1107
1108   /**
1109    * Temporarily unlock the LockedPtr, and reset it to null.
1110    *
1111    * Returns an helper object that will re-lock and restore the LockedPtr when
1112    * the helper is destroyed.  The LockedPtr may not be dereferenced for as
1113    * long as this helper object exists.
1114    */
1115   ScopedUnlocker<SynchronizedType, LockPolicy> scopedUnlock() {
1116     return ScopedUnlocker<SynchronizedType, LockPolicy>(this);
1117   }
1118
1119   /***************************************************************************
1120    * Upgradable lock methods.
1121    * These are disabled via SFINAE when the mutex is not upgradable
1122    **************************************************************************/
1123   /**
1124    * Move the locked ptr from an upgrade state to an exclusive state.  The
1125    * current lock is left in a null state.
1126    */
1127   template <
1128       typename SyncType = SynchronizedType,
1129       typename = typename std::enable_if<
1130           LockTraits<typename SyncType::MutexType>::is_upgrade>::type>
1131   LockedPtr<SynchronizedType, LockPolicyFromUpgradeToExclusive>
1132   moveFromUpgradeToWrite() {
1133     auto* parent_to_pass_on = this->parent_;
1134     this->parent_ = nullptr;
1135     return LockedPtr<SynchronizedType, LockPolicyFromUpgradeToExclusive>(
1136         parent_to_pass_on);
1137   }
1138
1139   /**
1140    * Move the locked ptr from an exclusive state to an upgrade state.  The
1141    * current lock is left in a null state.
1142    */
1143   template <
1144       typename SyncType = SynchronizedType,
1145       typename = typename std::enable_if<
1146           LockTraits<typename SyncType::MutexType>::is_upgrade>::type>
1147   LockedPtr<SynchronizedType, LockPolicyFromExclusiveToUpgrade>
1148   moveFromWriteToUpgrade() {
1149     auto* parent_to_pass_on = this->parent_;
1150     this->parent_ = nullptr;
1151     return LockedPtr<SynchronizedType, LockPolicyFromExclusiveToUpgrade>(
1152         parent_to_pass_on);
1153   }
1154
1155   /**
1156    * Move the locked ptr from an upgrade state to a shared state.  The
1157    * current lock is left in a null state.
1158    */
1159   template <
1160       typename SyncType = SynchronizedType,
1161       typename = typename std::enable_if<
1162           LockTraits<typename SyncType::MutexType>::is_upgrade>::type>
1163   LockedPtr<SynchronizedType, LockPolicyFromUpgradeToShared>
1164   moveFromUpgradeToRead() {
1165     auto* parent_to_pass_on = this->parent_;
1166     this->parent_ = nullptr;
1167     return LockedPtr<SynchronizedType, LockPolicyFromUpgradeToShared>(
1168         parent_to_pass_on);
1169   }
1170
1171   /**
1172    * Move the locked ptr from an exclusive state to a shared state.  The
1173    * current lock is left in a null state.
1174    */
1175   template <
1176       typename SyncType = SynchronizedType,
1177       typename = typename std::enable_if<
1178           LockTraits<typename SyncType::MutexType>::is_upgrade>::type>
1179   LockedPtr<SynchronizedType, LockPolicyFromExclusiveToShared>
1180   moveFromWriteToRead() {
1181     auto* parent_to_pass_on = this->parent_;
1182     this->parent_ = nullptr;
1183     return LockedPtr<SynchronizedType, LockPolicyFromExclusiveToShared>(
1184         parent_to_pass_on);
1185   }
1186 };
1187
1188 /**
1189  * LockedGuardPtr is a simplified version of LockedPtr.
1190  *
1191  * It is non-movable, and supports fewer features than LockedPtr.  However, it
1192  * is ever-so-slightly more performant than LockedPtr.  (The destructor can
1193  * unconditionally release the lock, without requiring a conditional branch.)
1194  *
1195  * The relationship between LockedGuardPtr and LockedPtr is similar to that
1196  * between std::lock_guard and std::unique_lock.
1197  */
1198 template <class SynchronizedType, class LockPolicy>
1199 class LockedGuardPtr {
1200  private:
1201   // CDataType is the DataType with the appropriate const-qualification
1202   using CDataType = detail::SynchronizedDataType<SynchronizedType>;
1203
1204  public:
1205   using DataType = typename SynchronizedType::DataType;
1206   using MutexType = typename SynchronizedType::MutexType;
1207   using Synchronized = typename std::remove_const<SynchronizedType>::type;
1208
1209   LockedGuardPtr() = delete;
1210
1211   /**
1212    * Takes a Synchronized<T> and locks it.
1213    */
1214   explicit LockedGuardPtr(SynchronizedType* parent) : parent_(parent) {
1215     LockPolicy::lock(parent_->mutex_);
1216   }
1217
1218   /**
1219    * Destructor releases.
1220    */
1221   ~LockedGuardPtr() {
1222     LockPolicy::unlock(parent_->mutex_);
1223   }
1224
1225   /**
1226    * Access the locked data.
1227    */
1228   CDataType* operator->() const {
1229     return &parent_->datum_;
1230   }
1231
1232   /**
1233    * Access the locked data.
1234    */
1235   CDataType& operator*() const {
1236     return parent_->datum_;
1237   }
1238
1239  private:
1240   // This is the entire state of LockedGuardPtr.
1241   SynchronizedType* const parent_{nullptr};
1242 };
1243
1244 /**
1245  * Acquire locks for multiple Synchronized<T> objects, in a deadlock-safe
1246  * manner.
1247  *
1248  * The locks are acquired in order from lowest address to highest address.
1249  * (Note that this is not necessarily the same algorithm used by std::lock().)
1250  *
1251  * For parameters that are const and support shared locks, a read lock is
1252  * acquired.  Otherwise an exclusive lock is acquired.
1253  *
1254  * TODO: Extend acquireLocked() with variadic template versions that
1255  * allow for more than 2 Synchronized arguments.  (I haven't given too much
1256  * thought about how to implement this.  It seems like it would be rather
1257  * complicated, but I think it should be possible.)
1258  */
1259 template <class Sync1, class Sync2>
1260 std::tuple<detail::LockedPtrType<Sync1>, detail::LockedPtrType<Sync2>>
1261 acquireLocked(Sync1& l1, Sync2& l2) {
1262   if (static_cast<const void*>(&l1) < static_cast<const void*>(&l2)) {
1263     auto p1 = l1.contextualLock();
1264     auto p2 = l2.contextualLock();
1265     return std::make_tuple(std::move(p1), std::move(p2));
1266   } else {
1267     auto p2 = l2.contextualLock();
1268     auto p1 = l1.contextualLock();
1269     return std::make_tuple(std::move(p1), std::move(p2));
1270   }
1271 }
1272
1273 /**
1274  * A version of acquireLocked() that returns a std::pair rather than a
1275  * std::tuple, which is easier to use in many places.
1276  */
1277 template <class Sync1, class Sync2>
1278 std::pair<detail::LockedPtrType<Sync1>, detail::LockedPtrType<Sync2>>
1279 acquireLockedPair(Sync1& l1, Sync2& l2) {
1280   auto lockedPtrs = acquireLocked(l1, l2);
1281   return {std::move(std::get<0>(lockedPtrs)),
1282           std::move(std::get<1>(lockedPtrs))};
1283 }
1284
1285 /************************************************************************
1286  * NOTE: All APIs below this line will be deprecated in upcoming diffs.
1287  ************************************************************************/
1288
1289 // Non-member swap primitive
1290 template <class T, class M>
1291 void swap(Synchronized<T, M>& lhs, Synchronized<T, M>& rhs) {
1292   lhs.swap(rhs);
1293 }
1294
1295 /**
1296  * Disambiguate the name var by concatenating the line number of the original
1297  * point of expansion. This avoids shadowing warnings for nested
1298  * SYNCHRONIZEDs. The name is consistent if used multiple times within
1299  * another macro.
1300  * Only for internal use.
1301  */
1302 #define SYNCHRONIZED_VAR(var) FB_CONCATENATE(SYNCHRONIZED_##var##_, __LINE__)
1303
1304 /**
1305  * SYNCHRONIZED is the main facility that makes Synchronized<T>
1306  * helpful. It is a pseudo-statement that introduces a scope where the
1307  * object is locked. Inside that scope you get to access the unadorned
1308  * datum.
1309  *
1310  * Example:
1311  *
1312  * Synchronized<vector<int>> svector;
1313  * ...
1314  * SYNCHRONIZED (svector) { ... use svector as a vector<int> ... }
1315  * or
1316  * SYNCHRONIZED (v, svector) { ... use v as a vector<int> ... }
1317  *
1318  * Refer to folly/docs/Synchronized.md for a detailed explanation and more
1319  * examples.
1320  */
1321 #define SYNCHRONIZED(...)                                             \
1322   FOLLY_PUSH_WARNING                                                  \
1323   FOLLY_GCC_DISABLE_WARNING("-Wshadow")                               \
1324   FOLLY_MSVC_DISABLE_WARNING(4189) /* initialized but unreferenced */ \
1325   FOLLY_MSVC_DISABLE_WARNING(4456) /* declaration hides local */      \
1326   FOLLY_MSVC_DISABLE_WARNING(4457) /* declaration hides parameter */  \
1327   FOLLY_MSVC_DISABLE_WARNING(4458) /* declaration hides member */     \
1328   FOLLY_MSVC_DISABLE_WARNING(4459) /* declaration hides global */     \
1329   FOLLY_GCC_DISABLE_NEW_SHADOW_WARNINGS                               \
1330   if (bool SYNCHRONIZED_VAR(state) = false) {                         \
1331   } else                                                              \
1332     for (auto SYNCHRONIZED_VAR(lockedPtr) =                           \
1333              (FB_VA_GLUE(FB_ARG_2_OR_1, (__VA_ARGS__))).operator->(); \
1334          !SYNCHRONIZED_VAR(state);                                    \
1335          SYNCHRONIZED_VAR(state) = true)                              \
1336       for (auto& FB_VA_GLUE(FB_ARG_1, (__VA_ARGS__)) =                \
1337                *SYNCHRONIZED_VAR(lockedPtr).operator->();             \
1338            !SYNCHRONIZED_VAR(state);                                  \
1339            SYNCHRONIZED_VAR(state) = true)                            \
1340   FOLLY_POP_WARNING
1341
1342 #define TIMED_SYNCHRONIZED(timeout, ...)                                       \
1343   if (bool SYNCHRONIZED_VAR(state) = false) {                                  \
1344   } else                                                                       \
1345     for (auto SYNCHRONIZED_VAR(lockedPtr) =                                    \
1346              (FB_VA_GLUE(FB_ARG_2_OR_1, (__VA_ARGS__))).timedAcquire(timeout); \
1347          !SYNCHRONIZED_VAR(state);                                             \
1348          SYNCHRONIZED_VAR(state) = true)                                       \
1349       for (auto FB_VA_GLUE(FB_ARG_1, (__VA_ARGS__)) =                          \
1350                (!SYNCHRONIZED_VAR(lockedPtr)                                   \
1351                     ? nullptr                                                  \
1352                     : SYNCHRONIZED_VAR(lockedPtr).operator->());               \
1353            !SYNCHRONIZED_VAR(state);                                           \
1354            SYNCHRONIZED_VAR(state) = true)
1355
1356 /**
1357  * Similar to SYNCHRONIZED, but only uses a read lock.
1358  */
1359 #define SYNCHRONIZED_CONST(...)            \
1360   SYNCHRONIZED(                            \
1361       FB_VA_GLUE(FB_ARG_1, (__VA_ARGS__)), \
1362       (FB_VA_GLUE(FB_ARG_2_OR_1, (__VA_ARGS__))).asConst())
1363
1364 /**
1365  * Similar to TIMED_SYNCHRONIZED, but only uses a read lock.
1366  */
1367 #define TIMED_SYNCHRONIZED_CONST(timeout, ...) \
1368   TIMED_SYNCHRONIZED(                          \
1369       timeout,                                 \
1370       FB_VA_GLUE(FB_ARG_1, (__VA_ARGS__)),     \
1371       (FB_VA_GLUE(FB_ARG_2_OR_1, (__VA_ARGS__))).asConst())
1372
1373 /**
1374  * Synchronizes two Synchronized objects (they may encapsulate
1375  * different data). Synchronization is done in increasing address of
1376  * object order, so there is no deadlock risk.
1377  */
1378 #define SYNCHRONIZED_DUAL(n1, e1, n2, e2)                                      \
1379   if (bool SYNCHRONIZED_VAR(state) = false) {                                  \
1380   } else                                                                       \
1381     for (auto SYNCHRONIZED_VAR(ptrs) = acquireLockedPair(e1, e2);              \
1382          !SYNCHRONIZED_VAR(state);                                             \
1383          SYNCHRONIZED_VAR(state) = true)                                       \
1384       for (auto& n1 = *SYNCHRONIZED_VAR(ptrs).first; !SYNCHRONIZED_VAR(state); \
1385            SYNCHRONIZED_VAR(state) = true)                                     \
1386         for (auto& n2 = *SYNCHRONIZED_VAR(ptrs).second;                        \
1387              !SYNCHRONIZED_VAR(state);                                         \
1388              SYNCHRONIZED_VAR(state) = true)
1389
1390 } /* namespace folly */