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
  21 class nsIThread;
  22 class nsIThreadPool;
  23
  24 namespace mozilla {
  25 namespace image {
  26
  27 class Decoder;
  28 class DecodePoolImpl;
  29
  30 /**
  31  * DecodePool is a singleton class that manages decoding of raster images. It
  32  * owns a pool of image decoding threads that are used for asynchronous
  33  * decoding.
  34  *
  35  * DecodePool allows callers to run a decoder, handling management of the
  36  * decoder's lifecycle and whether it executes on the main thread,
  37  * off-main-thread in the image decoding thread pool, or on some combination of
  38  * the two.
  39  */
  40 class DecodePool : public nsIObserver
  41 {
  42 public:
  43   NS_DECL_THREADSAFE_ISUPPORTS
  44   NS_DECL_NSIOBSERVER
  45
  46   /// Initializes the singleton instance. Should be called from the main thread.
  47   static void Initialize();
  48
  49   /// Returns the singleton instance.
  50   static DecodePool* Singleton();
  51
  52   /// @return the number of processor cores we have available. This is not the
  53   /// same as the number of decoding threads we're actually using.
  54   static uint32_t NumberOfCores();
  55
  56   /// Ask the DecodePool to run @aDecoder asynchronously and return immediately.
  57   void AsyncDecode(Decoder* aDecoder);
  58
  59   /**
  60    * Run @aDecoder synchronously if the image it's decoding is small. If the
  61    * image is too large, or if the source data isn't complete yet, run @aDecoder
  62    * asynchronously instead.
  63    */
  64   void SyncDecodeIfSmall(Decoder* aDecoder);
  65
  66   /**
  67    * Run aDecoder synchronously if at all possible. If it can't complete
  68    * synchronously because the source data isn't complete, asynchronously decode
  69    * the rest.
  70    */
  71   void SyncDecodeIfPossible(Decoder* aDecoder);
  72
  73   /**
  74    * Returns an event target interface to the DecodePool's I/O thread. Callers
  75    * who want to deliver data to workers on the DecodePool can use this event
  76    * target.
  77    *
  78    * @return An nsIEventTarget interface to the thread pool's I/O thread.
  79    */
  80   already_AddRefed<nsIEventTarget> GetIOEventTarget();
  81
  82 private:
  83   friend class DecodePoolWorker;
  84
  85   DecodePool();
  86   virtual ~DecodePool();
  87
  88   void Decode(Decoder* aDecoder);
  89   void NotifyDecodeComplete(Decoder* aDecoder);
  90   void NotifyProgress(Decoder* aDecoder);
  91
  92   static StaticRefPtr<DecodePool> sSingleton;
  93   static uint32_t sNumCores;
  94
  95   RefPtr<DecodePoolImpl>    mImpl;
  96
  97   // mMutex protects mThreads and mIOThread.
  98   Mutex                     mMutex;
  99   nsCOMArray<nsIThread>     mThreads;
 100   nsCOMPtr<nsIThread>       mIOThread;
 101 };
 102
 103 } // namespace image
 104 } // namespace mozilla
 105
 106 #endif // mozilla_image_DecodePool_h