value_future.h

// Copyright 2025 The Pigweed 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.
#pragma once
 
#include <mutex>
#include <optional>
#include <type_traits>
 
#include "pw_assert/assert.h"
#include "pw_async2/future.h"
#include "pw_polyfill/language_feature_macros.h"
#include "pw_sync/interrupt_spin_lock.h"
 
namespace pw::async2 {
namespace internal {
 
inline sync::InterruptSpinLock& ValueProviderLock() {
  PW_CONSTINIT static sync::InterruptSpinLock lock;
  return lock;
}
 
bool PendValueFutureCore(FutureCore& core, Context& cx)
    PW_EXCLUSIVE_LOCKS_REQUIRED(ValueProviderLock());
 
}  // namespace internal
 
template <typename T>
class ValueProvider;
template <typename T>
class BroadcastValueProvider;
 
 
template <typename T>
class ValueFuture {
 public:
  using value_type = T;
 
  constexpr ValueFuture() = default;
 
  ValueFuture(ValueFuture&& other) noexcept
      PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    *this = std::move(other);
  }
 
  ValueFuture& operator=(ValueFuture&& other) noexcept
      PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    if (this != &other) {
      std::lock_guard lock(internal::ValueProviderLock());
      core_ = std::move(other.core_);
      value_ = std::move(other.value_);
    }
    return *this;
  }
 
  ~ValueFuture() PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    std::lock_guard lock(internal::ValueProviderLock());
    core_.Unlist();
  }
 
  template <typename... Args>
  static ValueFuture Resolved(Args&&... args) {
    return ValueFuture(std::in_place, std::forward<Args>(args)...);
  }
 
  Poll<T> Pend(Context& cx) {
    // ValueFuture uses a global lock so that futures don't have to access their
    // provider to get a lock after they're completed. This ensures the
    // ValueFuture never needs to access the provider.
    //
    // With some care (and complexity), the lock could be moved to the provider.
    // A global lock is simpler and more efficient in practice.
    std::lock_guard lock(internal::ValueProviderLock());
    if (internal::PendValueFutureCore(core_, cx)) {
      return Pending();
    }
    return Ready(std::move(*value_));
  }
 
  [[nodiscard]] bool is_pendable() const {
    std::lock_guard lock(internal::ValueProviderLock());
    return core_.is_pendable();
  }
 
  [[nodiscard]] bool is_complete() const {
    std::lock_guard lock(internal::ValueProviderLock());
    return core_.is_complete();
  }
 
 private:
  friend class ValueProvider<T>;
  friend class BroadcastValueProvider<T>;
 
  template <typename... Args>
  explicit ValueFuture(std::in_place_t, Args&&... args)
      : core_(FutureState::kReadyForCompletion),
        value_(std::in_place, std::forward<Args>(args)...) {}
 
  ValueFuture(FutureState::Pending) : core_(FutureState::kPending) {}
 
  template <typename... Args>
  void ResolveLocked(Args&&... args)
      PW_EXCLUSIVE_LOCKS_REQUIRED(internal::ValueProviderLock()) {
    // SAFETY: This is only called from FutureList with the lock held.
    PW_DASSERT(!value_.has_value());
    value_.emplace(std::forward<Args>(args)...);
    core_.WakeAndMarkReady();
  }
 
  FutureCore core_ PW_GUARDED_BY(internal::ValueProviderLock());
  std::optional<T> value_ PW_GUARDED_BY(internal::ValueProviderLock());
};
 
template <>
class ValueFuture<void> {
 public:
  using value_type = void;
 
  constexpr ValueFuture() = default;
 
  ValueFuture(ValueFuture&& other) noexcept
      PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    *this = std::move(other);
  }
 
  ValueFuture& operator=(ValueFuture&& other) noexcept
      PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    if (this != &other) {
      std::lock_guard lock(internal::ValueProviderLock());
      core_ = std::move(other.core_);
    }
    return *this;
  }
 
  ~ValueFuture() PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    std::lock_guard lock(internal::ValueProviderLock());
    core_.Unlist();
  }
 
  Poll<> Pend(Context& cx) {
    std::lock_guard lock(internal::ValueProviderLock());
    if (internal::PendValueFutureCore(core_, cx)) {
      return Pending();
    }
    return Ready();
  }
 
  [[nodiscard]] bool is_pendable() const {
    std::lock_guard lock(internal::ValueProviderLock());
    return core_.is_pendable();
  }
 
  [[nodiscard]] bool is_complete() const {
    std::lock_guard lock(internal::ValueProviderLock());
    return core_.is_complete();
  }
 
  static ValueFuture Resolved() {
    return ValueFuture(FutureState::kReadyForCompletion);
  }
 
 private:
  friend class ValueProvider<void>;
  friend class BroadcastValueProvider<void>;
 
  explicit ValueFuture(FutureState::ReadyForCompletion)
      : core_(FutureState::kReadyForCompletion) {}
 
  explicit ValueFuture(FutureState::Pending) : core_(FutureState::kPending) {}
 
  FutureCore core_ PW_GUARDED_BY(internal::ValueProviderLock());
};
 
using VoidFuture = ValueFuture<void>;
 
template <typename T>
using OptionalValueFuture = ValueFuture<std::optional<T>>;
 
template <typename T>
class BroadcastValueProvider {
 public:
  constexpr BroadcastValueProvider() = default;
 
