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 {
  44 public:
  45   NS_DECL_THREADSAFE_ISUPPORTS
  46   NS_DECL_NSIOBSERVER
  47
  48   /// Initializes the singleton instance. Should be called from the main thread.
  49   static void Initialize();
  50
  51   /// Returns the singleton instance.
  52   static DecodePool* Singleton();
  53
  54   /// @return the number of processor cores we have available. This is not the
  55   /// same as the number of decoding threads we're actually using.
  56   static uint32_t NumberOfCores();
  57
  58   /// True if the DecodePool is being shutdown. This may only be called by
  59   /// threads from the pool to check if they should keep working or not.
  60   bool IsShuttingDown() const;
  61
  62   /// Ask the DecodePool to run @aTask asynchronously and return immediately.
  63   void AsyncRun(IDecodingTask* aTask);
  64
  65   /**
  66    * Run @aTask synchronously if the task would prefer it. It's up to the task
  67    * itself to make this decision; @see IDecodingTask::ShouldPreferSyncRun(). If
  68    * @aTask doesn't prefer it, just run @aTask asynchronously and return
  69    * immediately.
  70    * @return true if the task was run sync, false otherwise.
  71    */
  72   bool SyncRunIfPreferred(IDecodingTask* aTask, const nsCString& aURI);
  73
  74   /**
  75    * Run @aTask synchronously. This does not guarantee that @aTask will complete
  76    * synchronously. If, for example, @aTask doesn't yet have the data it needs to
  77    * run synchronously, it may recover by scheduling an async task to finish up
  78    * the work when the remaining data is available.
  79    */
  80   void SyncRunIfPossible(IDecodingTask* aTask, const nsCString& aURI);
  81
  82   /**
  83    * Returns an event target interface to the DecodePool's I/O thread. Callers
  84    * who want to deliver data to workers on the DecodePool can use this event
  85    * target.
  86    *
  87    * @return An nsIEventTarget interface to the thread pool's I/O thread.
  88    */
  89   already_AddRefed<nsIEventTarget> GetIOEventTarget();
  90
  91 private:
  92   friend class DecodePoolWorker;
  93
  94   DecodePool();
  95   virtual ~DecodePool();
  96
  97   static StaticRefPtr<DecodePool> sSingleton;
  98   static uint32_t sNumCores;
  99
 100   RefPtr<DecodePoolImpl> mImpl;
 101
 102   // mMutex protects mIOThread.
 103   Mutex                         mMutex;
 104   nsCOMPtr<nsIThread>           mIOThread;
 105 };
 106
 107 } // namespace image
 108 } // namespace mozilla
 109
 110 #endif // mozilla_image_DecodePool_h