base/threading/thread_checker.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_CHECKER_H_
   6 #define BASE_THREADING_THREAD_CHECKER_H_
   7
   8 // Apart from debug builds, we also enable the thread checker in
   9 // builds with DCHECK_ALWAYS_ON so that trybots and waterfall bots
  10 // with this define will get the same level of thread checking as
  11 // debug bots.
  12 //
  13 // Note that this does not perfectly match situations where DCHECK is
  14 // enabled.  For example a non-official release build may have
  15 // DCHECK_ALWAYS_ON undefined (and therefore ThreadChecker would be
  16 // disabled) but have DCHECKs enabled at runtime.
  17 #if (!defined(NDEBUG) || defined(DCHECK_ALWAYS_ON))
  18 #define ENABLE_THREAD_CHECKER 1
  19 #else
  20 #define ENABLE_THREAD_CHECKER 0
  21 #endif
  22
  23 #include "base/threading/thread_checker_impl.h"
  24
  25 namespace base {
  26
  27 // Do nothing implementation, for use in release mode.
  28 //
  29 // Note: You should almost always use the ThreadChecker class to get the
  30 // right version for your build configuration.
  31 class ThreadCheckerDoNothing {
  32  public:
  33   bool CalledOnValidThread() const WARN_UNUSED_RESULT {
  34     return true;
  35   }
  36
  37   void DetachFromThread() {}
  38 };
  39
  40 // ThreadChecker is a helper class used to help verify that some methods of a
  41 // class are called from the same thread. It provides identical functionality to
  42 // base::NonThreadSafe, but it is meant to be held as a member variable, rather
  43 // than inherited from base::NonThreadSafe.
  44 //
  45 // While inheriting from base::NonThreadSafe may give a clear indication about
  46 // the thread-safety of a class, it may also lead to violations of the style
  47 // guide with regard to multiple inheritance. The choice between having a
  48 // ThreadChecker member and inheriting from base::NonThreadSafe should be based
  49 // on whether:
  50 //  - Derived classes need to know the thread they belong to, as opposed to
  51 //    having that functionality fully encapsulated in the base class.
  52 //  - Derived classes should be able to reassign the base class to another
  53 //    thread, via DetachFromThread.
  54 //
  55 // If neither of these are true, then having a ThreadChecker member and calling
  56 // CalledOnValidThread is the preferable solution.
  57 //
  58 // Example:
  59 // class MyClass {
  60 //  public:
  61 //   void Foo() {
  62 //     DCHECK(thread_checker_.CalledOnValidThread());
  63 //     ... (do stuff) ...
  64 //   }
  65 //
  66 //  private:
  67 //   ThreadChecker thread_checker_;
  68 // }
  69 //
  70 // In Release mode, CalledOnValidThread will always return true.
  71 #if ENABLE_THREAD_CHECKER
  72 class ThreadChecker : public ThreadCheckerImpl {
  73 };
  74 #else
  75 class ThreadChecker : public ThreadCheckerDoNothing {
  76 };
  77 #endif  // ENABLE_THREAD_CHECKER
  78
  79 #undef ENABLE_THREAD_CHECKER
  80
  81 }  // namespace base
  82
  83 #endif  // BASE_THREADING_THREAD_CHECKER_H_