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.
5 #ifndef BASE_SEQUENCE_CHECKER_H_
6 #define BASE_SEQUENCE_CHECKER_H_
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"
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).
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.
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).
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.
35 // // Detaching on construction is necessary for objects that are
36 // // constructed on one sequence and forever after used from another
38 // DETACH_FROM_SEQUENCE(my_sequence_checker_);
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_);
51 // DCHECK_CALLED_ON_VALID_SEQUENCE(my_sequence_checker_);
56 // void MyOtherMethod()
57 // VALID_CONTEXT_REQUIRED(my_sequence_checker_) {
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_);
69 // SEQUENCE_CHECKER(my_sequence_checker_);
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()
87 // Do nothing implementation, for use in release mode.
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 {
96 static void EnableStackLogging() {}
98 SequenceCheckerDoNothing() = default;
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) =
105 SequenceCheckerDoNothing(const SequenceCheckerDoNothing&) = delete;
106 SequenceCheckerDoNothing& operator=(const SequenceCheckerDoNothing&) = delete;
108 [[nodiscard]] bool CalledOnValidSequence(void* = nullptr) const {
111 void DetachFromSequence() {}
115 using SequenceChecker = SequenceCheckerImpl;
117 using SequenceChecker = SequenceCheckerDoNothing;
118 #endif // DCHECK_IS_ON()
121 class BASE_EXPORT SCOPED_LOCKABLE ScopedValidateSequenceChecker {
123 explicit ScopedValidateSequenceChecker(const SequenceChecker& checker)
124 EXCLUSIVE_LOCK_FUNCTION(checker);
125 ~ScopedValidateSequenceChecker() UNLOCK_FUNCTION();
131 #endif // BASE_SEQUENCE_CHECKER_H_