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