ios/web/public/web_thread.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef IOS_WEB_PUBLIC_WEB_THREAD_H_
   6 #define IOS_WEB_PUBLIC_WEB_THREAD_H_
   7
   8 #include <string>
   9
  10 #include "base/callback_forward.h"
  11 #include "base/compiler_specific.h"
  12 #include "base/logging.h"
  13 #include "base/macros.h"
  14 #include "base/task_runner_util.h"
  15
  16 namespace base {
  17 class MessageLoop;
  18 class SequencedWorkerPool;
  19 }
  20
  21 namespace tracked_objects {
  22 class Location;
  23 }
  24
  25 namespace web {
  26
  27 // Use DCHECK_CURRENTLY_ON_WEB_THREAD(WebThread::ID) to assert that a function
  28 // can only be called on the named WebThread.
  29 // TODO(ios): rename to DCHECK_CURRENTLY_ON once iOS is independent from
  30 // content/ so it won't collide with the macro DCHECK_CURRENTLY_ON in content/.
  31 // http://crbug.com/438202
  32 #define DCHECK_CURRENTLY_ON_WEB_THREAD(thread_identifier)   \
  33   (DCHECK(::web::WebThread::CurrentlyOn(thread_identifier)) \
  34    << ::web::WebThread::GetDCheckCurrentlyOnErrorMessage(thread_identifier))
  35
  36 ///////////////////////////////////////////////////////////////////////////////
  37 // WebThread
  38 //
  39 // Utility functions for threads that are known by name. For example, there is
  40 // one IO thread for the entire process, and various pieces of code find it
  41 // useful to retrieve a pointer to the IO thread's message loop.
  42 //
  43 // Invoke a task by thread ID:
  44 //
  45 //   WebThread::PostTask(WebThread::IO, FROM_HERE, task);
  46 //
  47 // The return value is false if the task couldn't be posted because the target
  48 // thread doesn't exist.  If this could lead to data loss, you need to check the
  49 // result and restructure the code to ensure it doesn't occur.
  50 //
  51 // This class automatically handles the lifetime of different threads.
  52 // It's always safe to call PostTask on any thread.  If it's not yet created,
  53 // the task is deleted.  There are no race conditions.  If the thread that the
  54 // task is posted to is guaranteed to outlive the current thread, then no locks
  55 // are used.  You should never need to cache pointers to MessageLoops, since
  56 // they're not thread safe.
  57 class WebThread {
  58  public:
  59   // An enumeration of the well-known threads.
  60   // NOTE: threads must be listed in the order of their life-time, with each
  61   // thread outliving every other thread below it.
  62   enum ID {
  63     // The main thread in the browser.
  64     UI,
  65
  66     // This is the thread that interacts with the database.
  67     DB,
  68
  69     // This is the thread that interacts with the file system.
  70     FILE,
  71
  72     // Used for file system operations that block user interactions.
  73     // Responsiveness of this thread affect users.
  74     FILE_USER_BLOCKING,
  75
  76     // This is the thread to handle slow HTTP cache operations.
  77     CACHE,
  78
  79     // This is the thread that processes non-blocking IO, i.e. IPC and network.
  80     // Blocking IO should happen on other threads like DB, FILE,
  81     // FILE_USER_BLOCKING and CACHE depending on the usage.
  82     IO,
  83
  84     // NOTE: do not add new threads here that are only used by a small number of
  85     // files. Instead you should just use a Thread class and pass its
  86     // SingleThreadTaskRunner around. Named threads there are only for threads
  87     // that are used in many places.
  88
  89     // This identifier does not represent a thread.  Instead it counts the
  90     // number of well-known threads.  Insert new well-known threads before this
  91     // identifier.
  92     ID_COUNT
  93   };
  94
  95   // These are the same methods as in message_loop.h, but are guaranteed to
  96   // either get posted to the MessageLoop if it's still alive, or be deleted
  97   // otherwise.
  98   // They return true iff the thread existed and the task was posted.
  99   static bool PostTask(ID identifier,
 100                        const tracked_objects::Location& from_here,
 101                        const base::Closure& task);
 102   static bool PostDelayedTask(ID identifier,
 103                               const tracked_objects::Location& from_here,
 104                               const base::Closure& task,
 105                               base::TimeDelta delay);
 106   static bool PostNonNestableTask(ID identifier,
 107                                   const tracked_objects::Location& from_here,
 108                                   const base::Closure& task);
 109   static bool PostNonNestableDelayedTask(
 110       ID identifier,
 111       const tracked_objects::Location& from_here,
 112       const base::Closure& task,
 113       base::TimeDelta delay);
 114
 115   static bool PostTaskAndReply(ID identifier,
 116                                const tracked_objects::Location& from_here,
 117                                const base::Closure& task,
 118                                const base::Closure& reply);
 119
 120   template <typename ReturnType, typename ReplyArgType>
 121   static bool PostTaskAndReplyWithResult(
 122       ID identifier,
 123       const tracked_objects::Location& from_here,
 124       const base::Callback<ReturnType(void)>& task,
 125       const base::Callback<void(ReplyArgType)>& reply) {
 126     scoped_refptr<base::SingleThreadTaskRunner> task_runner =
 127         GetTaskRunnerForThread(identifier);
 128     return base::PostTaskAndReplyWithResult(task_runner.get(), from_here, task,
 129                                             reply);
 130   }
 131
 132   template <class T>
 133   static bool DeleteSoon(ID identifier,
 134                          const tracked_objects::Location& from_here,
 135                          const T* object) {
 136     return GetTaskRunnerForThread(identifier)->DeleteSoon(from_here, object);
 137   }
 138
 139   // Simplified wrappers for posting to the blocking thread pool. Use this
 140   // for doing things like blocking I/O.
 141   //
 142   // The first variant will run the task in the pool with no sequencing
 143   // semantics, so may get run in parallel with other posted tasks. The second
 144   // variant will all post a task with no sequencing semantics, and will post a
 145   // reply task to the origin TaskRunner upon completion.  The third variant
 146   // provides sequencing between tasks with the same sequence token name.
 147   //
 148   // These tasks are guaranteed to run before shutdown.
 149   //
 150   // If you need to provide different shutdown semantics (like you have
 151   // something slow and noncritical that doesn't need to block shutdown),
 152   // or you want to manually provide a sequence token (which saves a map
 153   // lookup and is guaranteed unique without you having to come up with a
 154   // unique string), you can access the sequenced worker pool directly via
 155   // GetBlockingPool().
 156   //
 157   // If you need to PostTaskAndReplyWithResult, use
 158   // base::PostTaskAndReplyWithResult() with GetBlockingPool() as the task
 159   // runner.
 160   static bool PostBlockingPoolTask(const tracked_objects::Location& from_here,
 161                                    const base::Closure& task);
 162   static bool PostBlockingPoolTaskAndReply(
 163       const tracked_objects::Location& from_here,
 164       const base::Closure& task,
 165       const base::Closure& reply);
 166   static bool PostBlockingPoolSequencedTask(
 167       const std::string& sequence_token_name,
 168       const tracked_objects::Location& from_here,
 169       const base::Closure& task);
 170
 171   // Returns the thread pool used for blocking file I/O. Use this object to
 172   // perform random blocking operations such as file writes.
 173   static base::SequencedWorkerPool* GetBlockingPool() WARN_UNUSED_RESULT;
 174
 175   // Returns a pointer to the thread's message loop, which will become
 176   // invalid during shutdown, so you probably shouldn't hold onto it.
 177   //
 178   // This must not be called before the thread is started, or after
 179   // the thread is stopped, or it will DCHECK.
 180   //
 181   // Ownership remains with the WebThread implementation, so you must not
 182   // delete the pointer.
 183   static base::MessageLoop* UnsafeGetMessageLoopForThread(ID identifier);
 184
 185   // Callable on any thread.  Returns whether the given well-known thread is
 186   // initialized.
 187   static bool IsThreadInitialized(ID identifier) WARN_UNUSED_RESULT;
 188
 189   // Callable on any thread.  Returns whether execution is currently on the
 190   // given thread.  To DCHECK this, use the DCHECK_CURRENTLY_ON_WEB_THREAD()
 191   // macro above.
 192   static bool CurrentlyOn(ID identifier) WARN_UNUSED_RESULT;
 193
 194   // Callable on any thread.  Returns whether the threads message loop is valid.
 195   // If this returns false it means the thread is in the process of shutting
 196   // down.
 197   static bool IsMessageLoopValid(ID identifier) WARN_UNUSED_RESULT;
 198
 199   // If the current message loop is one of the known threads, returns true and
 200   // sets identifier to its ID.
 201   static bool GetCurrentThreadIdentifier(ID* identifier) WARN_UNUSED_RESULT;
 202
 203   // Callers can hold on to a refcounted SingleThreadTaskRunner beyond the
 204   // lifetime of the thread.
 205   static scoped_refptr<base::SingleThreadTaskRunner> GetTaskRunnerForThread(
 206       ID identifier);
 207
 208   // Returns an appropriate error message for when
 209   // DCHECK_CURRENTLY_ON_WEB_THREAD() fails.
 210   static std::string GetDCheckCurrentlyOnErrorMessage(ID expected);
 211
 212  private:
 213   friend class WebThreadImpl;
 214
 215   WebThread() {}
 216   DISALLOW_COPY_AND_ASSIGN(WebThread);
 217 };
 218
 219 }  // namespace web
 220
 221 #endif  // IOS_WEB_PUBLIC_WEB_THREAD_H_