xpcom/threads/BlockingResourceBase.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_BlockingResourceBase_h
   8 #define mozilla_BlockingResourceBase_h
   9
  10 #include "mozilla/MemoryReporting.h"
  11 #include "mozilla/ThreadLocal.h"
  12 #include "mozilla/Attributes.h"
  13
  14 #include "nscore.h"
  15 #include "nsDebug.h"
  16
  17 #include "prtypes.h"
  18
  19 #ifdef DEBUG
  20
  21 // NB: Comment this out to enable callstack tracking.
  22 #  define MOZ_CALLSTACK_DISABLED
  23
  24 #  include "prinit.h"
  25
  26 #  ifndef MOZ_CALLSTACK_DISABLED
  27 #    include "mozilla/Maybe.h"
  28 #    include "nsTArray.h"
  29 #  endif
  30
  31 #endif
  32
  33 //
  34 // This header is not meant to be included by client code.
  35 //
  36
  37 namespace mozilla {
  38
  39 #ifdef DEBUG
  40 template <class T>
  41 class DeadlockDetector;
  42 #endif
  43
  44 /**
  45  * BlockingResourceBase
  46  * Base class of resources that might block clients trying to acquire them.
  47  * Does debugging and deadlock detection in DEBUG builds.
  48  **/
  49 class BlockingResourceBase {
  50  public:
  51   // Needs to be kept in sync with kResourceTypeNames.
  52   enum BlockingResourceType {
  53     eMutex,
  54     eReentrantMonitor,
  55     eCondVar,
  56     eRecursiveMutex
  57   };
  58
  59   /**
  60    * kResourceTypeName
  61    * Human-readable version of BlockingResourceType enum.
  62    */
  63   static const char* const kResourceTypeName[];
  64
  65 #ifdef DEBUG
  66
  67   static void AssertSafeToProcessEventLoop();
  68
  69   static size_t SizeOfDeadlockDetector(MallocSizeOf aMallocSizeOf);
  70
  71   /**
  72    * Print
  73    * Write a description of this blocking resource to |aOut|.  If
  74    * the resource appears to be currently acquired, the current
  75    * acquisition context is printed and true is returned.
  76    * Otherwise, we print the context from |aFirstSeen|, the
  77    * first acquisition from which the code calling |Print()|
  78    * became interested in us, and return false.
  79    *
  80    * *NOT* thread safe.  Reads |mAcquisitionContext| without
  81    * synchronization, but this will not cause correctness
  82    * problems.
  83    *
  84    * FIXME bug 456272: hack alert: because we can't write call
  85    * contexts into strings, all info is written to stderr, but
  86    * only some info is written into |aOut|
  87    */
  88   bool Print(nsACString& aOut) const;
  89
  90   size_t SizeOfIncludingThis(MallocSizeOf aMallocSizeOf) const {
  91     // NB: |mName| is not reported as it's expected to be a static string.
  92     //     If we switch to a nsString it should be added to the tally.
  93     //     |mChainPrev| is not reported because its memory is not owned.
  94     size_t n = aMallocSizeOf(this);
  95     return n;
  96   }
  97
  98   // ``DDT'' = ``Deadlock Detector Type''
  99   typedef DeadlockDetector<BlockingResourceBase> DDT;
 100
 101  protected:
 102 #  ifdef MOZ_CALLSTACK_DISABLED
 103   typedef bool AcquisitionState;
 104 #  else
 105   // Using maybe to use emplacement as the acquisition state flag; we may not
 106   // always get a stack trace because of possible stack walk suppression or
 107   // errors, hence can't use !IsEmpty() on the array itself as indication.
 108   static size_t const kAcquisitionStateStackSize = 24;
 109   typedef Maybe<AutoTArray<void*, kAcquisitionStateStackSize> >
 110       AcquisitionState;
 111 #  endif
 112
 113   /**
 114    * BlockingResourceBase
 115    * Initialize this blocking resource.  Also hooks the resource into
 116    * instrumentation code.
 117    *
 118    * Thread safe.
 119    *
 120    * @param aName A meaningful, unique name that can be used in
 121    *              error messages, et al.
 122    * @param aType The specific type of |this|, if any.
 123    **/
 124   BlockingResourceBase(const char* aName, BlockingResourceType aType);
 125
 126   ~BlockingResourceBase();
 127
 128   /**
 129    * CheckAcquire
 130    *
 131    * Thread safe.
 132    **/
 133   void CheckAcquire();
 134
 135   /**
 136    * Acquire
 137    *
 138    * *NOT* thread safe.  Requires ownership of underlying resource.
 139    **/
 140   void Acquire();  // NS_NEEDS_RESOURCE(this)
 141
 142   /**
 143    * Release
 144    * Remove this resource from the current thread's acquisition chain.
 145    * The resource does not have to be at the front of the chain, although
 146    * it is confusing to release resources in a different order than they
 147    * are acquired.  This generates a warning.
 148    *
 149    * *NOT* thread safe.  Requires ownership of underlying resource.
 150    **/
 151   void Release();  // NS_NEEDS_RESOURCE(this)
 152
 153   /**
 154    * ResourceChainFront
 155    *
 156    * Thread safe.
 157    *
 158    * @return the front of the resource acquisition chain, i.e., the last
 159    *         resource acquired.
 160    */
 161   static BlockingResourceBase* ResourceChainFront() {
 162     return sResourceAcqnChainFront.get();
 163   }
 164
 165   /**
 166    * ResourceChainPrev
 167    *
 168    * *NOT* thread safe.  Requires ownership of underlying resource.
 169    */
 170   static BlockingResourceBase* ResourceChainPrev(
 171       const BlockingResourceBase* aResource) {
 172     return aResource->mChainPrev;
 173   }  // NS_NEEDS_RESOURCE(this)
 174
 175   /**
 176    * ResourceChainAppend
 177    * Set |this| to the front of the resource acquisition chain, and link
 178    * |this| to |aPrev|.
 179    *
 180    * *NOT* thread safe.  Requires ownership of underlying resource.
 181    */
 182   void ResourceChainAppend(BlockingResourceBase* aPrev) {
 183     mChainPrev = aPrev;
 184     sResourceAcqnChainFront.set(this);
 185   }  // NS_NEEDS_RESOURCE(this)
 186
 187   /**
 188    * ResourceChainRemove
 189    * Remove |this| from the front of the resource acquisition chain.
 190    *
 191    * *NOT* thread safe.  Requires ownership of underlying resource.
 192    */
 193   void ResourceChainRemove() {
 194     NS_ASSERTION(this == ResourceChainFront(), "not at chain front");
 195     sResourceAcqnChainFront.set(mChainPrev);
 196   }  // NS_NEEDS_RESOURCE(this)
 197
 198   /**
 199    * TakeAcquisitionState
 200    * Return whether or not this resource was acquired and mark the resource
 201    * as not acquired for subsequent uses.
 202    *
 203    * *NOT* thread safe.  Requires ownership of underlying resource.
 204    */
 205   AcquisitionState TakeAcquisitionState() {
 206 #  ifdef MOZ_CALLSTACK_DISABLED
 207     bool acquired = mAcquired;
 208     ClearAcquisitionState();
 209     return acquired;
 210 #  else
 211     return mAcquired.take();
 212 #  endif
 213   }
 214
 215   /**
 216    * SetAcquisitionState
 217    * Set whether or not this resource was acquired.
 218    *
 219    * *NOT* thread safe.  Requires ownership of underlying resource.
 220    */
 221   void SetAcquisitionState(AcquisitionState&& aAcquisitionState) {
 222     mAcquired = std::move(aAcquisitionState);
 223   }
 224
 225   /**
 226    * ClearAcquisitionState
 227    * Indicate this resource is not acquired.
 228    *
 229    * *NOT* thread safe.  Requires ownership of underlying resource.
 230    */
 231   void ClearAcquisitionState() {
 232 #  ifdef MOZ_CALLSTACK_DISABLED
 233     mAcquired = false;
 234 #  else
 235     mAcquired.reset();
 236 #  endif
 237   }
 238
 239   /**
 240    * IsAcquired
 241    * Indicates if this resource is acquired.
 242    *
 243    * *NOT* thread safe.  Requires ownership of underlying resource.
 244    */
 245   bool IsAcquired() const { return (bool)mAcquired; }
 246
 247   /**
 248    * mChainPrev
 249    * A series of resource acquisitions creates a chain of orders.  This
 250    * chain is implemented as a linked list; |mChainPrev| points to the
 251    * resource most recently Acquire()'d before this one.
 252    **/
 253   BlockingResourceBase* mChainPrev;
 254
 255  private:
 256   /**
 257    * mName
 258    * A descriptive name for this resource.  Used in error
 259    * messages etc.
 260    */
 261   const char* mName;
 262
 263   /**
 264    * mType
 265    * The more specific type of this resource.  Used to implement
 266    * special semantics (e.g., reentrancy of monitors).
 267    **/
 268   BlockingResourceType mType;
 269
 270   /**
 271    * mAcquired
 272    * Indicates if this resource is currently acquired.
 273    */
 274   AcquisitionState mAcquired;
 275
 276 #  ifndef MOZ_CALLSTACK_DISABLED
 277   /**
 278    * mFirstSeen
 279    * Inidicates where this resource was first acquired.
 280    */
 281   AcquisitionState mFirstSeen;
 282 #  endif
 283
 284   /**
 285    * sCallOnce
 286    * Ensures static members are initialized only once, and in a
 287    * thread-safe way.
 288    */
 289   static PRCallOnceType sCallOnce;
 290
 291   /**
 292    * Thread-private pointer to the front of each thread's resource
 293    * acquisition chain.
 294    */
 295   static MOZ_THREAD_LOCAL(BlockingResourceBase*) sResourceAcqnChainFront;
 296
 297   /**
 298    * sDeadlockDetector
 299    * Does as named.
 300    */
 301   static DDT* sDeadlockDetector;
 302
 303   /**
 304    * InitStatics
 305    * Inititialize static members of BlockingResourceBase that can't
 306    * be statically initialized.
 307    *
 308    * *NOT* thread safe.
 309    */
 310   static PRStatus InitStatics();
 311
 312   /**
 313    * Shutdown
 314    * Free static members.
 315    *
 316    * *NOT* thread safe.
 317    */
 318   static void Shutdown();
 319
 320   static void StackWalkCallback(uint32_t aFrameNumber, void* aPc, void* aSp,
 321                                 void* aClosure);
 322   static void GetStackTrace(AcquisitionState& aState,
 323                             const void* aFirstFramePC);
 324
 325 #  ifdef MOZILLA_INTERNAL_API
 326   // so it can call BlockingResourceBase::Shutdown()
 327   friend void LogTerm();
 328 #  endif  // ifdef MOZILLA_INTERNAL_API
 329
 330 #else  // non-DEBUG implementation
 331
 332   BlockingResourceBase(const char* aName, BlockingResourceType aType) {}
 333
 334   ~BlockingResourceBase() {}
 335
 336 #endif
 337 };
 338
 339 }  // namespace mozilla
 340
 341 #endif  // mozilla_BlockingResourceBase_h