sequence_checker.h 5.1 KB

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