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/. */
7 #ifndef nsProxyRelease_h__
8 #define nsProxyRelease_h__
10 #include "nsIEventTarget.h"
11 #include "nsIThread.h"
13 #include "nsAutoPtr.h"
14 #include "MainThreadUtils.h"
15 #include "mozilla/Likely.h"
17 #ifdef XPCOM_GLUE_AVOID_NSPR
18 #error NS_ProxyRelease implementation depends on NSPR.
22 * Ensure that a nsCOMPtr is released on the target thread.
24 * @see NS_ProxyRelease(nsIEventTarget*, nsISupports*, bool)
27 inline NS_HIDDEN_(nsresult
)
28 NS_ProxyRelease(nsIEventTarget
* aTarget
, nsCOMPtr
<T
>& aDoomed
,
29 bool aAlwaysProxy
= false)
33 return NS_ProxyRelease(aTarget
, raw
, aAlwaysProxy
);
37 * Ensure that a nsRefPtr is released on the target thread.
39 * @see NS_ProxyRelease(nsIEventTarget*, nsISupports*, bool)
42 inline NS_HIDDEN_(nsresult
)
43 NS_ProxyRelease(nsIEventTarget
* aTarget
, nsRefPtr
<T
>& aDoomed
,
44 bool aAlwaysProxy
= false)
48 return NS_ProxyRelease(aTarget
, raw
, aAlwaysProxy
);
52 * Ensures that the delete of a nsISupports object occurs on the target thread.
55 * the target thread where the doomed object should be released.
57 * the doomed object; the object to be released on the target thread.
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.
65 NS_ProxyRelease(nsIEventTarget
* aTarget
, nsISupports
* aDoomed
,
66 bool aAlwaysProxy
= false);
69 * Class to safely handle main-thread-only pointers off the main thread.
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.
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.
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).
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.
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
103 * All structs and classes that might be accessed on other threads should store
104 * an nsMainThreadPtrHandle<T> rather than an nsCOMPtr<T>.
107 class nsMainThreadPtrHolder MOZ_FINAL
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)
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
);
126 // We can be released on any thread.
127 ~nsMainThreadPtrHolder()
129 if (NS_IsMainThread()) {
130 NS_IF_RELEASE(mRawPtr
);
131 } else if (mRawPtr
) {
132 nsCOMPtr
<nsIThread
> mainThread
;
133 NS_GetMainThread(getter_AddRefs(mainThread
));
135 NS_WARNING("Couldn't get main thread! Leaking pointer.");
138 NS_ProxyRelease(mainThread
, mRawPtr
);
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");
153 bool operator==(const nsMainThreadPtrHolder
<T
>& aOther
) const
155 return mRawPtr
== aOther
.mRawPtr
;
158 NS_INLINE_DECL_THREADSAFE_REFCOUNTING(nsMainThreadPtrHolder
<T
>)
161 // Our wrapped pointer.
164 // Whether to strictly enforce thread invariants in this class.
167 // Copy constructor and operator= not implemented. Once constructed, the
168 // holder is immutable.
169 T
& operator=(nsMainThreadPtrHolder
& aOther
);
170 nsMainThreadPtrHolder(const nsMainThreadPtrHolder
& aOther
);
174 class nsMainThreadPtrHandle
176 nsRefPtr
<nsMainThreadPtrHolder
<T
>> mPtr
;
179 nsMainThreadPtrHandle() : mPtr(nullptr) {}
180 explicit nsMainThreadPtrHandle(nsMainThreadPtrHolder
<T
>* aHolder
)
184 nsMainThreadPtrHandle(const nsMainThreadPtrHandle
& aOther
)
188 nsMainThreadPtrHandle
& operator=(const nsMainThreadPtrHandle
& aOther
)
193 nsMainThreadPtrHandle
& operator=(nsMainThreadPtrHolder
<T
>* aHolder
)
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.
205 return mPtr
.get()->get();
212 return mPtr
.get()->get();
217 operator T
*() { return get(); }
218 T
* operator->() { return get(); }
220 // These are safe to call on other threads with appropriate external locking.
221 bool operator==(const nsMainThreadPtrHandle
<T
>& aOther
) const
223 if (!mPtr
|| !aOther
.mPtr
) {
224 return mPtr
== aOther
.mPtr
;
226 return *mPtr
== *aOther
.mPtr
;
228 bool operator!() { return !mPtr
; }