base/sequence_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_SEQUENCE_CHECKER_H_
   6 #define BASE_SEQUENCE_CHECKER_H_
   7
   8 #include "base/check.h"
   9 #include "base/sequence_checker_impl.h"
  10 #include "base/strings/string_piece.h"
  11 #include "build/build_config.h"
  12
  13 #if DCHECK_IS_ON()
  14 #include "base/debug/stack_trace.h"
  15 #endif
  16
  17 // SequenceChecker is a helper class used to help verify that some methods of a
  18 // class are called sequentially (for thread-safety). It supports thread safety
  19 // annotations (see base/thread_annotations.h).
  20 //
  21 // Use the macros below instead of the SequenceChecker directly so that the
  22 // unused member doesn't result in an extra byte (four when padded) per
  23 // instance in production.
  24 //
  25 // This class is much prefered to ThreadChecker for thread-safety checks.
  26 // ThreadChecker should only be used for classes that are truly thread-affine
  27 // (use thread-local-storage or a third-party API that does).
  28 //
  29 // Debugging:
  30 //   If SequenceChecker::EnableStackLogging() is called beforehand, then when
  31 //   SequenceChecker fails, in addition to crashing with a stack trace of where
  32 //   the violation occurred, it will also dump a stack trace of where the
  33 //   checker was bound to a sequence.
  34 //
  35 // Usage:
  36 //   class MyClass {
  37 //    public:
  38 //     MyClass() {
  39 //       // Detaching on construction is necessary for objects that are
  40 //       // constructed on one sequence and forever after used from another
  41 //       // sequence.
  42 //       DETACH_FROM_SEQUENCE(my_sequence_checker_);
  43 //     }
  44 //
  45 //     ~MyClass() {
  46 //       // SequenceChecker doesn't automatically check it's destroyed on origin
  47 //       // sequence for the same reason it's sometimes detached in the
  48 //       // constructor. It's okay to destroy off sequence if the owner
  49 //       // otherwise knows usage on the associated sequence is done. If you're
  50 //       // not detaching in the constructor, you probably want to explicitly
  51 //       // check in the destructor.
  52 //       DCHECK_CALLED_ON_VALID_SEQUENCE(my_sequence_checker_);
  53 //     }
  54 //     void MyMethod() {
  55 //       DCHECK_CALLED_ON_VALID_SEQUENCE(my_sequence_checker_);
  56 //       ... (do stuff) ...
  57 //       MyOtherMethod();
  58 //     }
  59 //
  60 //     void MyOtherMethod()
  61 //         VALID_CONTEXT_REQUIRED(my_sequence_checker_) {
  62 //       foo_ = 42;
  63 //     }
  64 //
  65 //    private:
  66 //      // GUARDED_BY_CONTEXT() enforces that this member is only
  67 //      // accessed from a scope that invokes DCHECK_CALLED_ON_VALID_SEQUENCE()
  68 //      // or from a function annotated with VALID_CONTEXT_REQUIRED(). A
  69 //      // DCHECK build will not compile if the member is accessed and these
  70 //      // conditions are not met.
  71 //     int foo_ GUARDED_BY_CONTEXT(my_sequence_checker_);
  72 //
  73 //     SEQUENCE_CHECKER(my_sequence_checker_);
  74 //   }
  75
  76 #define SEQUENCE_CHECKER_INTERNAL_CONCAT2(a, b) a##b
  77 #define SEQUENCE_CHECKER_INTERNAL_CONCAT(a, b) \
  78   SEQUENCE_CHECKER_INTERNAL_CONCAT2(a, b)
  79 #define SEQUENCE_CHECKER_INTERNAL_UID(prefix) \
  80   SEQUENCE_CHECKER_INTERNAL_CONCAT(prefix, __LINE__)
  81
  82 #if DCHECK_IS_ON()
  83 #define SEQUENCE_CHECKER(name) base::SequenceChecker name
  84 #define DCHECK_CALLED_ON_VALID_SEQUENCE(name, ...)                   \
  85   base::ScopedValidateSequenceChecker SEQUENCE_CHECKER_INTERNAL_UID( \
  86       scoped_validate_sequence_checker_)(name, ##__VA_ARGS__)
  87 #define DETACH_FROM_SEQUENCE(name) (name).DetachFromSequence()
  88 #else  // DCHECK_IS_ON()
  89 // A no-op expansion that can be followed by a semicolon at class level.
  90 #define SEQUENCE_CHECKER(name) static_assert(true, "")
  91 #define DCHECK_CALLED_ON_VALID_SEQUENCE(name, ...) EAT_CHECK_STREAM_PARAMS()
  92 #define DETACH_FROM_SEQUENCE(name)
  93 #endif  // DCHECK_IS_ON()
  94
  95 namespace base {
  96
  97 // Do nothing implementation, for use in release mode.
  98 //
  99 // Note: You should almost always use the SequenceChecker class (through the
 100 // above macros) to get the right version for your build configuration.
 101 // Note: This is marked with "context" capability in order to support
 102 // thread_annotations.h.
 103 class THREAD_ANNOTATION_ATTRIBUTE__(capability("context"))
 104     SequenceCheckerDoNothing {
 105  public:
 106   static void EnableStackLogging() {}
 107
 108   SequenceCheckerDoNothing() = default;
 109
 110   // Moving between matching sequences is allowed to help classes with
 111   // SequenceCheckers that want a default move-construct/assign.
 112   SequenceCheckerDoNothing(SequenceCheckerDoNothing&& other) = default;
 113   SequenceCheckerDoNothing& operator=(SequenceCheckerDoNothing&& other) =
 114       default;
 115   SequenceCheckerDoNothing(const SequenceCheckerDoNothing&) = delete;
 116   SequenceCheckerDoNothing& operator=(const SequenceCheckerDoNothing&) = delete;
 117
 118   bool CalledOnValidSequence(void* = nullptr) const WARN_UNUSED_RESULT {
 119     return true;
 120   }
 121   void DetachFromSequence() {}
 122 };
 123
 124 #if DCHECK_IS_ON()
 125 using SequenceChecker = SequenceCheckerImpl;
 126 #else
 127 using SequenceChecker = SequenceCheckerDoNothing;
 128 #endif  // DCHECK_IS_ON()
 129
 130 #if DCHECK_IS_ON()
 131 class SCOPED_LOCKABLE ScopedValidateSequenceChecker {
 132  public:
 133   explicit ScopedValidateSequenceChecker(const SequenceChecker& checker)
 134       EXCLUSIVE_LOCK_FUNCTION(checker) {
 135     std::unique_ptr<debug::StackTrace> bound_at;
 136     DCHECK(checker.CalledOnValidSequence(&bound_at))
 137         << (bound_at ? "\nWas attached to sequence at:\n" + bound_at->ToString()
 138                      : "");
 139   }
 140
 141   explicit ScopedValidateSequenceChecker(const SequenceChecker& checker,
 142                                          const StringPiece& msg)
 143       EXCLUSIVE_LOCK_FUNCTION(checker) {
 144     std::unique_ptr<debug::StackTrace> bound_at;
 145     DCHECK(checker.CalledOnValidSequence(&bound_at))
 146         << msg
 147         << (bound_at ? "\nWas attached to sequence at:\n" + bound_at->ToString()
 148                      : "");
 149   }
 150
 151   ~ScopedValidateSequenceChecker() UNLOCK_FUNCTION() {}
 152
 153  private:
 154 };
 155 #endif
 156
 157 }  // namespace base
 158
 159 #endif  // BASE_SEQUENCE_CHECKER_H_