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/scheduling_mode.h"
22#include "absl/base/macros.h"
23
24// The following two declarations exist so SchedulingGuard may friend them with
25// the appropriate language linkage. These callbacks allow libc internals, such
26// as function level statics, to schedule cooperatively when locking.
27extern "C" bool __google_disable_rescheduling(void);
28extern "C" void __google_enable_rescheduling(bool disable_result);
29
30namespace absl {
31namespace base_internal {
32
33class SchedulingHelper; // To allow use of SchedulingGuard.
34class SpinLock; // To allow use of SchedulingGuard.
35
36// SchedulingGuard
37// Provides guard semantics that may be used to disable cooperative rescheduling
38// of the calling thread within specific program blocks. This is used to
39// protect resources (e.g. low-level SpinLocks or Domain code) that cooperative
40// scheduling depends on.
41//
42// Domain implementations capable of rescheduling in reaction to involuntary
43// kernel thread actions (e.g blocking due to a pagefault or syscall) must
44// guarantee that an annotated thread is not allowed to (cooperatively)
45// reschedule until the annotated region is complete.
46//
47// It is an error to attempt to use a cooperatively scheduled resource (e.g.
48// Mutex) within a rescheduling-disabled region.
49//
50// All methods are async-signal safe.
51class SchedulingGuard {
52 public:
53 // Returns true iff the calling thread may be cooperatively rescheduled.
54 static bool ReschedulingIsAllowed();
55
56 private:
57 // Disable cooperative rescheduling of the calling thread. It may still
58 // initiate scheduling operations (e.g. wake-ups), however, it may not itself
59 // reschedule. Nestable. The returned result is opaque, clients should not
60 // attempt to interpret it.
61 // REQUIRES: Result must be passed to a pairing EnableScheduling().
62 static bool DisableRescheduling();
63
64 // Marks the end of a rescheduling disabled region, previously started by
65 // DisableRescheduling().
66 // REQUIRES: Pairs with innermost call (and result) of DisableRescheduling().
67 static void EnableRescheduling(bool disable_result);
68
69 // A scoped helper for {Disable, Enable}Rescheduling().
70 // REQUIRES: destructor must run in same thread as constructor.
71 struct ScopedDisable {
72 ScopedDisable() { disabled = SchedulingGuard::DisableRescheduling(); }
73 ~ScopedDisable() { SchedulingGuard::EnableRescheduling(disabled); }
74
75 bool disabled;
76 };
77
78 // Access to SchedulingGuard is explicitly white-listed.
79 friend class SchedulingHelper;
80 friend class SpinLock;
81
82 SchedulingGuard(const SchedulingGuard&) = delete;
83 SchedulingGuard& operator=(const SchedulingGuard&) = delete;
84};
85
86//------------------------------------------------------------------------------
87// End of public interfaces.
88//------------------------------------------------------------------------------
89
90inline bool SchedulingGuard::ReschedulingIsAllowed() {
91 return false;
92}
93
94inline bool SchedulingGuard::DisableRescheduling() {
95 return false;
96}
97
98inline void SchedulingGuard::EnableRescheduling(bool /* disable_result */) {
99 return;
100}
101
102} // namespace base_internal
103} // namespace absl
104
105#endif // ABSL_BASE_INTERNAL_LOW_LEVEL_SCHEDULING_H_
106