Merge pull request #860 from notlesh/null_mutex_clarity

Null mutex clarity (via comments / log statement)

llarp/util/thread/threading.hpp

@@ -31,9 +31,20 @@ namespace llarp
   namespace util
   {
     /// a mutex that does nothing
+    ///
+    /// this exists to convert mutexes that were initially in use (but may no
+    /// longer be necessary) into no-op placeholders (except in debug mode
+    /// where they complain loudly when they are actually accessed across
+    /// different threads; see below).
+    ///
+    /// the idea is to "turn off" the mutexes and see where they are actually
+    /// needed.
     struct LOCKABLE NullMutex
     {
 #ifdef LOKINET_DEBUG
+      /// in debug mode, we implement lock() to enforce that any lock is only
+      /// used from a single thread. the point of this is to identify locks that
+      /// are actually needed by dying a painful death when used across threads
       mutable absl::optional< std::thread::id > m_id;
       void
       lock() const
@@ -44,9 +55,12 @@ namespace llarp
         }
         else if(m_id.value() != std::this_thread::get_id())
         {
-          std::cerr << "NullMutex " << this << " was locked by "
+          std::cerr << "NullMutex " << this
+                    << " was used across threads: locked by "
                     << std::this_thread::get_id()
                     << " and was previously locked by " << m_id.value() << "\n";
+          // if you're encountering this abort() call, you may have discovered a
+          // case where a NullMutex should be reverted to a "real mutex"
           std::abort();
         }
       }