OLD | NEW |
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef BASE_THREADING_THREAD_CHECKER_H_ | 5 #ifndef BASE_THREADING_THREAD_CHECKER_H_ |
6 #define BASE_THREADING_THREAD_CHECKER_H_ | 6 #define BASE_THREADING_THREAD_CHECKER_H_ |
7 | 7 |
8 #include "base/logging.h" | 8 #include "base/logging.h" |
9 #include "base/threading/thread_checker_impl.h" | 9 #include "base/threading/thread_checker_impl.h" |
10 | 10 |
| 11 // ThreadChecker is a helper class used to help verify that some methods of a |
| 12 // class are called from the same thread (for thread-affinity). |
| 13 // |
| 14 // Use the macros below instead of the ThreadChecker directly so that the unused |
| 15 // member doesn't result in an extra byte (four when padded) per instance in |
| 16 // production. |
| 17 // |
| 18 // Usage of this class should be *rare* as most classes require thread-safety |
| 19 // but not thread-affinity. Prefer base::SequenceChecker to verify thread-safe |
| 20 // access. |
| 21 // |
| 22 // Thread-affinity checks should only be required in classes that use thread- |
| 23 // local-storage or a third-party API that does. |
| 24 // |
| 25 // Prefer to encode the minimum requirements of each class instead of the |
| 26 // environment it happens to run in today. e.g. if a class requires thread- |
| 27 // safety but not thread-affinity, use a SequenceChecker even if it happens to |
| 28 // run on a SingleThreadTaskRunner today. That makes it easier to understand |
| 29 // what would need to change to turn that SingleThreadTaskRunner into a |
| 30 // SequencedTaskRunner for ease of scheduling as well as minimizes side-effects |
| 31 // if that change is made. |
| 32 // |
| 33 // Usage: |
| 34 // class MyClass { |
| 35 // public: |
| 36 // MyClass() { |
| 37 // // It's sometimes useful to detach on construction for objects that are |
| 38 // // constructed in one place and forever after used from another |
| 39 // // thread. |
| 40 // DETACH_FROM_THREAD(my_thread_checker_); |
| 41 // } |
| 42 // |
| 43 // ~MyClass() { |
| 44 // // ThreadChecker doesn't automatically check it's destroyed on origin |
| 45 // // thread for the same reason it's sometimes detached in the |
| 46 // // constructor. It's okay to destroy off thread if the owner otherwise |
| 47 // // knows usage on the associated thread is done. If you're not |
| 48 // // detaching in the constructor, you probably want to explicitly check |
| 49 // // in the destructor. |
| 50 // DCHECK_CALLED_ON_VALID_THREAD(my_thread_checker_); |
| 51 // } |
| 52 // |
| 53 // void MyMethod() { |
| 54 // DCHECK_CALLED_ON_VALID_THREAD(my_thread_checker_); |
| 55 // ... (do stuff) ... |
| 56 // } |
| 57 // |
| 58 // private: |
| 59 // THREAD_CHECKER(my_thread_checker_); |
| 60 // } |
| 61 |
| 62 #if DCHECK_IS_ON() |
| 63 #define THREAD_CHECKER(name) base::ThreadChecker name |
| 64 #define DCHECK_CALLED_ON_VALID_THREAD(name) DCHECK((name).CalledOnValidThread()) |
| 65 #define DETACH_FROM_THREAD(name) (name).DetachFromThread() |
| 66 #else // DCHECK_IS_ON() |
| 67 #define THREAD_CHECKER(name) |
| 68 #define DCHECK_CALLED_ON_VALID_THREAD(name) |
| 69 #define DETACH_FROM_THREAD(name) |
| 70 #endif // DCHECK_IS_ON() |
| 71 |
11 namespace base { | 72 namespace base { |
12 | 73 |
13 // Do nothing implementation, for use in release mode. | 74 // Do nothing implementation, for use in release mode. |
14 // | 75 // |
15 // Note: You should almost always use the ThreadChecker class to get the | 76 // Note: You should almost always use the ThreadChecker class (through the above |
16 // right version for your build configuration. | 77 // macros) to get the right version for your build configuration. |
17 class ThreadCheckerDoNothing { | 78 class ThreadCheckerDoNothing { |
18 public: | 79 public: |
19 bool CalledOnValidThread() const WARN_UNUSED_RESULT { | 80 bool CalledOnValidThread() const WARN_UNUSED_RESULT { |
20 return true; | 81 return true; |
21 } | 82 } |
22 | 83 |
23 void DetachFromThread() {} | 84 void DetachFromThread() {} |
24 }; | 85 }; |
25 | 86 |
26 // ThreadChecker is a helper class used to help verify that some methods of a | 87 // Note that ThreadCheckerImpl::CalledOnValidThread() returns false when called |
27 // class are called from the same thread. It provides identical functionality to | 88 // from tasks posted to SingleThreadTaskRunners bound to different sequences, |
28 // base::NonThreadSafe, but it is meant to be held as a member variable, rather | 89 // even if the tasks happen to run on the same thread (e.g. two independent |
29 // than inherited from base::NonThreadSafe. | 90 // SingleThreadTaskRunners on the TaskScheduler that happen to share a thread). |
30 // | |
31 // While inheriting from base::NonThreadSafe may give a clear indication about | |
32 // the thread-safety of a class, it may also lead to violations of the style | |
33 // guide with regard to multiple inheritance. The choice between having a | |
34 // ThreadChecker member and inheriting from base::NonThreadSafe should be based | |
35 // on whether: | |
36 // - Derived classes need to know the thread they belong to, as opposed to | |
37 // having that functionality fully encapsulated in the base class. | |
38 // - Derived classes should be able to reassign the base class to another | |
39 // thread, via DetachFromThread. | |
40 // | |
41 // If neither of these are true, then having a ThreadChecker member and calling | |
42 // CalledOnValidThread is the preferable solution. | |
43 // | |
44 // Example: | |
45 // class MyClass { | |
46 // public: | |
47 // void Foo() { | |
48 // DCHECK(thread_checker_.CalledOnValidThread()); | |
49 // ... (do stuff) ... | |
50 // } | |
51 // | |
52 // private: | |
53 // ThreadChecker thread_checker_; | |
54 // } | |
55 // | |
56 // Note that, when enabled, CalledOnValidThread() returns false when called from | |
57 // tasks posted to SingleThreadTaskRunners bound to different sequences, even if | |
58 // the tasks happen to run on the same thread (e.g. two independent TaskRunners | |
59 // with ExecutionMode::SINGLE_THREADED on the TaskScheduler that happen to share | |
60 // a thread). | |
61 // | |
62 // In Release mode, CalledOnValidThread will always return true. | |
63 #if DCHECK_IS_ON() | 91 #if DCHECK_IS_ON() |
64 class ThreadChecker : public ThreadCheckerImpl { | 92 class ThreadChecker : public ThreadCheckerImpl { |
65 }; | 93 }; |
66 #else | 94 #else |
67 class ThreadChecker : public ThreadCheckerDoNothing { | 95 class ThreadChecker : public ThreadCheckerDoNothing { |
68 }; | 96 }; |
69 #endif // DCHECK_IS_ON() | 97 #endif // DCHECK_IS_ON() |
70 | 98 |
71 } // namespace base | 99 } // namespace base |
72 | 100 |
73 #endif // BASE_THREADING_THREAD_CHECKER_H_ | 101 #endif // BASE_THREADING_THREAD_CHECKER_H_ |
OLD | NEW |