image/DecodePool.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /**
   7  * DecodePool manages the threads used for decoding raster images.
   8  */
   9
  10 #ifndef mozilla_image_DecodePool_h
  11 #define mozilla_image_DecodePool_h
  12
  13 #include "mozilla/Mutex.h"
  14 #include "mozilla/StaticPtr.h"
  15 #include "nsCOMArray.h"
  16 #include "nsCOMPtr.h"
  17 #include "nsIEventTarget.h"
  18 #include "nsIObserver.h"
  19 #include "mozilla/RefPtr.h"
  20 #include "nsStringFwd.h"
  21
  22 class nsIThread;
  23 class nsIThreadPool;
  24
  25 namespace mozilla {
  26 namespace image {
  27
  28 class Decoder;
  29 class DecodePoolImpl;
  30 class IDecodingTask;
  31
  32 /**
  33  * DecodePool is a singleton class that manages decoding of raster images. It
  34  * owns a pool of image decoding threads that are used for asynchronous
  35  * decoding.
  36  *
  37  * DecodePool allows callers to run a decoder, handling management of the
  38  * decoder's lifecycle and whether it executes on the main thread,
  39  * off-main-thread in the image decoding thread pool, or on some combination of
  40  * the two.
  41  */
  42 class DecodePool final : public nsIObserver {
  43  public:
  44   NS_DECL_THREADSAFE_ISUPPORTS
  45   NS_DECL_NSIOBSERVER
  46
  47   /// Initializes the singleton instance. Should be called from the main thread.
  48   static void Initialize();
  49
  50   /// Returns the singleton instance.
  51   static DecodePool* Singleton();
  52
  53   /// @return the number of processor cores we have available. This is not the
  54   /// same as the number of decoding threads we're actually using.
  55   static uint32_t NumberOfCores();
  56
  57   /// True if the DecodePool is being shutdown. This may only be called by
  58   /// threads from the pool to check if they should keep working or not.
  59   bool IsShuttingDown() const;
  60
  61   /// Ask the DecodePool to run @aTask asynchronously and return immediately.
  62   void AsyncRun(IDecodingTask* aTask);
  63
  64   /**
  65    * Run @aTask synchronously if the task would prefer it. It's up to the task
  66    * itself to make this decision; @see IDecodingTask::ShouldPreferSyncRun(). If
  67    * @aTask doesn't prefer it, just run @aTask asynchronously and return
  68    * immediately.
  69    * @return true if the task was run sync, false otherwise.
  70    */
  71   bool SyncRunIfPreferred(IDecodingTask* aTask, const nsCString& aURI);
  72
  73   /**
  74    * Run @aTask synchronously. This does not guarantee that @aTask will complete
  75    * synchronously. If, for example, @aTask doesn't yet have the data it needs
  76    * to run synchronously, it may recover by scheduling an async task to finish
  77    * up the work when the remaining data is available.
  78    */
  79   void SyncRunIfPossible(IDecodingTask* aTask, const nsCString& aURI);
  80
  81   /**
  82    * Returns an event target interface to the DecodePool's I/O thread. Callers
  83    * who want to deliver data to workers on the DecodePool can use this event
  84    * target.
  85    *
  86    * @return An nsIEventTarget interface to the thread pool's I/O thread.
  87    */
  88   already_AddRefed<nsIEventTarget> GetIOEventTarget();
  89
  90  private:
  91   friend class DecodePoolWorker;
  92
  93   DecodePool();
  94   virtual ~DecodePool();
  95
  96   static StaticRefPtr<DecodePool> sSingleton;
  97   static uint32_t sNumCores;
  98   bool mShuttingDown = false;
  99
 100   // mMutex protects mIOThread.
 101   Mutex mMutex;
 102   nsCOMPtr<nsIThread> mIOThread GUARDED_BY(mMutex);
 103 };
 104
 105 }  // namespace image
 106 }  // namespace mozilla
 107
 108 #endif  // mozilla_image_DecodePool_h