  BroadcastValueProvider(BroadcastValueProvider&& other) noexcept
      PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    std::lock_guard lock(internal::ValueProviderLock());
    list_ = std::move(other.list_);
  }
 
  BroadcastValueProvider& operator=(BroadcastValueProvider&& other) noexcept
      PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    if (this != &other) {
      std::lock_guard lock(internal::ValueProviderLock());
      PW_ASSERT(list_.empty());  // ensure any futures were resolved
      list_ = std::move(other.list_);
    }
    return *this;
  }
 
  BroadcastValueProvider(const BroadcastValueProvider&) = delete;
  BroadcastValueProvider& operator=(const BroadcastValueProvider&) = delete;
 
  ~BroadcastValueProvider() { PW_ASSERT(list_.empty()); }
 
  ValueFuture<T> Get() {
    ValueFuture<T> future(FutureState::kPending);
    {
      std::lock_guard lock(internal::ValueProviderLock());
      list_.Push(future.core_);
    }
    return future;
  }
 
  template <typename U = T, std::enable_if_t<!std::is_void_v<U>, int> = 0>
  void Resolve(const U& value) {
    std::lock_guard lock(internal::ValueProviderLock());
    list_.ResolveAllWith(
        [&](ValueFuture<T>& future)
            PW_NO_LOCK_SAFETY_ANALYSIS { future.ResolveLocked(value); });
  }
 
  template <typename U = T, std::enable_if_t<std::is_void_v<U>, int> = 0>
  void Resolve() {
    std::lock_guard lock(internal::ValueProviderLock());
    list_.ResolveAll();
  }
 
 private:
  FutureList<&ValueFuture<T>::core_> list_
      PW_GUARDED_BY(internal::ValueProviderLock());
};
 
template <typename T>
class ValueProvider {
 public:
  constexpr ValueProvider() = default;
 
  ValueProvider(ValueProvider&& other) noexcept
      PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    std::lock_guard lock(internal::ValueProviderLock());
    list_ = std::move(other.list_);
  }
 
  ValueProvider& operator=(ValueProvider&& other) noexcept
      PW_LOCKS_EXCLUDED(internal::ValueProviderLock()) {
    if (this != &other) {
      std::lock_guard lock(internal::ValueProviderLock());
      PW_ASSERT(list_.empty());  // ensure any futures were resolved
      list_ = std::move(other.list_);
    }
    return *this;
  }
 
  ValueProvider(const ValueProvider&) = delete;
  ValueProvider& operator=(const ValueProvider&) = delete;
 
  ~ValueProvider() { PW_ASSERT(list_.empty()); }
 
  ValueFuture<T> Get() {
    ValueFuture<T> future(FutureState::kPending);
    {
      std::lock_guard lock(internal::ValueProviderLock());
      list_.PushRequireEmpty(future.core_);
    }
    return future;
  }
 
  std::optional<ValueFuture<T>> TryGet() {
    ValueFuture<T> future(FutureState::kPending);
    {
      std::lock_guard lock(internal::ValueProviderLock());
      if (!list_.PushIfEmpty(future.core_)) {
        return std::nullopt;
      }
    }
    return future;
  }
 
  bool has_future() const {
    std::lock_guard lock(internal::ValueProviderLock());
    return !list_.empty();
  }
 
  template <typename... Args,
            typename U = T,
            std::enable_if_t<!std::is_void_v<U>, int> = 0>
  void Resolve(Args&&... args) {
    std::lock_guard lock(internal::ValueProviderLock());
    if (ValueFuture<T>* future = list_.PopIfAvailable(); future != nullptr) {
      future->ResolveLocked(std::forward<Args>(args)...);
    };
  }
 
  template <typename U = T, std::enable_if_t<std::is_void_v<U>, int> = 0>
  void Resolve() {
    std::lock_guard lock(internal::ValueProviderLock());
    list_.ResolveOneIfAvailable();
  }
 
 private:
  FutureList<&ValueFuture<T>::core_> list_
      PW_GUARDED_BY(internal::ValueProviderLock());
};
 
template <typename T>
class OptionalValueProvider {
 public:
  OptionalValueProvider() = default;
 
  OptionalValueProvider(OptionalValueProvider&&) = default;
  OptionalValueProvider& operator=(OptionalValueProvider&& other) {
    Cancel();
    provider_ = std::move(other.provider_);
    return *this;
  }
 
  OptionalValueProvider(const OptionalValueProvider&) = delete;
  OptionalValueProvider& operator=(const OptionalValueProvider&) = delete;
 
  ~OptionalValueProvider() { Cancel(); }
 
  OptionalValueFuture<T> Get() { return provider_.Get(); }
 
  template <typename... Args>
  void Resolve(Args&&... args) {
    provider_.Resolve(std::in_place, std::forward<Args>(args)...);
  }
 
  void Cancel() { provider_.Resolve(std::nullopt); }
 
 private:
  ValueProvider<std::optional<T>> provider_;
};
 
template <typename T>
class OptionalBroadcastValueProvider {
 public:
  OptionalBroadcastValueProvider() = default;
 
  OptionalBroadcastValueProvider(OptionalBroadcastValueProvider&&) = default;
  OptionalBroadcastValueProvider& operator=(
      OptionalBroadcastValueProvider&& other) {
    Cancel();
    provider_ = std::move(other.provider_);
    return *this;
  }
 
  OptionalBroadcastValueProvider(const OptionalBroadcastValueProvider&) =
      delete;
  OptionalBroadcastValueProvider& operator=(
      const OptionalBroadcastValueProvider&) = delete;
 
  ~OptionalBroadcastValueProvider() { Cancel(); }
 
  OptionalValueFuture<T> Get() { return provider_.Get(); }
 
  void Resolve(const T& value) { provider_.Resolve(value); }
 
  void Cancel() { provider_.Resolve(std::nullopt); }
 
 private:
  BroadcastValueProvider<std::optional<T>> provider_;
};
 
 
}  // namespace pw::async2