Merge bitcoin/bitcoin#27116: doc: clarify that LOCK() internally checks whether the mutex is held

91d08889218e06631f43a3dab0bae576aa46e43c sync: unpublish LocksHeld() which is used only in sync.cpp (Vasil Dimov)
3df37e0c78c3d5139c963a74eda56c331355ef72 doc: clarify that LOCK() does AssertLockNotHeld() internally (Vasil Dimov)

Pull request description:

  Constructs like

  ```cpp
  AssertLockNotHeld(m);
  LOCK(m);
  ```

  are equivalent to (almost, modulo some logging differences, see below)

  ```cpp
  LOCK(m);
  ```

  for non-recursive mutexes, so it is ok to omit `AssertLockNotHeld()` in such cases. Requests to do the former keep coming during review process. `developer-notes.md` explicitly states "Combine annotations in function declarations with run-time asserts in function definitions", but that seems to be too strong or unclear. `LOCK()` is also a run-time assert in this case.

  Also remove `LocksHeld()` from the public interface in `sync.h` since it is only used in `sync.cpp`.

ACKs for top commit:
  achow101:
    ACK 91d08889218e06631f43a3dab0bae576aa46e43c
  hebasto:
    ACK 91d08889218e06631f43a3dab0bae576aa46e43c, I have reviewed the code and it looks OK.

Tree-SHA512: c4b7ef2c0bfeb28d1c4f55f497810f629873137e02f5a92137c02cb1ff603ac76473dcd2171e594491494a5cb87b8c0c803e06b86f190d4acb231791e28e802d

2 files changed, 1 insertions, 2 deletions

diff --git a/src/sync.cpp b/src/sync.cpp
index 4621805653..58752a9f18 100644
--- a/src/sync.cpp
+++ b/src/sync.cpp
@@ -246,7 +246,7 @@ void LeaveCritical()
     pop_lock();
 }
 
-std::string LocksHeld()
+static std::string LocksHeld()
 {
     LockData& lockdata = GetLockData();
     std::lock_guard<std::mutex> lock(lockdata.dd_mutex);
diff --git a/src/sync.h b/src/sync.h
index 45d40b5fdc..dc63e3f2d0 100644
--- a/src/sync.h
+++ b/src/sync.h
@@ -57,7 +57,6 @@ template <typename MutexType>
 void EnterCritical(const char* pszName, const char* pszFile, int nLine, MutexType* cs, bool fTry = false);
 void LeaveCritical();
 void CheckLastCritical(void* cs, std::string& lockname, const char* guardname, const char* file, int line);
-std::string LocksHeld();
 template <typename MutexType>
 void AssertLockHeldInternal(const char* pszName, const char* pszFile, int nLine, MutexType* cs) EXCLUSIVE_LOCKS_REQUIRED(cs);
 template <typename MutexType>