1 // Copyright (c) 2008 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.
5 #ifndef BASE_THREAD_COLLISION_WARNER_H_
6 #define BASE_THREAD_COLLISION_WARNER_H_
10 #include "base/atomicops.h"
12 // A helper class alongside macros to be used to verify assumptions about thread
15 // Example: Queue implementation non thread-safe but still usable if clients
16 // are synchronized somehow.
18 // In this case the macro DFAKE_SCOPED_LOCK has to be
19 // used, it checks that if a thread is inside the push/pop then
20 // noone else is still inside the pop/push
22 // class NonThreadSafeQueue {
25 // void push(int) { DFAKE_SCOPED_LOCK(push_pop_); ... }
26 // int pop() { DFAKE_SCOPED_LOCK(push_pop_); ... }
29 // DFAKE_MUTEX(push_pop_);
33 // Example: Queue implementation non thread-safe but still usable if clients
34 // are synchronized somehow, it calls a method to "protect" from
35 // a "protected" method
37 // In this case the macro DFAKE_SCOPED_RECURSIVE_LOCK
38 // has to be used, it checks that if a thread is inside the push/pop
39 // then noone else is still inside the pop/push
41 // class NonThreadSafeQueue {
44 // DFAKE_SCOPED_LOCK(push_pop_);
48 // DFAKE_SCOPED_RECURSIVE_LOCK(push_pop_);
52 // void bar() { DFAKE_SCOPED_RECURSIVE_LOCK(push_pop_); ... }
55 // DFAKE_MUTEX(push_pop_);
59 // Example: Queue implementation not usable even if clients are synchronized,
60 // so only one thread in the class life cycle can use the two members
63 // In this case the macro DFAKE_SCOPED_LOCK_THREAD_LOCKED pins the
65 // critical section the first time a thread enters push or pop, from
66 // that time on only that thread is allowed to execute push or pop.
68 // class NonThreadSafeQueue {
71 // void push(int) { DFAKE_SCOPED_LOCK_THREAD_LOCKED(push_pop_); ... }
72 // int pop() { DFAKE_SCOPED_LOCK_THREAD_LOCKED(push_pop_); ... }
75 // DFAKE_MUTEX(push_pop_);
79 // Example: Class that has to be contructed/destroyed on same thread, it has
80 // a "shareable" method (with external syncronization) and a not
81 // shareable method (even with external synchronization).
83 // In this case 3 Critical sections have to be defined
85 // class ExoticClass {
87 // ExoticClass() { DFAKE_SCOPED_LOCK_THREAD_LOCKED(ctor_dtor_); ... }
88 // ~ExoticClass() { DFAKE_SCOPED_LOCK_THREAD_LOCKED(ctor_dtor_); ... }
90 // void Shareable() { DFAKE_SCOPED_LOCK(shareable_section_); ... }
91 // void NotShareable() { DFAKE_SCOPED_LOCK_THREAD_LOCKED(ctor_dtor_); ... }
94 // DFAKE_MUTEX(ctor_dtor_);
95 // DFAKE_MUTEX(shareable_section_);
101 // Defines a class member that acts like a mutex. It is used only as a
102 // verification tool.
103 #define DFAKE_MUTEX(obj) \
104 mutable base::ThreadCollisionWarner obj
105 // Asserts the call is never called simultaneously in two threads. Used at
106 // member function scope.
107 #define DFAKE_SCOPED_LOCK(obj) \
108 base::ThreadCollisionWarner::ScopedCheck s_check_##obj(&obj)
109 // Asserts the call is never called simultaneously in two threads. Used at
110 // member function scope. Same as DFAKE_SCOPED_LOCK but allows recursive locks.
111 #define DFAKE_SCOPED_RECURSIVE_LOCK(obj) \
112 base::ThreadCollisionWarner::ScopedRecursiveCheck sr_check_##obj(&obj)
113 // Asserts the code is always executed in the same thread.
114 #define DFAKE_SCOPED_LOCK_THREAD_LOCKED(obj) \
115 base::ThreadCollisionWarner::Check check_##obj(&obj)
119 #define DFAKE_MUTEX(obj)
120 #define DFAKE_SCOPED_LOCK(obj) ((void)0)
121 #define DFAKE_SCOPED_RECURSIVE_LOCK(obj) ((void)0)
122 #define DFAKE_SCOPED_LOCK_THREAD_LOCKED(obj) ((void)0)
128 // The class ThreadCollisionWarner uses an Asserter to notify the collision
129 // AsserterBase is the interfaces and DCheckAsserter is the default asserter
130 // used. During the unit tests is used another class that doesn't "DCHECK"
131 // in case of collision (check thread_collision_warner_unittests.cc)
132 struct AsserterBase
{
133 virtual ~AsserterBase() {}
134 virtual void warn() = 0;
137 struct DCheckAsserter
: public AsserterBase
{
138 virtual ~DCheckAsserter() {}
142 class ThreadCollisionWarner
{
144 // The parameter asserter is there only for test purpose
145 ThreadCollisionWarner(AsserterBase
* asserter
= new DCheckAsserter())
146 : valid_thread_id_(0),
148 asserter_(asserter
) {}
150 ~ThreadCollisionWarner() {
154 // This class is meant to be used through the macro
155 // DFAKE_SCOPED_LOCK_THREAD_LOCKED
156 // it doesn't leave the critical section, as opposed to ScopedCheck,
157 // because the critical section being pinned is allowed to be used only
161 explicit Check(ThreadCollisionWarner
* warner
)
163 warner_
->EnterSelf();
169 ThreadCollisionWarner
* warner_
;
171 DISALLOW_COPY_AND_ASSIGN(Check
);
174 // This class is meant to be used through the macro
178 explicit ScopedCheck(ThreadCollisionWarner
* warner
)
188 ThreadCollisionWarner
* warner_
;
190 DISALLOW_COPY_AND_ASSIGN(ScopedCheck
);
193 // This class is meant to be used through the macro
194 // DFAKE_SCOPED_RECURSIVE_LOCK
195 class ScopedRecursiveCheck
{
197 explicit ScopedRecursiveCheck(ThreadCollisionWarner
* warner
)
199 warner_
->EnterSelf();
202 ~ScopedRecursiveCheck() {
207 ThreadCollisionWarner
* warner_
;
209 DISALLOW_COPY_AND_ASSIGN(ScopedRecursiveCheck
);
213 // This method stores the current thread identifier and does a DCHECK
214 // if a another thread has already done it, it is safe if same thread
215 // calls this multiple time (recursion allowed).
218 // Same as EnterSelf but recursion is not allowed.
221 // Removes the thread_id stored in order to allow other threads to
222 // call EnterSelf or Enter.
225 // This stores the thread id that is inside the critical section, if the
226 // value is 0 then no thread is inside.
227 volatile subtle::Atomic32 valid_thread_id_
;
229 // Counter to trace how many time a critical section was "pinned"
230 // (when allowed) in order to unpin it when counter_ reaches 0.
231 volatile subtle::Atomic32 counter_
;
233 // Here only for class unit tests purpose, during the test I need to not
234 // DCHECK but notify the collision with something else.
235 AsserterBase
* asserter_
;
237 DISALLOW_COPY_AND_ASSIGN(ThreadCollisionWarner
);
242 #endif // BASE_THREAD_COLLISION_WARNER_H_