124 lines
5.0 KiB
C++
124 lines
5.0 KiB
C++
// 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.
|
|
//
|
|
// -----------------------------------------------------------------------------
|
|
// notification.h
|
|
// -----------------------------------------------------------------------------
|
|
//
|
|
// This header file defines a `Notification` abstraction, which allows threads
|
|
// to receive notification of a single occurrence of a single event.
|
|
//
|
|
// The `Notification` object maintains a private boolean "notified" state that
|
|
// transitions to `true` at most once. The `Notification` class provides the
|
|
// following primary member functions:
|
|
// * `HasBeenNotified() `to query its state
|
|
// * `WaitForNotification*()` to have threads wait until the "notified" state
|
|
// is `true`.
|
|
// * `Notify()` to set the notification's "notified" state to `true` and
|
|
// notify all waiting threads that the event has occurred.
|
|
// This method may only be called once.
|
|
//
|
|
// Note that while `Notify()` may only be called once, it is perfectly valid to
|
|
// call any of the `WaitForNotification*()` methods multiple times, from
|
|
// multiple threads -- even after the notification's "notified" state has been
|
|
// set -- in which case those methods will immediately return.
|
|
//
|
|
// Note that the lifetime of a `Notification` requires careful consideration;
|
|
// it might not be safe to destroy a notification after calling `Notify()` since
|
|
// it is still legal for other threads to call `WaitForNotification*()` methods
|
|
// on the notification. However, observers responding to a "notified" state of
|
|
// `true` can safely delete the notification without interfering with the call
|
|
// to `Notify()` in the other thread.
|
|
//
|
|
// Memory ordering: For any threads X and Y, if X calls `Notify()`, then any
|
|
// action taken by X before it calls `Notify()` is visible to thread Y after:
|
|
// * Y returns from `WaitForNotification()`, or
|
|
// * Y receives a `true` return value from either `HasBeenNotified()` or
|
|
// `WaitForNotificationWithTimeout()`.
|
|
|
|
#ifndef ABSL_SYNCHRONIZATION_NOTIFICATION_H_
|
|
#define ABSL_SYNCHRONIZATION_NOTIFICATION_H_
|
|
|
|
#include <atomic>
|
|
|
|
#include "absl/base/macros.h"
|
|
#include "absl/synchronization/mutex.h"
|
|
#include "absl/time/time.h"
|
|
|
|
namespace absl {
|
|
ABSL_NAMESPACE_BEGIN
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// Notification
|
|
// -----------------------------------------------------------------------------
|
|
class Notification {
|
|
public:
|
|
// Initializes the "notified" state to unnotified.
|
|
Notification() : notified_yet_(false) {}
|
|
explicit Notification(bool prenotify) : notified_yet_(prenotify) {}
|
|
Notification(const Notification&) = delete;
|
|
Notification& operator=(const Notification&) = delete;
|
|
~Notification();
|
|
|
|
// Notification::HasBeenNotified()
|
|
//
|
|
// Returns the value of the notification's internal "notified" state.
|
|
bool HasBeenNotified() const {
|
|
return HasBeenNotifiedInternal(&this->notified_yet_);
|
|
}
|
|
|
|
// Notification::WaitForNotification()
|
|
//
|
|
// Blocks the calling thread until the notification's "notified" state is
|
|
// `true`. Note that if `Notify()` has been previously called on this
|
|
// notification, this function will immediately return.
|
|
void WaitForNotification() const;
|
|
|
|
// Notification::WaitForNotificationWithTimeout()
|
|
//
|
|
// Blocks until either the notification's "notified" state is `true` (which
|
|
// may occur immediately) or the timeout has elapsed, returning the value of
|
|
// its "notified" state in either case.
|
|
bool WaitForNotificationWithTimeout(absl::Duration timeout) const;
|
|
|
|
// Notification::WaitForNotificationWithDeadline()
|
|
//
|
|
// Blocks until either the notification's "notified" state is `true` (which
|
|
// may occur immediately) or the deadline has expired, returning the value of
|
|
// its "notified" state in either case.
|
|
bool WaitForNotificationWithDeadline(absl::Time deadline) const;
|
|
|
|
// Notification::Notify()
|
|
//
|
|
// Sets the "notified" state of this notification to `true` and wakes waiting
|
|
// threads. Note: do not call `Notify()` multiple times on the same
|
|
// `Notification`; calling `Notify()` more than once on the same notification
|
|
// results in undefined behavior.
|
|
void Notify();
|
|
|
|
private:
|
|
static inline bool HasBeenNotifiedInternal(
|
|
const std::atomic<bool>* notified_yet) {
|
|
return notified_yet->load(std::memory_order_acquire);
|
|
}
|
|
|
|
mutable Mutex mutex_;
|
|
std::atomic<bool> notified_yet_; // written under mutex_
|
|
};
|
|
|
|
ABSL_NAMESPACE_END
|
|
} // namespace absl
|
|
|
|
#endif // ABSL_SYNCHRONIZATION_NOTIFICATION_H_
|