xref: /aosp_15_r20/external/angle/third_party/abseil-cpp/absl/synchronization/notification.h (revision 8975f5c5ed3d1c378011245431ada316dfb6f244)
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 // -----------------------------------------------------------------------------
16 // notification.h
17 // -----------------------------------------------------------------------------
18 //
19 // This header file defines a `Notification` abstraction, which allows threads
20 // to receive notification of a single occurrence of a single event.
21 //
22 // The `Notification` object maintains a private boolean "notified" state that
23 // transitions to `true` at most once. The `Notification` class provides the
24 // following primary member functions:
25 //   * `HasBeenNotified()` to query its state
26 //   * `WaitForNotification*()` to have threads wait until the "notified" state
27 //      is `true`.
28 //   * `Notify()` to set the notification's "notified" state to `true` and
29 //     notify all waiting threads that the event has occurred.
30 //     This method may only be called once.
31 //
32 // Note that while `Notify()` may only be called once, it is perfectly valid to
33 // call any of the `WaitForNotification*()` methods multiple times, from
34 // multiple threads -- even after the notification's "notified" state has been
35 // set -- in which case those methods will immediately return.
36 //
37 // Note that the lifetime of a `Notification` requires careful consideration;
38 // it might not be safe to destroy a notification after calling `Notify()` since
39 // it is still legal for other threads to call `WaitForNotification*()` methods
40 // on the notification. However, observers responding to a "notified" state of
41 // `true` can safely delete the notification without interfering with the call
42 // to `Notify()` in the other thread.
43 //
44 // Memory ordering: For any threads X and Y, if X calls `Notify()`, then any
45 // action taken by X before it calls `Notify()` is visible to thread Y after:
46 //  * Y returns from `WaitForNotification()`, or
47 //  * Y receives a `true` return value from either `HasBeenNotified()` or
48 //    `WaitForNotificationWithTimeout()`.
49 
50 #ifndef ABSL_SYNCHRONIZATION_NOTIFICATION_H_
51 #define ABSL_SYNCHRONIZATION_NOTIFICATION_H_
52 
53 #include <atomic>
54 
55 #include "absl/base/attributes.h"
56 #include "absl/base/internal/tracing.h"
57 #include "absl/synchronization/mutex.h"
58 #include "absl/time/time.h"
59 
60 namespace absl {
61 ABSL_NAMESPACE_BEGIN
62 
63 // -----------------------------------------------------------------------------
64 // Notification
65 // -----------------------------------------------------------------------------
66 class Notification {
67  public:
68   // Initializes the "notified" state to unnotified.
Notification()69   Notification() : notified_yet_(false) {}
Notification(bool prenotify)70   explicit Notification(bool prenotify) : notified_yet_(prenotify) {}
71   Notification(const Notification&) = delete;
72   Notification& operator=(const Notification&) = delete;
73   ~Notification();
74 
75   // Notification::HasBeenNotified()
76   //
77   // Returns the value of the notification's internal "notified" state.
HasBeenNotified()78   ABSL_MUST_USE_RESULT bool HasBeenNotified() const {
79     if (HasBeenNotifiedInternal(&this->notified_yet_)) {
80       base_internal::TraceObserved(this, TraceObjectKind());
81       return true;
82     }
83     return false;
84   }
85 
86   // Notification::WaitForNotification()
87   //
88   // Blocks the calling thread until the notification's "notified" state is
89   // `true`. Note that if `Notify()` has been previously called on this
90   // notification, this function will immediately return.
91   void WaitForNotification() const;
92 
93   // Notification::WaitForNotificationWithTimeout()
94   //
95   // Blocks until either the notification's "notified" state is `true` (which
96   // may occur immediately) or the timeout has elapsed, returning the value of
97   // its "notified" state in either case.
98   bool WaitForNotificationWithTimeout(absl::Duration timeout) const;
99 
100   // Notification::WaitForNotificationWithDeadline()
101   //
102   // Blocks until either the notification's "notified" state is `true` (which
103   // may occur immediately) or the deadline has expired, returning the value of
104   // its "notified" state in either case.
105   bool WaitForNotificationWithDeadline(absl::Time deadline) const;
106 
107   // Notification::Notify()
108   //
109   // Sets the "notified" state of this notification to `true` and wakes waiting
110   // threads. Note: do not call `Notify()` multiple times on the same
111   // `Notification`; calling `Notify()` more than once on the same notification
112   // results in undefined behavior.
113   void Notify();
114 
115  private:
116   // Convenience helper to reduce verbosity at call sites.
TraceObjectKind()117   static inline constexpr base_internal::ObjectKind TraceObjectKind() {
118     return base_internal::ObjectKind::kNotification;
119   }
120 
HasBeenNotifiedInternal(const std::atomic<bool> * notified_yet)121   static inline bool HasBeenNotifiedInternal(
122       const std::atomic<bool>* notified_yet) {
123     return notified_yet->load(std::memory_order_acquire);
124   }
125 
126   mutable Mutex mutex_;
127   std::atomic<bool> notified_yet_;  // written under mutex_
128 };
129 
130 ABSL_NAMESPACE_END
131 }  // namespace absl
132 
133 #endif  // ABSL_SYNCHRONIZATION_NOTIFICATION_H_
134