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


abseil_cpp
Author(s):
autogenerated on Wed Jun 19 2019 19:19:57