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 size_t SizeOfDeadlockDetector(MallocSizeOf aMallocSizeOf);
  68
  69   /**
  70    * Print
  71    * Write a description of this blocking resource to |aOut|.  If
  72    * the resource appears to be currently acquired, the current
  73    * acquisition context is printed and true is returned.
  74    * Otherwise, we print the context from |aFirstSeen|, the
  75    * first acquisition from which the code calling |Print()|
  76    * became interested in us, and return false.
  77    *
  78    * *NOT* thread safe.  Reads |mAcquisitionContext| without
  79    * synchronization, but this will not cause correctness
  80    * problems.
  81    *
  82    * FIXME bug 456272: hack alert: because we can't write call
  83    * contexts into strings, all info is written to stderr, but
  84    * only some info is written into |aOut|
  85    */
  86   bool Print(nsACString& aOut) const;
  87
  88   size_t SizeOfIncludingThis(MallocSizeOf aMallocSizeOf) const {
  89     // NB: |mName| is not reported as it's expected to be a static string.
  90     //     If we switch to a nsString it should be added to the tally.
  91     //     |mChainPrev| is not reported because its memory is not owned.
  92     size_t n = aMallocSizeOf(this);
  93     return n;
  94   }
  95
  96   // ``DDT'' = ``Deadlock Detector Type''
  97   typedef DeadlockDetector<BlockingResourceBase> DDT;
  98
  99  protected:
 100 #  ifdef MOZ_CALLSTACK_DISABLED
 101   typedef bool AcquisitionState;
 102 #  else
 103   // Using maybe to use emplacement as the acquisition state flag; we may not
 104   // always get a stack trace because of possible stack walk suppression or
 105   // errors, hence can't use !IsEmpty() on the array itself as indication.
 106   static size_t const kAcquisitionStateStackSize = 24;
 107   typedef Maybe<AutoTArray<void*, kAcquisitionStateStackSize> >
 108       AcquisitionState;
 109 #  endif
 110
 111   /**
 112    * BlockingResourceBase
 113    * Initialize this blocking resource.  Also hooks the resource into
 114    * instrumentation code.
 115    *
 116    * Thread safe.
 117    *
 118    * @param aName A meaningful, unique name that can be used in
 119    *              error messages, et al.
 120    * @param aType The specific type of |this|, if any.
 121    **/
 122   BlockingResourceBase(const char* aName, BlockingResourceType aType);
 123
 124   ~BlockingResourceBase();
 125
 126   /**
 127    * CheckAcquire
 128    *
 129    * Thread safe.
 130    **/
 131   void CheckAcquire();
 132
 133   /**
 134    * Acquire
 135    *
 136    * *NOT* thread safe.  Requires ownership of underlying resource.
 137    **/
 138   void Acquire();  // NS_NEEDS_RESOURCE(this)
 139
 140   /**
 141    * Release
 142    * Remove this resource from the current thread's acquisition chain.
 143    * The resource does not have to be at the front of the chain, although
 144    * it is confusing to release resources in a different order than they
 145    * are acquired.  This generates a warning.
 146    *
 147    * *NOT* thread safe.  Requires ownership of underlying resource.
 148    **/
 149   void Release();  // NS_NEEDS_RESOURCE(this)
 150
 151   /**
 152    * ResourceChainFront
 153    *
 154    * Thread safe.
 155    *
 156    * @return the front of the resource acquisition chain, i.e., the last
 157    *         resource acquired.
 158    */
 159   static BlockingResourceBase* ResourceChainFront() {
 160     return sResourceAcqnChainFront.get();
 161   }
 162
 163   /**
 164    * ResourceChainPrev
 165    *
 166    * *NOT* thread safe.  Requires ownership of underlying resource.
 167    */
 168   static BlockingResourceBase* ResourceChainPrev(
 169       const BlockingResourceBase* aResource) {
 170     return aResource->mChainPrev;
 171   }  // NS_NEEDS_RESOURCE(this)
 172
 173   /**
 174    * ResourceChainAppend
 175    * Set |this| to the front of the resource acquisition chain, and link
 176    * |this| to |aPrev|.
 177    *
 178    * *NOT* thread safe.  Requires ownership of underlying resource.
 179    */
 180   void ResourceChainAppend(BlockingResourceBase* aPrev) {
 181     mChainPrev = aPrev;
 182     sResourceAcqnChainFront.set(this);
 183   }  // NS_NEEDS_RESOURCE(this)
 184
 185   /**
 186    * ResourceChainRemove
 187    * Remove |this| from the front of the resource acquisition chain.
 188    *
 189    * *NOT* thread safe.  Requires ownership of underlying resource.
 190    */
 191   void ResourceChainRemove() {
 192     NS_ASSERTION(this == ResourceChainFront(), "not at chain front");
 193     sResourceAcqnChainFront.set(mChainPrev);
 194   }  // NS_NEEDS_RESOURCE(this)
 195
 196   /**
 197    * TakeAcquisitionState
 198    * Return whether or not this resource was acquired and mark the resource
 199    * as not acquired for subsequent uses.
 200    *
 201    * *NOT* thread safe.  Requires ownership of underlying resource.
 202    */
 203   AcquisitionState TakeAcquisitionState() {
 204 #  ifdef MOZ_CALLSTACK_DISABLED
 205     bool acquired = mAcquired;
 206     ClearAcquisitionState();
 207     return acquired;
 208 #  else
 209     return mAcquired.take();
 210 #  endif
 211   }
 212
 213   /**
 214    * SetAcquisitionState
 215    * Set whether or not this resource was acquired.
 216    *
 217    * *NOT* thread safe.  Requires ownership of underlying resource.
 218    */
 219   void SetAcquisitionState(AcquisitionState&& aAcquisitionState) {
 220     mAcquired = std::move(aAcquisitionState);
 221   }
 222
 223   /**
 224    * ClearAcquisitionState
 225    * Indicate this resource is not acquired.
 226    *
 227    * *NOT* thread safe.  Requires ownership of underlying resource.
 228    */
 229   void ClearAcquisitionState() {
 230 #  ifdef MOZ_CALLSTACK_DISABLED
 231     mAcquired = false;
 232 #  else
 233     mAcquired.reset();
 234 #  endif
 235   }
 236
 237   /**
 238    * IsAcquired
 239    * Indicates if this resource is acquired.
 240    *
 241    * *NOT* thread safe.  Requires ownership of underlying resource.
 242    */
 243   bool IsAcquired() const { return (bool)mAcquired; }
 244
 245   /**
 246    * mChainPrev
 247    * A series of resource acquisitions creates a chain of orders.  This
 248    * chain is implemented as a linked list; |mChainPrev| points to the
 249    * resource most recently Acquire()'d before this one.
 250    **/
 251   BlockingResourceBase* mChainPrev;
 252
 253  private:
 254   /**
 255    * mName
 256    * A descriptive name for this resource.  Used in error
 257    * messages etc.
 258    */
 259   const char* mName;
 260
 261   /**
 262    * mType
 263    * The more specific type of this resource.  Used to implement
 264    * special semantics (e.g., reentrancy of monitors).
 265    **/
 266   BlockingResourceType mType;
 267
 268   /**
 269    * mAcquired
 270    * Indicates if this resource is currently acquired.
 271    */
 272   AcquisitionState mAcquired;
 273
 274 #  ifndef MOZ_CALLSTACK_DISABLED
 275   /**
 276    * mFirstSeen
 277    * Inidicates where this resource was first acquired.
 278    */
 279   AcquisitionState mFirstSeen;
 280 #  endif
 281
 282   /**
 283    * sCallOnce
 284    * Ensures static members are initialized only once, and in a
 285    * thread-safe way.
 286    */
 287   static PRCallOnceType sCallOnce;
 288
 289   /**
 290    * Thread-private pointer to the front of each thread's resource
 291    * acquisition chain.
 292    */
 293   static MOZ_THREAD_LOCAL(BlockingResourceBase*) sResourceAcqnChainFront;
 294
 295   /**
 296    * sDeadlockDetector
 297    * Does as named.
 298    */
 299   static DDT* sDeadlockDetector;
 300
 301   /**
 302    * InitStatics
 303    * Inititialize static members of BlockingResourceBase that can't
 304    * be statically initialized.
 305    *
 306    * *NOT* thread safe.
 307    */
 308   static PRStatus InitStatics();
 309
 310   /**
 311    * Shutdown
 312    * Free static members.
 313    *
 314    * *NOT* thread safe.
 315    */
 316   static void Shutdown();
 317
 318   static void StackWalkCallback(uint32_t aFrameNumber, void* aPc, void* aSp,
 319                                 void* aClosure);
 320   static void GetStackTrace(AcquisitionState& aState,
 321                             const void* aFirstFramePC);
 322
 323 #  ifdef MOZILLA_INTERNAL_API
 324   // so it can call BlockingResourceBase::Shutdown()
 325   friend void LogTerm();
 326 #  endif  // ifdef MOZILLA_INTERNAL_API
 327
 328 #else  // non-DEBUG implementation
 329
 330   BlockingResourceBase(const char* aName, BlockingResourceType aType) {}
 331
 332   ~BlockingResourceBase() {}
 333
 334 #endif
 335 };
 336
 337 }  // namespace mozilla
 338
 339 #endif  // mozilla_BlockingResourceBase_h