// Copyright 2017 The Abseil Authors. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // // Core interfaces and definitions used by by low-level interfaces such as // SpinLock. #ifndef ABSL_BASE_INTERNAL_LOW_LEVEL_SCHEDULING_H_ #define ABSL_BASE_INTERNAL_LOW_LEVEL_SCHEDULING_H_ #include "absl/base/internal/raw_logging.h" #include "absl/base/internal/scheduling_mode.h" #include "absl/base/macros.h" // The following two declarations exist so SchedulingGuard may friend them with // the appropriate language linkage. These callbacks allow libc internals, such // as function level statics, to schedule cooperatively when locking. extern "C" bool __google_disable_rescheduling(void); extern "C" void __google_enable_rescheduling(bool disable_result); namespace absl { ABSL_NAMESPACE_BEGIN class CondVar; class Mutex; namespace synchronization_internal { int MutexDelay(int32_t c, int mode); } // namespace synchronization_internal namespace base_internal { class SchedulingHelper; // To allow use of SchedulingGuard. class SpinLock; // To allow use of SchedulingGuard. // SchedulingGuard // Provides guard semantics that may be used to disable cooperative rescheduling // of the calling thread within specific program blocks. This is used to // protect resources (e.g. low-level SpinLocks or Domain code) that cooperative // scheduling depends on. // // Domain implementations capable of rescheduling in reaction to involuntary // kernel thread actions (e.g blocking due to a pagefault or syscall) must // guarantee that an annotated thread is not allowed to (cooperatively) // reschedule until the annotated region is complete. // // It is an error to attempt to use a cooperatively scheduled resource (e.g. // Mutex) within a rescheduling-disabled region. // // All methods are async-signal safe. class SchedulingGuard { public: // Returns true iff the calling thread may be cooperatively rescheduled. static bool ReschedulingIsAllowed(); SchedulingGuard(const SchedulingGuard&) = delete; SchedulingGuard& operator=(const SchedulingGuard&) = delete; private: // Disable cooperative rescheduling of the calling thread. It may still // initiate scheduling operations (e.g. wake-ups), however, it may not itself // reschedule. Nestable. The returned result is opaque, clients should not // attempt to interpret it. // REQUIRES: Result must be passed to a pairing EnableScheduling(). static bool DisableRescheduling(); // Marks the end of a rescheduling disabled region, previously started by // DisableRescheduling(). // REQUIRES: Pairs with innermost call (and result) of DisableRescheduling(). static void EnableRescheduling(bool disable_result); // A scoped helper for {Disable, Enable}Rescheduling(). // REQUIRES: destructor must run in same thread as constructor. struct ScopedDisable { ScopedDisable() { disabled = SchedulingGuard::DisableRescheduling(); } ~ScopedDisable() { SchedulingGuard::EnableRescheduling(disabled); } bool disabled; }; // A scoped helper to enable rescheduling temporarily. // REQUIRES: destructor must run in same thread as constructor. class ScopedEnable { public: ScopedEnable(); ~ScopedEnable(); private: int scheduling_disabled_depth_; }; // Access to SchedulingGuard is explicitly permitted. friend class absl::CondVar; friend class absl::Mutex; friend class SchedulingHelper; friend class SpinLock; friend int absl::synchronization_internal::MutexDelay(int32_t c, int mode); }; //------------------------------------------------------------------------------ // End of public interfaces. //------------------------------------------------------------------------------ inline bool SchedulingGuard::ReschedulingIsAllowed() { return false; } inline bool SchedulingGuard::DisableRescheduling() { return false; } inline void SchedulingGuard::EnableRescheduling(bool /* disable_result */) { return; } inline SchedulingGuard::ScopedEnable::ScopedEnable() : scheduling_disabled_depth_(0) {} inline SchedulingGuard::ScopedEnable::~ScopedEnable() { ABSL_RAW_CHECK(scheduling_disabled_depth_ == 0, "disable unused warning"); } } // namespace base_internal ABSL_NAMESPACE_END } // namespace absl #endif // ABSL_BASE_INTERNAL_LOW_LEVEL_SCHEDULING_H_