poll.h

// Copyright 2023 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 <optional>
 
#include "pw_async2/internal/poll_internal.h"
#include "pw_polyfill/language_feature_macros.h"
#include "pw_string/to_string.h"
 
namespace pw {
namespace async2 {
 
struct ReadyType {};
 
struct PW_NODISCARD_STR(
    "`Poll`-returning functions may or may not have completed. Their "
    "return value should be examined.") PendingType {};
 
template <typename T = ReadyType>
class PW_NODISCARD_STR(
    "`Poll`-returning functions may or may not have completed. Their "
    "return value should be examined.") Poll {
 public:
  using OutputType = T;
 
  Poll() = delete;
  constexpr Poll(const Poll&) = default;
  constexpr Poll& operator=(const Poll&) = default;
  constexpr Poll(Poll&&) = default;
  constexpr Poll& operator=(Poll&&) = default;
 
  template <typename U,
            internal_poll::EnableIfImplicitlyConvertible<T, const U&> = 0>
  constexpr Poll(const Poll<U>& other) : value_(other.value_) {}
  template <typename U,
            internal_poll::EnableIfExplicitlyConvertible<T, const U&> = 0>
  explicit constexpr Poll(const Poll<U>& other) : value_(other.value_) {}
 
  template <typename U,
            internal_poll::EnableIfImplicitlyConvertible<T, U&&> = 0>
  constexpr Poll(Poll<U>&& other)  // NOLINT
      : value_(std::move(other.value_)) {}
  template <typename U,
            internal_poll::EnableIfExplicitlyConvertible<T, U&&> = 0>
  explicit constexpr Poll(Poll<U>&& other) : value_(std::move(other.value_)) {}
 
  // Constructs the inner value `T` in-place using the provided args, using the
  // `T(U)` (direct-initialization) constructor. This constructor is only valid
  // if `T` can be constructed from a `U`. Can accept move or copy constructors.
  //
  // This constructor is explicit if `U` is not convertible to `T`. To avoid
  // ambiguity, this constructor is disabled if `U` is a `Poll<J>`, where
  // `J` is convertible to `T`.
  template <typename U = T,
            internal_poll::EnableIfImplicitlyInitializable<T, U> = 0>
  constexpr Poll(U&& u)  // NOLINT
      : Poll(std::in_place, std::forward<U>(u)) {}
 
  template <typename U = T,
            internal_poll::EnableIfExplicitlyInitializable<T, U> = 0>
  explicit constexpr Poll(U&& u)  // NOLINT
      : Poll(std::in_place, std::forward<U>(u)) {}
 
  // In-place construction of ``Ready`` variant.
  template <typename... Args>
  constexpr Poll(std::in_place_t, Args&&... args)
      : value_(std::in_place, std::move(args)...) {}
 
  // Convert from `T`
  constexpr Poll(T&& value) : value_(std::move(value)) {}
  constexpr Poll& operator=(T&& value) {
    value_ = std::optional<T>(std::move(value));
    return *this;
  }
 
  // Convert from `Pending`
  constexpr Poll(PendingType) noexcept : value_() {}
  constexpr Poll& operator=(PendingType) noexcept {
    value_ = std::nullopt;
    return *this;
  }
 
  constexpr bool IsReady() const noexcept { return value_.has_value(); }
 
  constexpr bool IsPending() const noexcept { return !value_.has_value(); }
 
  constexpr Poll<> Readiness() const noexcept {
    if (IsReady()) {
      return ReadyType();
    } else {
      return PendingType();
    }
  }
 
  constexpr T& value() & noexcept { return *value_; }
  constexpr const T& value() const& noexcept { return *value_; }
  constexpr T&& value() && noexcept { return std::move(*value_); }
  constexpr const T&& value() const&& noexcept { return std::move(*value_); }
 
  constexpr const T* operator->() const noexcept { return &*value_; }
  constexpr T* operator->() noexcept { return &*value_; }
 
  constexpr const T& operator*() const& noexcept { return *value_; }
  constexpr T& operator*() & noexcept { return *value_; }
  constexpr const T&& operator*() const&& noexcept {
    return std::move(*value_);
  }
  constexpr T&& operator*() && noexcept { return std::move(*value_); }
 
  constexpr void IgnorePoll() const {}
 
 private:
  template <typename U>
  friend class Poll;
  std::optional<T> value_;
};
 
// Deduction guide to allow ``Poll(v)`` rather than ``Poll<T>(v)``.
template <typename T>
Poll(T value) -> Poll<T>;
 
template <typename T>
constexpr bool operator==(const Poll<T>& lhs, const Poll<T>& rhs) {
  if (lhs.IsReady() && rhs.IsReady()) {
    return *lhs == *rhs;
  }
  return lhs.IsReady() == rhs.IsReady();
}
 
template <typename T>
constexpr bool operator!=(const Poll<T>& lhs, const Poll<T>& rhs) {
  return !(lhs == rhs);
}
 
template <typename T>
constexpr bool operator==(const Poll<T>& lhs, PendingType) {
  return lhs.IsPending();
}
 
template <typename T>
constexpr bool operator!=(const Poll<T>& lhs, PendingType) {
  return !lhs.IsPending();
}
 
template <typename T>
constexpr bool operator==(PendingType, const Poll<T>& rhs) {
  return rhs.IsPending();
}
 
template <typename T>
constexpr bool operator!=(PendingType, const Poll<T>& rhs) {
  return !rhs.IsPending();
}
 
// ``ReadyType`` is the value type for `Poll<T>` and has no value,
// so it should always compare equal.
constexpr bool operator==(ReadyType, ReadyType) { return true; }
constexpr bool operator!=(ReadyType, ReadyType) { return false; }
 
// The ``Pending`` case holds no value, so is always equal.
constexpr bool operator==(PendingType, PendingType) { return true; }
constexpr bool operator!=(PendingType, PendingType) { return false; }
 
inline constexpr Poll<> Ready() { return Poll(ReadyType{}); }
 
template <typename T, typename... Args>
constexpr Poll<T> Ready(std::in_place_t, Args&&... args) {
  return Poll<T>(std::in_place, std::forward<Args>(args)...);
}
 
template <typename T>
constexpr Poll<std::remove_reference_t<T>> Ready(T&& value) {
  return Poll<std::remove_reference_t<T>>(std::forward<T>(value));
}
 
inline constexpr PendingType Pending() { return PendingType(); }
 
}  // namespace async2
 
// --- ToString implementations for ``Poll`` types ---
 
template <>
inline StatusWithSize ToString(const async2::ReadyType&, span<char> buffer) {
  return ToString("Ready", buffer);
}
 
template <>
inline StatusWithSize ToString(const async2::PendingType&, span<char> buffer) {
  return ToString("Pending", buffer);
}
 
// Implement ``ToString`` for ``Poll<T>``.
template <typename T>
inline StatusWithSize ToString(const async2::Poll<T>& poll, span<char> buffer) {
  if (poll.IsReady()) {
    StatusWithSize s;
    s.UpdateAndAdd(ToString("Ready(", buffer));
    s.UpdateAndAdd(ToString(*poll, buffer.subspan(s.size())));
    s.UpdateAndAdd(ToString(")", buffer.subspan(s.size())));
    s.ZeroIfNotOk();
    return s;
  }
  return ToString(async2::PendingType{}, buffer);
}
 
template <>
inline StatusWithSize ToString(const async2::Poll<>& poll, span<char> buffer) {
  if (poll.IsReady()) {
    return ToString(async2::ReadyType{}, buffer);
  }
  return ToString(async2::PendingType{}, buffer);
}
 
}  // namespace pw