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 mozilla_mscom_EnsureMTA_h
8 #define mozilla_mscom_EnsureMTA_h
10 #include "MainThreadUtils.h"
11 #include "mozilla/Attributes.h"
12 #include "mozilla/DebugOnly.h"
13 #include "mozilla/MozPromise.h"
14 #include "mozilla/Unused.h"
15 #include "mozilla/mscom/AgileReference.h"
16 #include "mozilla/mscom/Utils.h"
17 #include "mozilla/RefPtr.h"
19 #include "nsIThread.h"
20 #include "nsThreadUtils.h"
21 #include "nsWindowsHelpers.h"
29 // Forward declarations
37 struct MTAReleaseInChildProcess
;
39 struct PreservedStreamDeleter
;
45 // This class is OK to use as a temporary on the stack.
46 class MOZ_STACK_CLASS EnsureMTA final
{
50 // Forcibly dispatch to the thread returned by GetPersistentMTAThread(),
51 // even if the current thread is already inside a MTA.
52 ForceDispatchToPersistentThread
,
56 * Synchronously run |aClosure| on a thread living in the COM multithreaded
57 * apartment. If the current thread lives inside the COM MTA, then it runs
58 * |aClosure| immediately unless |aOpt| ==
59 * Option::ForceDispatchToPersistentThread.
61 template <typename FuncT
>
62 explicit EnsureMTA(FuncT
&& aClosure
, Option aOpt
= Option::Default
) {
63 if (aOpt
!= Option::ForceDispatchToPersistentThread
&&
64 IsCurrentThreadMTA()) {
65 // We're already on the MTA, we can run aClosure directly
70 // In this case we need to run aClosure on a background thread in the MTA
71 nsCOMPtr
<nsIRunnable
> runnable(
72 NS_NewRunnableFunction("EnsureMTA::EnsureMTA", std::move(aClosure
)));
73 SyncDispatch(std::move(runnable
), aOpt
);
76 using CreateInstanceAgileRefPromise
=
77 MozPromise
<AgileReference
, HRESULT
, false>;
80 * *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
82 * Asynchronously instantiate a new COM object from a MTA thread, unless the
83 * current thread is already living inside the multithreaded apartment, in
84 * which case the object is immediately instantiated.
86 * This function only supports the most common configurations for creating
87 * a new object, so it only supports in-process servers. Furthermore, this
88 * function does not support aggregation (ie. the |pUnkOuter| parameter to
91 * Given that attempting to instantiate an Apartment-threaded COM object
92 * inside the MTA results in a *loss* of performance, we assert when that
95 * The resulting promise, once resolved, provides an AgileReference that may
96 * be passed between any COM-initialized thread in the current process.
98 * *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
101 * Some COM objects do not support creation in the multithreaded apartment,
102 * in which case this function is not available as an option. In this case,
103 * the promise will always be rejected. In debug builds we will assert.
105 * *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
108 * Any in-process COM objects whose interfaces accept HWNDs are probably
109 * *not* safe to instantiate in the multithreaded apartment! Even if this
110 * function succeeds when creating such an object, you *MUST NOT* do so, as
111 * these failures might not become apparent until your code is running out in
112 * the wild on the release channel!
114 * *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
117 * When you obtain an interface from the AgileReference, it may or may not be
118 * a proxy to the real object. This depends entirely on the implementation of
119 * the underlying class and the multithreading capabilities that the class
120 * declares to the COM runtime. If the interface is proxied, it might be
121 * expensive to invoke methods on that interface! *Always* test the
122 * performance of your method calls when calling interfaces that are resolved
125 * *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
127 * (Despite this myriad of warnings, it is still *much* safer to use this
128 * function to asynchronously create COM objects than it is to roll your own!)
130 * *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
132 static RefPtr
<CreateInstanceAgileRefPromise
> CreateInstance(REFCLSID aClsid
,
136 static RefPtr
<CreateInstanceAgileRefPromise
> CreateInstanceInternal(
137 REFCLSID aClsid
, REFIID aIid
);
139 static nsCOMPtr
<nsIThread
> GetPersistentMTAThread();
141 static void SyncDispatch(nsCOMPtr
<nsIRunnable
>&& aRunnable
, Option aOpt
);
142 static void SyncDispatchToPersistentThread(nsIRunnable
* aRunnable
);
144 // The following function is private in order to force any consumers to be
145 // declared as friends of EnsureMTA. The intention is to prevent
146 // AsyncOperation from becoming some kind of free-for-all mechanism for
147 // asynchronously executing work on a background thread.
148 template <typename FuncT
>
149 static void AsyncOperation(FuncT
&& aClosure
) {
150 if (IsCurrentThreadMTA()) {
155 nsCOMPtr
<nsIThread
> thread(GetPersistentMTAThread());
161 DebugOnly
<nsresult
> rv
= thread
->Dispatch(
162 NS_NewRunnableFunction("mscom::EnsureMTA::AsyncOperation",
163 std::move(aClosure
)),
165 MOZ_ASSERT(NS_SUCCEEDED(rv
));
169 * This constructor just ensures that the MTA is up and running. This should
170 * only be called by ProcessRuntime.
174 friend class mozilla::mscom::ProcessRuntime
;
176 template <typename T
>
177 friend struct mozilla::mscom::detail::MTADelete
;
179 template <typename T
>
180 friend struct mozilla::mscom::detail::MTARelease
;
182 template <typename T
>
183 friend struct mozilla::mscom::detail::MTAReleaseInChildProcess
;
185 friend struct mozilla::mscom::detail::PreservedStreamDeleter
;
189 } // namespace mozilla
191 #endif // mozilla_mscom_EnsureMTA_h