tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

sequence_checker.h (4940B)

      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_