mark nested-name lock-holder types as deprecated

Summary: The nested-name lock-holder types `{mutex}::ReadHolder`, `{mutex}::WriteHolder`, and `{mutex}::UpgradeHolder` are deprecated in favor of the canonical lock-holder types `std::shared_lock`, `std::unique_lock`, and `folly::upgrade_lock` respectively.

Reviewed By: ot, malanka, dmm-fb

Differential Revision: D52371884

fbshipit-source-id: 2b4b87d082f9f689f7c03b01595b81b7ba935e3c

Author: yfeldblum

folly/Portability.h

@@ -86,6 +86,9 @@ constexpr bool kHasUnalignedAccess = false;
 #define FOLLY_NODISCARD
 #endif
 
+// older clang-format gets confused by [[deprecated(...)]] on class decls
+#define FOLLY_DEPRECATED(...) [[deprecated(__VA_ARGS__)]]
+
 // target
 #ifdef _MSC_VER
 #define FOLLY_TARGET_ATTRIBUTE(target)

folly/SharedMutex.h

@@ -101,13 +101,6 @@
 //    is held.  See https://github.com/boostorg/thread/blob/master/
 //      include/boost/thread/pthread/shared_mutex.hpp
 //
-//  * RWSpinLock::UpgradedHolder maps to SharedMutex::UpgradeHolder
-//    (UpgradeableHolder would be even more pedantically correct).
-//    SharedMutex's holders have fewer methods (no reset) and are less
-//    tolerant (promotion and downgrade crash if the donor doesn't own
-//    the lock, and you must use the default constructor rather than
-//    passing a nullptr to the pointer constructor).
-//
 // Both SharedMutex and RWSpinLock provide "exclusive", "upgrade",
 // and "shared" modes.  At all times num_threads_holding_exclusive +
 // num_threads_holding_upgrade <= 1, and num_threads_holding_exclusive ==
@@ -193,7 +186,7 @@
 // recorded the lock, which might be in the lock itself or in any of
 // the shared slots.  If you can conveniently pass state from lock
 // acquisition to release then the fastest mechanism is to std::move
-// the SharedMutex::ReadHolder instance or an SharedMutex::Token (using
+// the std::shared_lock instance or an SharedMutex::Token (using
 // lock_shared(Token&) and unlock_shared(Token&)).  The guard or token
 // will tell unlock_shared where in deferredReaders[] to look for the
 // deferred lock.  The Token-less version of unlock_shared() works in all
@@ -1433,7 +1426,7 @@ class SharedMutexImpl : std::conditional_t<
   }
 
  public:
-  class FOLLY_NODISCARD ReadHolder {
+  class FOLLY_NODISCARD FOLLY_DEPRECATED("use std::shared_lock") ReadHolder {
     using folly_is_unsafe_for_async_usage = std::true_type;
 
     ReadHolder() : lock_(nullptr) {}
@@ -1495,7 +1488,8 @@ class SharedMutexImpl : std::conditional_t<
     SharedMutexToken token_;
   };
 
-  class FOLLY_NODISCARD UpgradeHolder {
+  class FOLLY_NODISCARD FOLLY_DEPRECATED("use folly::upgrade_lock")
+      UpgradeHolder {
     using folly_is_unsafe_for_async_usage = std::true_type;
 
     UpgradeHolder() : lock_(nullptr) {}
@@ -1545,7 +1539,7 @@ class SharedMutexImpl : std::conditional_t<
     SharedMutexImpl* lock_;
   };
 
-  class FOLLY_NODISCARD WriteHolder {
+  class FOLLY_NODISCARD FOLLY_DEPRECATED("use std::unique_lock") WriteHolder {
     using folly_is_unsafe_for_async_usage = std::true_type;
 
     WriteHolder() : lock_(nullptr) {}

folly/fibers/TimedMutex.h

@@ -178,7 +178,7 @@ class TimedRWMutexImpl {
   // are any.
   void unlock_and_lock_shared();
 
-  class FOLLY_NODISCARD ReadHolder {
+  class FOLLY_NODISCARD FOLLY_DEPRECATED("use std::shared_lock") ReadHolder {
    public:
     explicit ReadHolder(TimedRWMutexImpl& lock) : lock_(&lock) {
       lock_->lock_shared();
@@ -199,7 +199,7 @@ class TimedRWMutexImpl {
     TimedRWMutexImpl* lock_;
   };
 
-  class FOLLY_NODISCARD WriteHolder {
+  class FOLLY_NODISCARD FOLLY_DEPRECATED("use std::unique_lock") WriteHolder {
    public:
     explicit WriteHolder(TimedRWMutexImpl& lock) : lock_(&lock) {
       lock_->lock();

folly/synchronization/RWSpinLock.h

@@ -309,7 +309,7 @@ class RWSpinLock {
   class FOLLY_NODISCARD UpgradedHolder;
   class FOLLY_NODISCARD WriteHolder;
 
-  class FOLLY_NODISCARD ReadHolder {
+  class FOLLY_NODISCARD FOLLY_DEPRECATED("use std::shared_lock") ReadHolder {
    public:
     explicit ReadHolder(RWSpinLock* lock) : lock_(lock) {
       if (lock_) {
@@ -376,7 +376,8 @@ class RWSpinLock {
     RWSpinLock* lock_;
   };
 
-  class FOLLY_NODISCARD UpgradedHolder {
+  class FOLLY_NODISCARD FOLLY_DEPRECATED("use folly::upgrade_lock")
+      UpgradedHolder {
    public:
     explicit UpgradedHolder(RWSpinLock* lock) : lock_(lock) {
       if (lock_) {
@@ -439,7 +440,7 @@ class RWSpinLock {
     RWSpinLock* lock_;
   };
 
-  class FOLLY_NODISCARD WriteHolder {
+  class FOLLY_NODISCARD FOLLY_DEPRECATED("use std::unique_lock") WriteHolder {
    public:
     explicit WriteHolder(RWSpinLock* lock) : lock_(lock) {
       if (lock_) {