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/macros.h" 56 #include "absl/synchronization/mutex.h" 57 #include "absl/time/time.h" 58 59 namespace absl { 60 ABSL_NAMESPACE_BEGIN 61 62 // ----------------------------------------------------------------------------- 63 // Notification 64 // ----------------------------------------------------------------------------- 65 class Notification { 66 public: 67 // Initializes the "notified" state to unnotified. Notification()68 Notification() : notified_yet_(false) {} Notification(bool prenotify)69 explicit Notification(bool prenotify) : notified_yet_(prenotify) {} 70 Notification(const Notification&) = delete; 71 Notification& operator=(const Notification&) = delete; 72 ~Notification(); 73 74 // Notification::HasBeenNotified() 75 // 76 // Returns the value of the notification's internal "notified" state. HasBeenNotified()77 bool HasBeenNotified() const { 78 return HasBeenNotifiedInternal(&this->notified_yet_); 79 } 80 81 // Notification::WaitForNotification() 82 // 83 // Blocks the calling thread until the notification's "notified" state is 84 // `true`. Note that if `Notify()` has been previously called on this 85 // notification, this function will immediately return. 86 void WaitForNotification() const; 87 88 // Notification::WaitForNotificationWithTimeout() 89 // 90 // Blocks until either the notification's "notified" state is `true` (which 91 // may occur immediately) or the timeout has elapsed, returning the value of 92 // its "notified" state in either case. 93 bool WaitForNotificationWithTimeout(absl::Duration timeout) const; 94 95 // Notification::WaitForNotificationWithDeadline() 96 // 97 // Blocks until either the notification's "notified" state is `true` (which 98 // may occur immediately) or the deadline has expired, returning the value of 99 // its "notified" state in either case. 100 bool WaitForNotificationWithDeadline(absl::Time deadline) const; 101 102 // Notification::Notify() 103 // 104 // Sets the "notified" state of this notification to `true` and wakes waiting 105 // threads. Note: do not call `Notify()` multiple times on the same 106 // `Notification`; calling `Notify()` more than once on the same notification 107 // results in undefined behavior. 108 void Notify(); 109 110 private: HasBeenNotifiedInternal(const std::atomic<bool> * notified_yet)111 static inline bool HasBeenNotifiedInternal( 112 const std::atomic<bool>* notified_yet) { 113 return notified_yet->load(std::memory_order_acquire); 114 } 115 116 mutable Mutex mutex_; 117 std::atomic<bool> notified_yet_; // written under mutex_ 118 }; 119 120 ABSL_NAMESPACE_END 121 } // namespace absl 122 123 #endif // ABSL_SYNCHRONIZATION_NOTIFICATION_H_ 124