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
 
#ifdef __cpp_concepts
#include <concepts>
#endif  // __cpp_concepts
 
#include <mutex>
#include <optional>
#include <type_traits>
 
#include "lib/stdcompat/utility.h"
#include "pw_assert/assert.h"
#include "pw_async2/poll.h"
#include "pw_async2/task.h"
#include "pw_async2/waker.h"
#include "pw_containers/intrusive_list.h"
#include "pw_memory/container_of.h"
#include "pw_sync/interrupt_spin_lock.h"
 
namespace pw::async2 {
 
 
#ifdef __cpp_concepts
 
template <typename T>
concept Future = requires {
  typename T::value_type;
 
  static_cast<bool (T::*)() const>(&T::is_pendable);
 
  static_cast<bool (T::*)() const>(&T::is_complete);
 
  static_cast<Poll<typename T::value_type> (T::*)(Context&)>(&T::Pend);
 
} && std::default_initializable<T> && std::destructible<T> && std::movable<T>;
 
#else  // C++17 version
 
namespace internal {
 
template <typename T, typename = void>
struct is_future : std::false_type {};
 
template <typename T>
struct is_future<
    T,
    std::void_t<typename T::value_type,
                decltype(std::declval<T&>().Pend(std::declval<Context&>())),
                decltype(std::declval<const T&>().is_pendable()),
                decltype(std::declval<const T&>().is_complete())>>
    : std::conjunction<
          std::is_convertible<decltype(&T::is_pendable), bool (T::*)() const>,
          std::is_convertible<decltype(&T::is_complete), bool (T::*)() const>,
          std::is_convertible<decltype(&T::Pend),
                              Poll<typename T::value_type> (T::*)(Context&)>,
          std::is_default_constructible<T>,
          std::is_destructible<T>> {};
 
}  // namespace internal
 
// This variable is named as a type to match the C++20 concept. This makes it
// possible to use `Future` in static asserts in either C++17 or C++20.
template <typename T>
constexpr bool Future =
    internal::is_future<std::remove_cv_t<std::remove_reference_t<T>>>::value;
 
#endif  // __cpp_concepts
 
template <typename T>
using FutureValue = std::conditional_t<std::is_void_v<typename T::value_type>,
                                       ReadyType,
                                       typename T::value_type>;
 
class FutureState {
 public:
  enum Pending { kPending };
 
  enum ReadyForCompletion { kReadyForCompletion };
 
  constexpr FutureState() : pend_state_(PendState::kEmpty) {}
 
  constexpr FutureState(Pending) : pend_state_(PendState::kPending) {}
 
  constexpr FutureState(ReadyForCompletion)
      : pend_state_(PendState::kPending), ready_(true) {}
 
  constexpr FutureState(const FutureState&) = delete;
  constexpr FutureState& operator=(const FutureState&) = delete;
 
  constexpr FutureState(FutureState&& other)
      : pend_state_(cpp20::exchange(other.pend_state_, PendState::kEmpty)),
        ready_(cpp20::exchange(other.ready_, false)) {}
 
  constexpr FutureState& operator=(FutureState&& other) {
    pend_state_ = cpp20::exchange(other.pend_state_, PendState::kEmpty);
    ready_ = cpp20::exchange(other.ready_, false);
    return *this;
  }
 
  [[nodiscard]] constexpr bool is_pendable() const {
    return pend_state_ == PendState::kPending;
  }
 
  [[nodiscard]] constexpr bool is_complete() const {
    return pend_state_ == PendState::kComplete;
  }
 
  [[nodiscard]] constexpr bool is_ready() const { return ready_; }
 
  [[nodiscard]] constexpr bool is_initialized() const {
    return pend_state_ != PendState::kEmpty;
  }
 
  void MarkReady() { ready_ = true; }
 
  void MarkComplete() { pend_state_ = PendState::kComplete; }
 
 private:
  // The future's pend_state_ is exclusively managed by the task that creates
  // and pends the future.
  enum class PendState : unsigned char {
    // The future is in a default constructed, empty state. It does not
    // represent an async operation and `Pend()` cannot be called.
    kEmpty,
 
    // `Pend()` may be called to advance the operation represented by this
    // future. `Pend()` may return `Ready()` or `Pending()`.
    kPending,
 
    // A previous call to `Pend()` returned `Ready()`.
    kComplete,
  } pend_state_;
 
  // Indicates that a future was put in a ready-to-complete state.
  //
  // The ready flag is only set by code that wakes or advances a future,
  // typically outside of the task that pends it.
  bool ready_ = false;
};
 
class FutureCore : public IntrusiveForwardList<FutureCore>::Item {
 public:
  constexpr FutureCore() = default;
 
  FutureCore(FutureCore&& other) noexcept;
 
  FutureCore& operator=(FutureCore&& other) noexcept;
 
  explicit constexpr FutureCore(FutureState::Pending)
      : state_(FutureState::kPending) {}
 
