ipc/mscom/EnsureMTA.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_mscom_EnsureMTA_h
   8 #define mozilla_mscom_EnsureMTA_h
   9
  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"
  18 #include "nsCOMPtr.h"
  19 #include "nsIThread.h"
  20 #include "nsThreadUtils.h"
  21 #include "nsWindowsHelpers.h"
  22
  23 #include <windows.h>
  24
  25 namespace mozilla {
  26 namespace mscom {
  27 namespace detail {
  28
  29 // Forward declarations
  30 template <typename T>
  31 struct MTADelete;
  32
  33 template <typename T>
  34 struct MTARelease;
  35
  36 template <typename T>
  37 struct MTAReleaseInChildProcess;
  38
  39 struct PreservedStreamDeleter;
  40
  41 }  // namespace detail
  42
  43 class ProcessRuntime;
  44
  45 // This class is OK to use as a temporary on the stack.
  46 class MOZ_STACK_CLASS EnsureMTA final {
  47  public:
  48   enum class Option {
  49     Default,
  50     // Forcibly dispatch to the thread returned by GetPersistentMTAThread(),
  51     // even if the current thread is already inside a MTA.
  52     ForceDispatchToPersistentThread,
  53   };
  54
  55   /**
  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.
  60    */
  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
  66       aClosure();
  67       return;
  68     }
  69
  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);
  74   }
  75
  76   using CreateInstanceAgileRefPromise =
  77       MozPromise<AgileReference, HRESULT, false>;
  78
  79   /**
  80    *       *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
  81    *
  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.
  85    *
  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
  89    * CoCreateInstance).
  90    *
  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
  93    * situation arises.
  94    *
  95    * The resulting promise, once resolved, provides an AgileReference that may
  96    * be passed between any COM-initialized thread in the current process.
  97    *
  98    *       *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
  99    *
 100    * WARNING:
 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.
 104    *
 105    *       *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
 106    *
 107    * WARNING:
 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!
 113    *
 114    *       *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
 115    *
 116    * WARNING:
 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
 123    * via this function!
 124    *
 125    *       *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
 126    *
 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!)
 129    *
 130    *       *** A MSCOM PEER SHOULD REVIEW ALL NEW USES OF THIS API! ***
 131    */
 132   static RefPtr<CreateInstanceAgileRefPromise> CreateInstance(REFCLSID aClsid,
 133                                                               REFIID aIid);
 134
 135  private:
 136   static RefPtr<CreateInstanceAgileRefPromise> CreateInstanceInternal(
 137       REFCLSID aClsid, REFIID aIid);
 138
 139   static nsCOMPtr<nsIThread> GetPersistentMTAThread();
 140
 141   static void SyncDispatch(nsCOMPtr<nsIRunnable>&& aRunnable, Option aOpt);
 142   static void SyncDispatchToPersistentThread(nsIRunnable* aRunnable);
 143
 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()) {
 151       aClosure();
 152       return;
 153     }
 154
 155     nsCOMPtr<nsIThread> thread(GetPersistentMTAThread());
 156     MOZ_ASSERT(thread);
 157     if (!thread) {
 158       return;
 159     }
 160
 161     DebugOnly<nsresult> rv = thread->Dispatch(
 162         NS_NewRunnableFunction("mscom::EnsureMTA::AsyncOperation",
 163                                std::move(aClosure)),
 164         NS_DISPATCH_NORMAL);
 165     MOZ_ASSERT(NS_SUCCEEDED(rv));
 166   }
 167
 168   /**
 169    * This constructor just ensures that the MTA is up and running. This should
 170    * only be called by ProcessRuntime.
 171    */
 172   EnsureMTA();
 173
 174   friend class mozilla::mscom::ProcessRuntime;
 175
 176   template <typename T>
 177   friend struct mozilla::mscom::detail::MTADelete;
 178
 179   template <typename T>
 180   friend struct mozilla::mscom::detail::MTARelease;
 181
 182   template <typename T>
 183   friend struct mozilla::mscom::detail::MTAReleaseInChildProcess;
 184
 185   friend struct mozilla::mscom::detail::PreservedStreamDeleter;
 186 };
 187
 188 }  // namespace mscom
 189 }  // namespace mozilla
 190
 191 #endif  // mozilla_mscom_EnsureMTA_h