base/threading/thread_restrictions.h

   1 // Copyright (c) 2012 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 BASE_THREADING_THREAD_RESTRICTIONS_H_
   6 #define BASE_THREADING_THREAD_RESTRICTIONS_H_
   7
   8 #include "base/base_export.h"
   9 #include "base/basictypes.h"
  10
  11 // See comment at top of thread_checker.h
  12 #if (!defined(NDEBUG) || defined(DCHECK_ALWAYS_ON))
  13 #define ENABLE_THREAD_RESTRICTIONS 1
  14 #else
  15 #define ENABLE_THREAD_RESTRICTIONS 0
  16 #endif
  17
  18 class AcceleratedPresenter;
  19 class BrowserProcessImpl;
  20 class HistogramSynchronizer;
  21 class MetricsService;
  22 class NativeBackendKWallet;
  23 class ScopedAllowWaitForLegacyWebViewApi;
  24 class TestingAutomationProvider;
  25
  26 namespace browser_sync {
  27 class NonFrontendDataTypeController;
  28 class UIModelWorker;
  29 }
  30 namespace cc {
  31 class CompletionEvent;
  32 }
  33 namespace chromeos {
  34 class AudioMixerAlsa;
  35 class BlockingMethodCaller;
  36 namespace system {
  37 class StatisticsProviderImpl;
  38 }
  39 }
  40 namespace chrome_browser_net {
  41 class Predictor;
  42 }
  43 namespace content {
  44 class BrowserGpuChannelHostFactory;
  45 class GLHelper;
  46 class GpuChannelHost;
  47 class RenderWidgetHelper;
  48 class TextInputClientMac;
  49 }
  50 namespace dbus {
  51 class Bus;
  52 }
  53 namespace disk_cache {
  54 class BackendImpl;
  55 class InFlightIO;
  56 }
  57 namespace media {
  58 class AudioOutputController;
  59 }
  60 namespace net {
  61 class FileStreamPosix;
  62 class FileStreamWin;
  63 namespace internal {
  64 class AddressTrackerLinux;
  65 }
  66 }
  67
  68 namespace remoting {
  69 class AutoThread;
  70 }
  71
  72 namespace base {
  73
  74 class SequencedWorkerPool;
  75 class SimpleThread;
  76 class Thread;
  77 class ThreadTestHelper;
  78
  79 // Certain behavior is disallowed on certain threads.  ThreadRestrictions helps
  80 // enforce these rules.  Examples of such rules:
  81 //
  82 // * Do not do blocking IO (makes the thread janky)
  83 // * Do not access Singleton/LazyInstance (may lead to shutdown crashes)
  84 //
  85 // Here's more about how the protection works:
  86 //
  87 // 1) If a thread should not be allowed to make IO calls, mark it:
  88 //      base::ThreadRestrictions::SetIOAllowed(false);
  89 //    By default, threads *are* allowed to make IO calls.
  90 //    In Chrome browser code, IO calls should be proxied to the File thread.
  91 //
  92 // 2) If a function makes a call that will go out to disk, check whether the
  93 //    current thread is allowed:
  94 //      base::ThreadRestrictions::AssertIOAllowed();
  95 //
  96 //
  97 // Style tip: where should you put AssertIOAllowed checks?  It's best
  98 // if you put them as close to the disk access as possible, at the
  99 // lowest level.  This rule is simple to follow and helps catch all
 100 // callers.  For example, if your function GoDoSomeBlockingDiskCall()
 101 // only calls other functions in Chrome and not fopen(), you should go
 102 // add the AssertIOAllowed checks in the helper functions.
 103
 104 class BASE_EXPORT ThreadRestrictions {
 105  public:
 106   // Constructing a ScopedAllowIO temporarily allows IO for the current
 107   // thread.  Doing this is almost certainly always incorrect.
 108   class BASE_EXPORT ScopedAllowIO {
 109    public:
 110     ScopedAllowIO() { previous_value_ = SetIOAllowed(true); }
 111     ~ScopedAllowIO() { SetIOAllowed(previous_value_); }
 112    private:
 113     // Whether IO is allowed when the ScopedAllowIO was constructed.
 114     bool previous_value_;
 115
 116     DISALLOW_COPY_AND_ASSIGN(ScopedAllowIO);
 117   };
 118
 119   // Constructing a ScopedAllowSingleton temporarily allows accessing for the
 120   // current thread.  Doing this is almost always incorrect.
 121   class BASE_EXPORT ScopedAllowSingleton {
 122    public:
 123     ScopedAllowSingleton() { previous_value_ = SetSingletonAllowed(true); }
 124     ~ScopedAllowSingleton() { SetSingletonAllowed(previous_value_); }
 125    private:
 126     // Whether singleton use is allowed when the ScopedAllowSingleton was
 127     // constructed.
 128     bool previous_value_;
 129
 130     DISALLOW_COPY_AND_ASSIGN(ScopedAllowSingleton);
 131   };
 132
 133 #if ENABLE_THREAD_RESTRICTIONS
 134   // Set whether the current thread to make IO calls.
 135   // Threads start out in the *allowed* state.
 136   // Returns the previous value.
 137   static bool SetIOAllowed(bool allowed);
 138
 139   // Check whether the current thread is allowed to make IO calls,
 140   // and DCHECK if not.  See the block comment above the class for
 141   // a discussion of where to add these checks.
 142   static void AssertIOAllowed();
 143
 144   // Set whether the current thread can use singletons.  Returns the previous
 145   // value.
 146   static bool SetSingletonAllowed(bool allowed);
 147
 148   // Check whether the current thread is allowed to use singletons (Singleton /
 149   // LazyInstance).  DCHECKs if not.
 150   static void AssertSingletonAllowed();
 151
 152   // Disable waiting on the current thread. Threads start out in the *allowed*
 153   // state. Returns the previous value.
 154   static void DisallowWaiting();
 155
 156   // Check whether the current thread is allowed to wait, and DCHECK if not.
 157   static void AssertWaitAllowed();
 158 #else
 159   // Inline the empty definitions of these functions so that they can be
 160   // compiled out.
 161   static bool SetIOAllowed(bool allowed) { return true; }
 162   static void AssertIOAllowed() {}
 163   static bool SetSingletonAllowed(bool allowed) { return true; }
 164   static void AssertSingletonAllowed() {}
 165   static void DisallowWaiting() {}
 166   static void AssertWaitAllowed() {}
 167 #endif
 168
 169  private:
 170   // DO NOT ADD ANY OTHER FRIEND STATEMENTS, talk to jam or brettw first.
 171   // BEGIN ALLOWED USAGE.
 172   friend class content::RenderWidgetHelper;
 173   friend class ::HistogramSynchronizer;
 174   friend class ::ScopedAllowWaitForLegacyWebViewApi;
 175   friend class ::TestingAutomationProvider;
 176   friend class cc::CompletionEvent;
 177   friend class remoting::AutoThread;
 178   friend class MessagePumpDefault;
 179   friend class SequencedWorkerPool;
 180   friend class SimpleThread;
 181   friend class Thread;
 182   friend class ThreadTestHelper;
 183
 184   // END ALLOWED USAGE.
 185   // BEGIN USAGE THAT NEEDS TO BE FIXED.
 186   friend class ::chromeos::AudioMixerAlsa;        // http://crbug.com/125206
 187   friend class ::chromeos::BlockingMethodCaller;  // http://crbug.com/125360
 188   friend class ::chromeos::system::StatisticsProviderImpl;  // http://crbug.com/125385
 189   friend class browser_sync::NonFrontendDataTypeController;  // http://crbug.com/19757
 190   friend class browser_sync::UIModelWorker;       // http://crbug.com/19757
 191   friend class chrome_browser_net::Predictor;     // http://crbug.com/78451
 192   friend class
 193       content::BrowserGpuChannelHostFactory;      // http://crbug.com/125248
 194   friend class content::GLHelper;                 // http://crbug.com/125415
 195   friend class content::GpuChannelHost;           // http://crbug.com/125264
 196   friend class content::TextInputClientMac;       // http://crbug.com/121917
 197   friend class dbus::Bus;                         // http://crbug.com/125222
 198   friend class disk_cache::BackendImpl;           // http://crbug.com/74623
 199   friend class disk_cache::InFlightIO;            // http://crbug.com/74623
 200   friend class media::AudioOutputController;      // http://crbug.com/120973
 201   friend class net::FileStreamPosix;              // http://crbug.com/115067
 202   friend class net::FileStreamWin;                // http://crbug.com/115067
 203   friend class net::internal::AddressTrackerLinux;  // http://crbug.com/125097
 204   friend class ::AcceleratedPresenter;            // http://crbug.com/125391
 205   friend class ::BrowserProcessImpl;              // http://crbug.com/125207
 206   friend class ::MetricsService;                  // http://crbug.com/124954
 207   friend class ::NativeBackendKWallet;            // http://crbug.com/125331
 208   // END USAGE THAT NEEDS TO BE FIXED.
 209
 210 #if ENABLE_THREAD_RESTRICTIONS
 211   static bool SetWaitAllowed(bool allowed);
 212 #else
 213   static bool SetWaitAllowed(bool allowed) { return true; }
 214 #endif
 215
 216   // Constructing a ScopedAllowWait temporarily allows waiting on the current
 217   // thread.  Doing this is almost always incorrect, which is why we limit who
 218   // can use this through friend. If you find yourself needing to use this, find
 219   // another way. Talk to jam or brettw.
 220   class BASE_EXPORT ScopedAllowWait {
 221    public:
 222     ScopedAllowWait() { previous_value_ = SetWaitAllowed(true); }
 223     ~ScopedAllowWait() { SetWaitAllowed(previous_value_); }
 224    private:
 225     // Whether singleton use is allowed when the ScopedAllowWait was
 226     // constructed.
 227     bool previous_value_;
 228
 229     DISALLOW_COPY_AND_ASSIGN(ScopedAllowWait);
 230   };
 231
 232   DISALLOW_IMPLICIT_CONSTRUCTORS(ThreadRestrictions);
 233 };
 234
 235 }  // namespace base
 236
 237 #endif  // BASE_THREADING_THREAD_RESTRICTIONS_H_