  explicit constexpr FutureCore(FutureState::ReadyForCompletion)
      : state_(FutureState::kReadyForCompletion) {}
 
  FutureCore(const FutureCore&) = delete;
  FutureCore& operator=(const FutureCore&) = delete;
 
  ~FutureCore() = default;
 
  [[nodiscard]] constexpr bool is_pendable() const {
    return state_.is_pendable();
  }
 
  [[nodiscard]] constexpr bool is_complete() const {
    return state_.is_complete();
  }
 
  [[nodiscard]] constexpr bool is_ready() const { return state_.is_ready(); }
 
  [[nodiscard]] constexpr bool is_initialized() const {
    return state_.is_initialized();
  }
 
  void Wake() { waker_.Wake(); }
 
  void WakeAndMarkReady() {
    // Mark ready before waking to guarantee so that task will run with the
    // ready future (though `is_ready()` should only be accessed in `Pend()`
    // with a lock held anyway).
    state_.MarkReady();
    Wake();
  }
 
  Waker& waker() { return waker_; }
 
  void MarkComplete() { state_.MarkComplete(); }
 
  void Unlist() { unlist(); }
 
  void Reset() {
    Unlist();
    state_ = FutureState();
  }
 
  template <typename FutureType>
  auto DoPend(FutureType& future, Context& cx) PW_NO_LOCK_SAFETY_ANALYSIS {
    PW_ASSERT(is_pendable());
 
    auto poll = future.DoPend(cx);
    if (poll.IsPending()) {
      PW_ASYNC_STORE_WAKER(cx, waker_, FutureType::kWaitReason);
    } else {
      MarkComplete();
    }
 
    return poll;
  }
 
  [[nodiscard]] bool in_list() const { return !unlisted(); }
 
 private:
  friend class BaseFutureList;  // for IntrusiveForwardList::Item functions
 
  Waker waker_;
  FutureState state_;
};
 
class BaseFutureList {
 public:
  constexpr BaseFutureList() = default;
 
  bool empty() const { return list_.empty(); }
 
  void Push(FutureCore& future) { containers::PushBackSlow(list_, future); }
 
  void PushRequireEmpty(FutureCore& future);
 
  bool PushIfEmpty(FutureCore& future);
 
  FutureCore* PopIfAvailable() { return list_.empty() ? nullptr : &Pop(); }
 
  FutureCore& Pop() {
    FutureCore& future = list_.front();
    list_.pop_front();
    return future;
  }
 
  void ResolveOne() {
    list_.front().WakeAndMarkReady();
    list_.pop_front();
  }
 
  void ResolveOneIfAvailable() {
    if (!list_.empty()) {
      ResolveOne();
    }
  }
 
  void ResolveAll();
 
 protected:
  IntrusiveForwardList<FutureCore>& list() { return list_; }
 
 private:
  IntrusiveForwardList<FutureCore> list_;
};
 
template <auto kGetFutureImpl, auto kGetFutureCore>
class CustomFutureList : public BaseFutureList {
 public:
  using value_type = std::remove_reference_t<decltype(*kGetFutureImpl(
      std::declval<FutureCore*>()))>;
  using pointer = value_type*;
  using reference = value_type&;
 
  constexpr CustomFutureList() = default;
 
  void Push(FutureCore& future) { BaseFutureList::Push(future); }
  void Push(reference future) { Push(kGetFutureCore(future)); }
 
  void PushRequireEmpty(FutureCore& future) {
    BaseFutureList::PushRequireEmpty(future);
  }
  void PushRequireEmpty(reference future) {
    PushRequireEmpty(kGetFutureCore(future));
  }
 
  bool PushIfEmpty(FutureCore& future) {
    return BaseFutureList::PushIfEmpty(future);
  }
  bool PushIfEmpty(reference future) {
    return PushIfEmpty(kGetFutureCore(future));
  }
 
  pointer PopIfAvailable() {
    return kGetFutureImpl(BaseFutureList::PopIfAvailable());
  }
 
  reference Pop() { return *kGetFutureImpl(BaseFutureList::PopIfAvailable()); }
 
  template <typename Predicate>
  pointer Remove(Predicate predicate) {
    auto previous = list().before_begin();
    auto current = list().begin();
    while (current != list().end()) {
      pointer item = kGetFutureImpl(&(*current));
      if (predicate(*item)) {
        list().erase_after(previous);
        return item;
      }
      previous = current;
      ++current;
    }
    return nullptr;
  }
 
  template <typename Resolver>
  void ResolveAllWith(Resolver&& resolver) {
    while (!list().empty()) {
      resolver(Pop());
    }
  }
 
  template <typename Resolver>
  void ResolveOneWith(Resolver&& resolver) {
    if (!list().empty()) {
      resolver(Pop());
    }
  }
};
 
template <auto kMemberPtr>
using FutureList =
    CustomFutureList<ContainerOf<kMemberPtr, FutureCore>, MemberOf<kMemberPtr>>;
 
 
}  // namespace pw::async2