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