xpcom/threads/LazyIdleThread.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_lazyidlethread_h__
   8 #define mozilla_lazyidlethread_h__
   9
  10 #ifndef MOZILLA_INTERNAL_API
  11 #  error "This header is only usable from within libxul (MOZILLA_INTERNAL_API)."
  12 #endif
  13
  14 #include "mozilla/TaskQueue.h"
  15 #include "nsIObserver.h"
  16 #include "nsThreadPool.h"
  17
  18 namespace mozilla {
  19
  20 /**
  21  * This class provides a basic event target that creates its thread lazily and
  22  * destroys its thread after a period of inactivity. It may be created and used
  23  * on any thread but it may only be shut down from the thread on which it is
  24  * created.
  25  */
  26 class LazyIdleThread final : public nsISerialEventTarget, public nsIObserver {
  27  public:
  28   NS_DECL_THREADSAFE_ISUPPORTS
  29   NS_DECL_NSIEVENTTARGET_FULL
  30   NS_DECL_NSIOBSERVER
  31
  32   /**
  33    * If AutomaticShutdown is specified, and the LazyIdleThread is created on the
  34    * main thread, Shutdown() will automatically be called during
  35    * xpcom-shutdown-threads.
  36    */
  37   enum ShutdownMethod { AutomaticShutdown = 0, ManualShutdown };
  38
  39   /**
  40    * Create a new LazyIdleThread that will destroy its thread after the given
  41    * number of milliseconds.
  42    */
  43   LazyIdleThread(uint32_t aIdleTimeoutMS, const char* aName,
  44                  ShutdownMethod aShutdownMethod = AutomaticShutdown);
  45
  46   /**
  47    * Shuts down the LazyIdleThread, waiting for any pending work to complete.
  48    * Must be called from mOwningEventTarget.
  49    */
  50   void Shutdown();
  51
  52   /**
  53    * Register a nsIThreadPoolListener on the underlying threadpool to track the
  54    * thread as it is created/destroyed.
  55    */
  56   nsresult SetListener(nsIThreadPoolListener* aListener);
  57
  58  private:
  59   /**
  60    * Asynchronously shuts down the LazyIdleThread on mOwningEventTarget.
  61    */
  62   ~LazyIdleThread();
  63
  64   /**
  65    * The thread which created this LazyIdleThread and is responsible for
  66    * shutting it down.
  67    */
  68   const nsCOMPtr<nsISerialEventTarget> mOwningEventTarget;
  69
  70   /**
  71    * The single-thread backing threadpool which provides the actual threads used
  72    * by LazyIdleThread, and implements the timeout.
  73    */
  74   const RefPtr<nsThreadPool> mThreadPool;
  75
  76   /**
  77    * The serial event target providing a `nsISerialEventTarget` implementation
  78    * when on the LazyIdleThread.
  79    */
  80   const RefPtr<TaskQueue> mTaskQueue;
  81
  82   /**
  83    * Only safe to access on the owning thread or in the destructor (as no other
  84    * threads have access then). If `true`, means the LazyIdleThread has already
  85    * been shut down, so it does not need to be shut down asynchronously from the
  86    * destructor.
  87    */
  88   bool mShutdown = false;
  89 };
  90
  91 }  // namespace mozilla
  92
  93 #endif  // mozilla_lazyidlethread_h__