1 // Copyright 2017 The Abseil Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 //
15 // Core interfaces and definitions used by by low-level interfaces such as
16 // SpinLock.
17
18 #ifndef ABSL_BASE_INTERNAL_LOW_LEVEL_SCHEDULING_H_
19 #define ABSL_BASE_INTERNAL_LOW_LEVEL_SCHEDULING_H_
20
21 #include "absl/base/internal/raw_logging.h"
22 #include "absl/base/internal/scheduling_mode.h"
23 #include "absl/base/macros.h"
24
25 // The following two declarations exist so SchedulingGuard may friend them with
26 // the appropriate language linkage. These callbacks allow libc internals, such
27 // as function level statics, to schedule cooperatively when locking.
28 extern "C" bool __google_disable_rescheduling(void);
29 extern "C" void __google_enable_rescheduling(bool disable_result);
30
31 namespace absl {
32 ABSL_NAMESPACE_BEGIN
33 class CondVar;
34 class Mutex;
35
36 namespace synchronization_internal {
37 int MutexDelay(int32_t c, int mode);
38 } // namespace synchronization_internal
39
40 namespace base_internal {
41
42 class SchedulingHelper; // To allow use of SchedulingGuard.
43 class SpinLock; // To allow use of SchedulingGuard.
44
45 // SchedulingGuard
46 // Provides guard semantics that may be used to disable cooperative rescheduling
47 // of the calling thread within specific program blocks. This is used to
48 // protect resources (e.g. low-level SpinLocks or Domain code) that cooperative
49 // scheduling depends on.
50 //
51 // Domain implementations capable of rescheduling in reaction to involuntary
52 // kernel thread actions (e.g blocking due to a pagefault or syscall) must
53 // guarantee that an annotated thread is not allowed to (cooperatively)
54 // reschedule until the annotated region is complete.
55 //
56 // It is an error to attempt to use a cooperatively scheduled resource (e.g.
57 // Mutex) within a rescheduling-disabled region.
58 //
59 // All methods are async-signal safe.
60 class SchedulingGuard {
61 public:
62 // Returns true iff the calling thread may be cooperatively rescheduled.
63 static bool ReschedulingIsAllowed();
64
65 private:
66 // Disable cooperative rescheduling of the calling thread. It may still
67 // initiate scheduling operations (e.g. wake-ups), however, it may not itself
68 // reschedule. Nestable. The returned result is opaque, clients should not
69 // attempt to interpret it.
70 // REQUIRES: Result must be passed to a pairing EnableScheduling().
71 static bool DisableRescheduling();
72
73 // Marks the end of a rescheduling disabled region, previously started by
74 // DisableRescheduling().
75 // REQUIRES: Pairs with innermost call (and result) of DisableRescheduling().
76 static void EnableRescheduling(bool disable_result);
77
78 // A scoped helper for {Disable, Enable}Rescheduling().
79 // REQUIRES: destructor must run in same thread as constructor.
80 struct ScopedDisable {
ScopedDisableScopedDisable81 ScopedDisable() { disabled = SchedulingGuard::DisableRescheduling(); }
~ScopedDisableScopedDisable82 ~ScopedDisable() { SchedulingGuard::EnableRescheduling(disabled); }
83
84 bool disabled;
85 };
86
87 // A scoped helper to enable rescheduling temporarily.
88 // REQUIRES: destructor must run in same thread as constructor.
89 class ScopedEnable {
90 public:
91 ScopedEnable();
92 ~ScopedEnable();
93
94 private:
95 int scheduling_disabled_depth_;
96 };
97
98 // Access to SchedulingGuard is explicitly permitted.
99 friend class absl::CondVar;
100 friend class absl::Mutex;
101 friend class SchedulingHelper;
102 friend class SpinLock;
103 friend int absl::synchronization_internal::MutexDelay(int32_t c, int mode);
104
105 SchedulingGuard(const SchedulingGuard&) = delete;
106 SchedulingGuard& operator=(const SchedulingGuard&) = delete;
107 };
108
109 //------------------------------------------------------------------------------
110 // End of public interfaces.
111 //------------------------------------------------------------------------------
112
ReschedulingIsAllowed()113 inline bool SchedulingGuard::ReschedulingIsAllowed() {
114 return false;
115 }
116
DisableRescheduling()117 inline bool SchedulingGuard::DisableRescheduling() {
118 return false;
119 }
120
EnableRescheduling(bool)121 inline void SchedulingGuard::EnableRescheduling(bool /* disable_result */) {
122 return;
123 }
124
ScopedEnable()125 inline SchedulingGuard::ScopedEnable::ScopedEnable()
126 : scheduling_disabled_depth_(0) {}
~ScopedEnable()127 inline SchedulingGuard::ScopedEnable::~ScopedEnable() {
128 ABSL_RAW_CHECK(scheduling_disabled_depth_ == 0, "disable unused warning");
129 }
130
131 } // namespace base_internal
132 ABSL_NAMESPACE_END
133 } // namespace absl
134
135 #endif // ABSL_BASE_INTERNAL_LOW_LEVEL_SCHEDULING_H_
136