base/sequence_checker.h

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