LCOV - code coverage report
Current view: top level - src - sync.h (source / functions) Hit Total Coverage
Test: fuzz_coverage.info Lines: 59 125 47.2 %
Date: 2023-10-05 12:38:51 Functions: 37 64 57.8 %
Branches: 13 68 19.1 %

           Branch data     Line data    Source code
       1                 :            : // Copyright (c) 2009-2010 Satoshi Nakamoto
       2                 :            : // Copyright (c) 2009-2022 The Bitcoin Core developers
       3                 :            : // Distributed under the MIT software license, see the accompanying
       4                 :            : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
       5                 :            : 
       6                 :            : #ifndef BITCOIN_SYNC_H
       7                 :            : #define BITCOIN_SYNC_H
       8                 :            : 
       9                 :            : #ifdef DEBUG_LOCKCONTENTION
      10                 :            : #include <logging.h>
      11                 :            : #include <logging/timer.h>
      12                 :            : #endif
      13                 :            : 
      14                 :            : #include <threadsafety.h> // IWYU pragma: export
      15                 :            : #include <util/macros.h>
      16                 :            : 
      17                 :            : #include <condition_variable>
      18                 :            : #include <mutex>
      19                 :            : #include <string>
      20                 :            : #include <thread>
      21                 :            : 
      22                 :            : ////////////////////////////////////////////////
      23                 :            : //                                            //
      24                 :            : // THE SIMPLE DEFINITION, EXCLUDING DEBUG CODE //
      25                 :            : //                                            //
      26                 :            : ////////////////////////////////////////////////
      27                 :            : 
      28                 :            : /*
      29                 :            : RecursiveMutex mutex;
      30                 :            :     std::recursive_mutex mutex;
      31                 :            : 
      32                 :            : LOCK(mutex);
      33                 :            :     std::unique_lock<std::recursive_mutex> criticalblock(mutex);
      34                 :            : 
      35                 :            : LOCK2(mutex1, mutex2);
      36                 :            :     std::unique_lock<std::recursive_mutex> criticalblock1(mutex1);
      37                 :            :     std::unique_lock<std::recursive_mutex> criticalblock2(mutex2);
      38                 :            : 
      39                 :            : TRY_LOCK(mutex, name);
      40                 :            :     std::unique_lock<std::recursive_mutex> name(mutex, std::try_to_lock_t);
      41                 :            : 
      42                 :            : ENTER_CRITICAL_SECTION(mutex); // no RAII
      43                 :            :     mutex.lock();
      44                 :            : 
      45                 :            : LEAVE_CRITICAL_SECTION(mutex); // no RAII
      46                 :            :     mutex.unlock();
      47                 :            :  */
      48                 :            : 
      49                 :            : ///////////////////////////////
      50                 :            : //                           //
      51                 :            : // THE ACTUAL IMPLEMENTATION //
      52                 :            : //                           //
      53                 :            : ///////////////////////////////
      54                 :            : 
      55                 :            : #ifdef DEBUG_LOCKORDER
      56                 :            : template <typename MutexType>
      57                 :            : void EnterCritical(const char* pszName, const char* pszFile, int nLine, MutexType* cs, bool fTry = false);
      58                 :            : void LeaveCritical();
      59                 :            : void CheckLastCritical(void* cs, std::string& lockname, const char* guardname, const char* file, int line);
      60                 :            : std::string LocksHeld();
      61                 :            : template <typename MutexType>
      62                 :            : void AssertLockHeldInternal(const char* pszName, const char* pszFile, int nLine, MutexType* cs) EXCLUSIVE_LOCKS_REQUIRED(cs);
      63                 :            : template <typename MutexType>
      64                 :            : void AssertLockNotHeldInternal(const char* pszName, const char* pszFile, int nLine, MutexType* cs) LOCKS_EXCLUDED(cs);
      65                 :            : void DeleteLock(void* cs);
      66                 :            : bool LockStackEmpty();
      67                 :            : 
      68                 :            : /**
      69                 :            :  * Call abort() if a potential lock order deadlock bug is detected, instead of
      70                 :            :  * just logging information and throwing a logic_error. Defaults to true, and
      71                 :            :  * set to false in DEBUG_LOCKORDER unit tests.
      72                 :            :  */
      73                 :            : extern bool g_debug_lockorder_abort;
      74                 :            : #else
      75                 :            : template <typename MutexType>
      76                 :     393283 : inline void EnterCritical(const char* pszName, const char* pszFile, int nLine, MutexType* cs, bool fTry = false) {}
      77                 :     393283 : inline void LeaveCritical() {}
      78                 :          3 : inline void CheckLastCritical(void* cs, std::string& lockname, const char* guardname, const char* file, int line) {}
      79                 :            : template <typename MutexType>
      80                 :    2110485 : inline void AssertLockHeldInternal(const char* pszName, const char* pszFile, int nLine, MutexType* cs) EXCLUSIVE_LOCKS_REQUIRED(cs) {}
      81                 :            : template <typename MutexType>
      82                 :     140250 : void AssertLockNotHeldInternal(const char* pszName, const char* pszFile, int nLine, MutexType* cs) LOCKS_EXCLUDED(cs) {}
      83                 :     183761 : inline void DeleteLock(void* cs) {}
      84                 :          0 : inline bool LockStackEmpty() { return true; }
      85                 :            : #endif
      86                 :            : 
      87                 :            : /**
      88                 :            :  * Template mixin that adds -Wthread-safety locking annotations and lock order
      89                 :            :  * checking to a subset of the mutex API.
      90                 :            :  */
      91                 :            : template <typename PARENT>
      92                 :            : class LOCKABLE AnnotatedMixin : public PARENT
      93                 :            : {
      94                 :            : public:
      95                 :     183761 :     ~AnnotatedMixin() {
      96         [ +  - ]:     183761 :         DeleteLock((void*)this);
      97                 :     183761 :     }
      98                 :            : 
      99                 :          0 :     void lock() EXCLUSIVE_LOCK_FUNCTION()
     100                 :            :     {
     101                 :          0 :         PARENT::lock();
     102                 :          0 :     }
     103                 :            : 
     104                 :          0 :     void unlock() UNLOCK_FUNCTION()
     105                 :            :     {
     106                 :          0 :         PARENT::unlock();
     107                 :          0 :     }
     108                 :            : 
     109                 :          0 :     bool try_lock() EXCLUSIVE_TRYLOCK_FUNCTION(true)
     110                 :            :     {
     111                 :          0 :         return PARENT::try_lock();
     112                 :            :     }
     113                 :            : 
     114                 :            :     using unique_lock = std::unique_lock<PARENT>;
     115                 :            : #ifdef __clang__
     116                 :            :     //! For negative capabilities in the Clang Thread Safety Analysis.
     117                 :            :     //! A negative requirement uses the EXCLUSIVE_LOCKS_REQUIRED attribute, in conjunction
     118                 :            :     //! with the ! operator, to indicate that a mutex should not be held.
     119                 :            :     const AnnotatedMixin& operator!() const { return *this; }
     120                 :            : #endif // __clang__
     121                 :            : };
     122                 :            : 
     123                 :            : /**
     124                 :            :  * Wrapped mutex: supports recursive locking, but no waiting
     125                 :            :  * TODO: We should move away from using the recursive lock by default.
     126                 :            :  */
     127                 :            : using RecursiveMutex = AnnotatedMixin<std::recursive_mutex>;
     128                 :            : 
     129                 :            : /** Wrapped mutex: supports waiting but not recursive locking */
     130                 :            : using Mutex = AnnotatedMixin<std::mutex>;
     131                 :            : 
     132                 :            : /** Different type to mark Mutex at global scope
     133                 :            :  *
     134                 :            :  * Thread safety analysis can't handle negative assertions about mutexes
     135                 :            :  * with global scope well, so mark them with a separate type, and
     136                 :            :  * eventually move all the mutexes into classes so they are not globally
     137                 :            :  * visible.
     138                 :            :  *
     139                 :            :  * See: https://github.com/bitcoin/bitcoin/pull/20272#issuecomment-720755781
     140                 :            :  */
     141                 :            : class GlobalMutex : public Mutex { };
     142                 :            : 
     143                 :            : #define AssertLockHeld(cs) AssertLockHeldInternal(#cs, __FILE__, __LINE__, &cs)
     144                 :            : 
     145                 :     140248 : inline void AssertLockNotHeldInline(const char* name, const char* file, int line, Mutex* cs) EXCLUSIVE_LOCKS_REQUIRED(!cs) { AssertLockNotHeldInternal(name, file, line, cs); }
     146                 :          2 : inline void AssertLockNotHeldInline(const char* name, const char* file, int line, RecursiveMutex* cs) LOCKS_EXCLUDED(cs) { AssertLockNotHeldInternal(name, file, line, cs); }
     147                 :            : inline void AssertLockNotHeldInline(const char* name, const char* file, int line, GlobalMutex* cs) LOCKS_EXCLUDED(cs) { AssertLockNotHeldInternal(name, file, line, cs); }
     148                 :            : #define AssertLockNotHeld(cs) AssertLockNotHeldInline(#cs, __FILE__, __LINE__, &cs)
     149                 :            : 
     150                 :            : /** Wrapper around std::unique_lock style lock for MutexType. */
     151                 :            : template <typename MutexType>
     152                 :            : class SCOPED_LOCKABLE UniqueLock : public MutexType::unique_lock
     153                 :            : {
     154                 :            : private:
     155                 :            :     using Base = typename MutexType::unique_lock;
     156                 :            : 
     157                 :     393280 :     void Enter(const char* pszName, const char* pszFile, int nLine)
     158                 :            :     {
     159                 :     393280 :         EnterCritical(pszName, pszFile, nLine, Base::mutex());
     160                 :            : #ifdef DEBUG_LOCKCONTENTION
     161                 :            :         if (Base::try_lock()) return;
     162                 :            :         LOG_TIME_MICROS_WITH_CATEGORY(strprintf("lock contention %s, %s:%d", pszName, pszFile, nLine), BCLog::LOCK);
     163                 :            : #endif
     164                 :     393280 :         Base::lock();
     165                 :     393280 :     }
     166                 :            : 
     167                 :          0 :     bool TryEnter(const char* pszName, const char* pszFile, int nLine)
     168                 :            :     {
     169                 :          0 :         EnterCritical(pszName, pszFile, nLine, Base::mutex(), true);
     170   [ #  #  #  #  :          0 :         if (Base::try_lock()) {
                   #  # ]
     171                 :          0 :             return true;
     172                 :            :         }
     173                 :          0 :         LeaveCritical();
     174                 :          0 :         return false;
     175                 :          0 :     }
     176                 :            : 
     177                 :            : public:
     178                 :     393279 :     UniqueLock(MutexType& mutexIn, const char* pszName, const char* pszFile, int nLine, bool fTry = false) EXCLUSIVE_LOCK_FUNCTION(mutexIn) : Base(mutexIn, std::defer_lock)
     179                 :            :     {
     180   [ -  +  #  #  :     393279 :         if (fTry)
                   #  # ]
     181   [ #  #  #  #  :          0 :             TryEnter(pszName, pszFile, nLine);
                   #  # ]
     182                 :            :         else
     183   [ +  -  #  #  :     393279 :             Enter(pszName, pszFile, nLine);
                   #  # ]
     184                 :     393279 :     }
     185                 :            : 
     186                 :          1 :     UniqueLock(MutexType* pmutexIn, const char* pszName, const char* pszFile, int nLine, bool fTry = false) EXCLUSIVE_LOCK_FUNCTION(pmutexIn)
     187                 :            :     {
     188         [ +  - ]:          1 :         if (!pmutexIn) return;
     189                 :            : 
     190                 :          1 :         *static_cast<Base*>(this) = Base(*pmutexIn, std::defer_lock);
     191         [ +  - ]:          1 :         if (fTry)
     192         [ #  # ]:          0 :             TryEnter(pszName, pszFile, nLine);
     193                 :            :         else
     194         [ +  - ]:          1 :             Enter(pszName, pszFile, nLine);
     195                 :          1 :     }
     196                 :            : 
     197                 :     393283 :     ~UniqueLock() UNLOCK_FUNCTION()
     198                 :            :     {
     199   [ +  +  #  #  :     393283 :         if (Base::owns_lock())
                   #  # ]
     200                 :     393280 :             LeaveCritical();
     201                 :     393283 :     }
     202                 :            : 
     203                 :          0 :     operator bool()
     204                 :            :     {
     205                 :          0 :         return Base::owns_lock();
     206                 :            :     }
     207                 :            : 
     208                 :            : protected:
     209                 :            :     // needed for reverse_lock
     210                 :          3 :     UniqueLock() { }
     211                 :            : 
     212                 :            : public:
     213                 :            :     /**
     214                 :            :      * An RAII-style reverse lock. Unlocks on construction and locks on destruction.
     215                 :            :      */
     216                 :            :     class reverse_lock {
     217                 :            :     public:
     218         [ +  - ]:          3 :         explicit reverse_lock(UniqueLock& _lock, const char* _guardname, const char* _file, int _line) : lock(_lock), file(_file), line(_line) {
     219         [ +  - ]:          3 :             CheckLastCritical((void*)lock.mutex(), lockname, _guardname, _file, _line);
     220         [ +  - ]:          3 :             lock.unlock();
     221                 :          3 :             LeaveCritical();
     222                 :          3 :             lock.swap(templock);
     223                 :          3 :         }
     224                 :            : 
     225                 :          3 :         ~reverse_lock() {
     226                 :          3 :             templock.swap(lock);
     227                 :          3 :             EnterCritical(lockname.c_str(), file.c_str(), line, lock.mutex());
     228         [ +  - ]:          3 :             lock.lock();
     229                 :          3 :         }
     230                 :            : 
     231                 :            :      private:
     232                 :            :         reverse_lock(reverse_lock const&);
     233                 :            :         reverse_lock& operator=(reverse_lock const&);
     234                 :            : 
     235                 :            :         UniqueLock& lock;
     236                 :            :         UniqueLock templock;
     237                 :            :         std::string lockname;
     238                 :            :         const std::string file;
     239                 :            :         const int line;
     240                 :            :      };
     241                 :            :      friend class reverse_lock;
     242                 :            : };
     243                 :            : 
     244                 :            : #define REVERSE_LOCK(g) typename std::decay<decltype(g)>::type::reverse_lock UNIQUE_NAME(revlock)(g, #g, __FILE__, __LINE__)
     245                 :            : 
     246                 :            : // When locking a Mutex, require negative capability to ensure the lock
     247                 :            : // is not already held
     248                 :     258599 : inline Mutex& MaybeCheckNotHeld(Mutex& cs) EXCLUSIVE_LOCKS_REQUIRED(!cs) LOCK_RETURNED(cs) { return cs; }
     249                 :            : inline Mutex* MaybeCheckNotHeld(Mutex* cs) EXCLUSIVE_LOCKS_REQUIRED(!cs) LOCK_RETURNED(cs) { return cs; }
     250                 :            : 
     251                 :            : // When locking a GlobalMutex or RecursiveMutex, just check it is not
     252                 :            : // locked in the surrounding scope.
     253                 :            : template <typename MutexType>
     254                 :     140356 : inline MutexType& MaybeCheckNotHeld(MutexType& m) LOCKS_EXCLUDED(m) LOCK_RETURNED(m) { return m; }
     255                 :            : template <typename MutexType>
     256                 :          1 : inline MutexType* MaybeCheckNotHeld(MutexType* m) LOCKS_EXCLUDED(m) LOCK_RETURNED(m) { return m; }
     257                 :            : 
     258                 :            : #define LOCK(cs) UniqueLock UNIQUE_NAME(criticalblock)(MaybeCheckNotHeld(cs), #cs, __FILE__, __LINE__)
     259                 :            : #define LOCK2(cs1, cs2)                                               \
     260                 :            :     UniqueLock criticalblock1(MaybeCheckNotHeld(cs1), #cs1, __FILE__, __LINE__); \
     261                 :            :     UniqueLock criticalblock2(MaybeCheckNotHeld(cs2), #cs2, __FILE__, __LINE__)
     262                 :            : #define TRY_LOCK(cs, name) UniqueLock name(MaybeCheckNotHeld(cs), #cs, __FILE__, __LINE__, true)
     263                 :            : #define WAIT_LOCK(cs, name) UniqueLock name(MaybeCheckNotHeld(cs), #cs, __FILE__, __LINE__)
     264                 :            : 
     265                 :            : #define ENTER_CRITICAL_SECTION(cs)                            \
     266                 :            :     {                                                         \
     267                 :            :         EnterCritical(#cs, __FILE__, __LINE__, &cs); \
     268                 :            :         (cs).lock();                                          \
     269                 :            :     }
     270                 :            : 
     271                 :            : #define LEAVE_CRITICAL_SECTION(cs)                                          \
     272                 :            :     {                                                                       \
     273                 :            :         std::string lockname;                                               \
     274                 :            :         CheckLastCritical((void*)(&cs), lockname, #cs, __FILE__, __LINE__); \
     275                 :            :         (cs).unlock();                                                      \
     276                 :            :         LeaveCritical();                                                    \
     277                 :            :     }
     278                 :            : 
     279                 :            : //! Run code while locking a mutex.
     280                 :            : //!
     281                 :            : //! Examples:
     282                 :            : //!
     283                 :            : //!   WITH_LOCK(cs, shared_val = shared_val + 1);
     284                 :            : //!
     285                 :            : //!   int val = WITH_LOCK(cs, return shared_val);
     286                 :            : //!
     287                 :            : //! Note:
     288                 :            : //!
     289                 :            : //! Since the return type deduction follows that of decltype(auto), while the
     290                 :            : //! deduced type of:
     291                 :            : //!
     292                 :            : //!   WITH_LOCK(cs, return {int i = 1; return i;});
     293                 :            : //!
     294                 :            : //! is int, the deduced type of:
     295                 :            : //!
     296                 :            : //!   WITH_LOCK(cs, return {int j = 1; return (j);});
     297                 :            : //!
     298                 :            : //! is &int, a reference to a local variable
     299                 :            : //!
     300                 :            : //! The above is detectable at compile-time with the -Wreturn-local-addr flag in
     301                 :            : //! gcc and the -Wreturn-stack-address flag in clang, both enabled by default.
     302                 :            : #define WITH_LOCK(cs, code) (MaybeCheckNotHeld(cs), [&]() -> decltype(auto) { LOCK(cs); code; }())
     303                 :            : 
     304                 :            : /** An implementation of a semaphore.
     305                 :            :  *
     306                 :            :  * See https://en.wikipedia.org/wiki/Semaphore_(programming)
     307                 :            :  */
     308                 :            : class CSemaphore
     309                 :            : {
     310                 :            : private:
     311                 :            :     std::condition_variable condition;
     312                 :            :     std::mutex mutex;
     313                 :            :     int value;
     314                 :            : 
     315                 :            : public:
     316                 :          0 :     explicit CSemaphore(int init) noexcept : value(init) {}
     317                 :            : 
     318                 :            :     // Disallow default construct, copy, move.
     319                 :            :     CSemaphore() = delete;
     320                 :            :     CSemaphore(const CSemaphore&) = delete;
     321                 :            :     CSemaphore(CSemaphore&&) = delete;
     322                 :            :     CSemaphore& operator=(const CSemaphore&) = delete;
     323                 :            :     CSemaphore& operator=(CSemaphore&&) = delete;
     324                 :            : 
     325                 :          0 :     void wait() noexcept
     326                 :            :     {
     327         [ #  # ]:          0 :         std::unique_lock<std::mutex> lock(mutex);
     328         [ #  # ]:          0 :         condition.wait(lock, [&]() { return value >= 1; });
     329                 :          0 :         value--;
     330                 :          0 :     }
     331                 :            : 
     332                 :          0 :     bool try_wait() noexcept
     333                 :            :     {
     334         [ #  # ]:          0 :         std::lock_guard<std::mutex> lock(mutex);
     335         [ #  # ]:          0 :         if (value < 1) {
     336                 :          0 :             return false;
     337                 :            :         }
     338                 :          0 :         value--;
     339                 :          0 :         return true;
     340                 :          0 :     }
     341                 :            : 
     342                 :          0 :     void post() noexcept
     343                 :            :     {
     344                 :            :         {
     345         [ #  # ]:          0 :             std::lock_guard<std::mutex> lock(mutex);
     346                 :          0 :             value++;
     347                 :          0 :         }
     348                 :          0 :         condition.notify_one();
     349                 :          0 :     }
     350                 :            : };
     351                 :            : 
     352                 :            : /** RAII-style semaphore lock */
     353                 :            : class CSemaphoreGrant
     354                 :            : {
     355                 :            : private:
     356                 :            :     CSemaphore* sem;
     357                 :            :     bool fHaveGrant;
     358                 :            : 
     359                 :            : public:
     360                 :          0 :     void Acquire() noexcept
     361                 :            :     {
     362         [ #  # ]:          0 :         if (fHaveGrant) {
     363                 :          0 :             return;
     364                 :            :         }
     365                 :          0 :         sem->wait();
     366                 :          0 :         fHaveGrant = true;
     367                 :          0 :     }
     368                 :            : 
     369                 :      35342 :     void Release() noexcept
     370                 :            :     {
     371         [ +  - ]:      35342 :         if (!fHaveGrant) {
     372                 :      35342 :             return;
     373                 :            :         }
     374                 :          0 :         sem->post();
     375                 :          0 :         fHaveGrant = false;
     376                 :      35342 :     }
     377                 :            : 
     378                 :          0 :     bool TryAcquire() noexcept
     379                 :            :     {
     380   [ #  #  #  # ]:          0 :         if (!fHaveGrant && sem->try_wait()) {
     381                 :          0 :             fHaveGrant = true;
     382                 :          0 :         }
     383                 :          0 :         return fHaveGrant;
     384                 :            :     }
     385                 :            : 
     386                 :            :     // Disallow copy.
     387                 :            :     CSemaphoreGrant(const CSemaphoreGrant&) = delete;
     388                 :            :     CSemaphoreGrant& operator=(const CSemaphoreGrant&) = delete;
     389                 :            : 
     390                 :            :     // Allow move.
     391                 :          0 :     CSemaphoreGrant(CSemaphoreGrant&& other) noexcept
     392                 :            :     {
     393                 :          0 :         sem = other.sem;
     394                 :          0 :         fHaveGrant = other.fHaveGrant;
     395                 :          0 :         other.fHaveGrant = false;
     396                 :          0 :         other.sem = nullptr;
     397                 :          0 :     }
     398                 :            : 
     399                 :       6993 :     CSemaphoreGrant& operator=(CSemaphoreGrant&& other) noexcept
     400                 :            :     {
     401                 :       6993 :         Release();
     402                 :       6993 :         sem = other.sem;
     403                 :       6993 :         fHaveGrant = other.fHaveGrant;
     404                 :       6993 :         other.fHaveGrant = false;
     405                 :       6993 :         other.sem = nullptr;
     406                 :       6993 :         return *this;
     407                 :            :     }
     408                 :            : 
     409                 :      28349 :     CSemaphoreGrant() noexcept : sem(nullptr), fHaveGrant(false) {}
     410                 :            : 
     411                 :          0 :     explicit CSemaphoreGrant(CSemaphore& sema, bool fTry = false) noexcept : sem(&sema), fHaveGrant(false)
     412                 :            :     {
     413         [ #  # ]:          0 :         if (fTry) {
     414                 :          0 :             TryAcquire();
     415                 :          0 :         } else {
     416                 :          0 :             Acquire();
     417                 :            :         }
     418                 :          0 :     }
     419                 :            : 
     420                 :      28349 :     ~CSemaphoreGrant()
     421                 :            :     {
     422                 :      28349 :         Release();
     423                 :      28349 :     }
     424                 :            : 
     425                 :          0 :     explicit operator bool() const noexcept
     426                 :            :     {
     427                 :          0 :         return fHaveGrant;
     428                 :            :     }
     429                 :            : };
     430                 :            : 
     431                 :            : #endif // BITCOIN_SYNC_H

Generated by: LCOV version 1.14