xpcom/glue/nsProxyRelease.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 nsProxyRelease_h__
   8 #define nsProxyRelease_h__
   9
  10 #include "nsIEventTarget.h"
  11 #include "nsIThread.h"
  12 #include "nsCOMPtr.h"
  13 #include "nsAutoPtr.h"
  14 #include "MainThreadUtils.h"
  15 #include "mozilla/Likely.h"
  16
  17 #ifdef XPCOM_GLUE_AVOID_NSPR
  18 #error NS_ProxyRelease implementation depends on NSPR.
  19 #endif
  20
  21 /**
  22  * Ensure that a nsCOMPtr is released on the target thread.
  23  *
  24  * @see NS_ProxyRelease(nsIEventTarget*, nsISupports*, bool)
  25  */
  26 template<class T>
  27 inline NS_HIDDEN_(nsresult)
  28 NS_ProxyRelease(nsIEventTarget* aTarget, nsCOMPtr<T>& aDoomed,
  29                 bool aAlwaysProxy = false)
  30 {
  31   T* raw = nullptr;
  32   aDoomed.swap(raw);
  33   return NS_ProxyRelease(aTarget, raw, aAlwaysProxy);
  34 }
  35
  36 /**
  37  * Ensure that a nsRefPtr is released on the target thread.
  38  *
  39  * @see NS_ProxyRelease(nsIEventTarget*, nsISupports*, bool)
  40  */
  41 template<class T>
  42 inline NS_HIDDEN_(nsresult)
  43 NS_ProxyRelease(nsIEventTarget* aTarget, nsRefPtr<T>& aDoomed,
  44                 bool aAlwaysProxy = false)
  45 {
  46   T* raw = nullptr;
  47   aDoomed.swap(raw);
  48   return NS_ProxyRelease(aTarget, raw, aAlwaysProxy);
  49 }
  50
  51 /**
  52  * Ensures that the delete of a nsISupports object occurs on the target thread.
  53  *
  54  * @param aTarget
  55  *        the target thread where the doomed object should be released.
  56  * @param aDoomed
  57  *        the doomed object; the object to be released on the target thread.
  58  * @param aAlwaysProxy
  59  *        normally, if NS_ProxyRelease is called on the target thread, then the
  60  *        doomed object will released directly.  however, if this parameter is
  61  *        true, then an event will always be posted to the target thread for
  62  *        asynchronous release.
  63  */
  64 nsresult
  65 NS_ProxyRelease(nsIEventTarget* aTarget, nsISupports* aDoomed,
  66                 bool aAlwaysProxy = false);
  67
  68 /**
  69  * Class to safely handle main-thread-only pointers off the main thread.
  70  *
  71  * Classes like XPCWrappedJS are main-thread-only, which means that it is
  72  * forbidden to call methods on instances of these classes off the main thread.
  73  * For various reasons (see bug 771074), this restriction recently began to
  74  * apply to AddRef/Release as well.
  75  *
  76  * This presents a problem for consumers that wish to hold a callback alive
  77  * on non-main-thread code. A common example of this is the proxy callback
  78  * pattern, where non-main-thread code holds a strong-reference to the callback
  79  * object, and dispatches new Runnables (also with a strong reference) to the
  80  * main thread in order to execute the callback. This involves several AddRef
  81  * and Release calls on the other thread, which is (now) verboten.
  82  *
  83  * The basic idea of this class is to introduce a layer of indirection.
  84  * nsMainThreadPtrHolder is a threadsafe reference-counted class that internally
  85  * maintains one strong reference to the main-thread-only object. It must be
  86  * instantiated on the main thread (so that the AddRef of the underlying object
  87  * happens on the main thread), but consumers may subsequently pass references
  88  * to the holder anywhere they please. These references are meant to be opaque
  89  * when accessed off-main-thread (assertions enforce this).
  90  *
  91  * The semantics of nsRefPtr<nsMainThreadPtrHolder<T> > would be cumbersome, so
  92  * we also introduce nsMainThreadPtrHandle<T>, which is conceptually identical
  93  * to the above (though it includes various convenience methods). The basic
  94  * pattern is as follows.
  95  *
  96  * // On the main thread:
  97  * nsCOMPtr<nsIFooCallback> callback = ...;
  98  * nsMainThreadPtrHandle<nsIFooCallback> callbackHandle =
  99  *   new nsMainThreadPtrHolder<nsIFooCallback>(callback);
 100  * // Pass callbackHandle to structs/classes that might be accessed on other
 101  * // threads.
 102  *
 103  * All structs and classes that might be accessed on other threads should store
 104  * an nsMainThreadPtrHandle<T> rather than an nsCOMPtr<T>.
 105  */
 106 template<class T>
 107 class nsMainThreadPtrHolder MOZ_FINAL
 108 {
 109 public:
 110   // We can only acquire a pointer on the main thread. We to fail fast for
 111   // threading bugs, so by default we assert if our pointer is used or acquired
 112   // off-main-thread. But some consumers need to use the same pointer for
 113   // multiple classes, some of which are main-thread-only and some of which
 114   // aren't. So we allow them to explicitly disable this strict checking.
 115   explicit nsMainThreadPtrHolder(T* aPtr, bool aStrict = true)
 116     : mRawPtr(nullptr)
 117     , mStrict(aStrict)
 118   {
 119     // We can only AddRef our pointer on the main thread, which means that the
 120     // holder must be constructed on the main thread.
 121     MOZ_ASSERT(!mStrict || NS_IsMainThread());
 122     NS_IF_ADDREF(mRawPtr = aPtr);
 123   }
 124
 125 private:
 126   // We can be released on any thread.
 127   ~nsMainThreadPtrHolder()
 128   {
 129     if (NS_IsMainThread()) {
 130       NS_IF_RELEASE(mRawPtr);
 131     } else if (mRawPtr) {
 132       nsCOMPtr<nsIThread> mainThread;
 133       NS_GetMainThread(getter_AddRefs(mainThread));
 134       if (!mainThread) {
 135         NS_WARNING("Couldn't get main thread! Leaking pointer.");
 136         return;
 137       }
 138       NS_ProxyRelease(mainThread, mRawPtr);
 139     }
 140   }
 141
 142 public:
 143   T* get()
 144   {
 145     // Nobody should be touching the raw pointer off-main-thread.
 146     if (mStrict && MOZ_UNLIKELY(!NS_IsMainThread())) {
 147       NS_ERROR("Can't dereference nsMainThreadPtrHolder off main thread");
 148       MOZ_CRASH();
 149     }
 150     return mRawPtr;
 151   }
 152
 153   bool operator==(const nsMainThreadPtrHolder<T>& aOther) const
 154   {
 155     return mRawPtr == aOther.mRawPtr;
 156   }
 157
 158   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(nsMainThreadPtrHolder<T>)
 159
 160 private:
 161   // Our wrapped pointer.
 162   T* mRawPtr;
 163
 164   // Whether to strictly enforce thread invariants in this class.
 165   bool mStrict;
 166
 167   // Copy constructor and operator= not implemented. Once constructed, the
 168   // holder is immutable.
 169   T& operator=(nsMainThreadPtrHolder& aOther);
 170   nsMainThreadPtrHolder(const nsMainThreadPtrHolder& aOther);
 171 };
 172
 173 template<class T>
 174 class nsMainThreadPtrHandle
 175 {
 176   nsRefPtr<nsMainThreadPtrHolder<T>> mPtr;
 177
 178 public:
 179   nsMainThreadPtrHandle() : mPtr(nullptr) {}
 180   explicit nsMainThreadPtrHandle(nsMainThreadPtrHolder<T>* aHolder)
 181     : mPtr(aHolder)
 182   {
 183   }
 184   nsMainThreadPtrHandle(const nsMainThreadPtrHandle& aOther)
 185     : mPtr(aOther.mPtr)
 186   {
 187   }
 188   nsMainThreadPtrHandle& operator=(const nsMainThreadPtrHandle& aOther)
 189   {
 190     mPtr = aOther.mPtr;
 191     return *this;
 192   }
 193   nsMainThreadPtrHandle& operator=(nsMainThreadPtrHolder<T>* aHolder)
 194   {
 195     mPtr = aHolder;
 196     return *this;
 197   }
 198
 199   // These all call through to nsMainThreadPtrHolder, and thus implicitly
 200   // assert that we're on the main thread. Off-main-thread consumers must treat
 201   // these handles as opaque.
 202   T* get()
 203   {
 204     if (mPtr) {
 205       return mPtr.get()->get();
 206     }
 207     return nullptr;
 208   }
 209   const T* get() const
 210   {
 211     if (mPtr) {
 212       return mPtr.get()->get();
 213     }
 214     return nullptr;
 215   }
 216
 217   operator T*() { return get(); }
 218   T* operator->() { return get(); }
 219
 220   // These are safe to call on other threads with appropriate external locking.
 221   bool operator==(const nsMainThreadPtrHandle<T>& aOther) const
 222   {
 223     if (!mPtr || !aOther.mPtr) {
 224       return mPtr == aOther.mPtr;
 225     }
 226     return *mPtr == *aOther.mPtr;
 227   }
 228   bool operator!() { return !mPtr; }
 229 };
 230
 231 #endif