channel.h

// Copyright 2024 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
 
//         __      ___   ___ _  _ ___ _  _  ___
//         \ \    / /_\ | _ \ \| |_ _| \| |/ __|
//          \ \/\/ / _ \|   / .` || || .` | (_ |
//           \_/\_/_/ \_\_|_\_|\_|___|_|\_|\___|
//  _____  _____ ___ ___ ___ __  __ ___ _  _ _____ _   _
// | __\ \/ / _ \ __| _ \_ _|  \/  | __| \| |_   _/_\ | |
// | _| >  <|  _/ _||   /| || |\/| | _|| .` | | |/ _ \| |__
// |___/_/\_\_| |___|_|_\___|_|  |_|___|_|\_| |_/_/ \_\____|
//
// This module is in an early, experimental state. The APIs are in flux and may
// change without notice. Please do not rely on it in production code, but feel
// free to explore and share feedback with the Pigweed team!
 
#include <cstddef>
#include <cstdint>
#include <limits>
#include <utility>
 
#include "pw_async2/dispatcher.h"
#include "pw_async2/poll.h"
#include "pw_bytes/span.h"
#include "pw_channel/properties.h"
#include "pw_multibuf/multibuf.h"
#include "pw_result/result.h"
#include "pw_status/status.h"
 
namespace pw::channel {
 
 
template <DataType kDataType, Property... kProperties>
class Channel {
 public:
  [[nodiscard]] static constexpr DataType data_type() { return kDataType; }
 
  [[nodiscard]] static constexpr bool reliable() {
    return ((kProperties == Property::kReliable) || ...);
  }
  [[nodiscard]] static constexpr bool seekable() {
    return ((kProperties == Property::kSeekable) || ...);
  }
  [[nodiscard]] static constexpr bool readable() {
    return ((kProperties == Property::kReadable) || ...);
  }
  [[nodiscard]] static constexpr bool writable() {
    return ((kProperties == Property::kWritable) || ...);
  }
 
  [[nodiscard]] constexpr bool is_read_open() const;
 
  [[nodiscard]] constexpr bool is_write_open() const;
 
  [[nodiscard]] constexpr bool is_read_or_write_open() const {
    return is_read_open() || is_write_open();
  }
 
  async2::Poll<Result<multibuf::MultiBuf>> PendRead(async2::Context& cx);
  async2::Poll<Status> PendReadyToWrite(pw::async2::Context& cx);
  async2::Poll<std::optional<multibuf::MultiBuf>> PendAllocateWriteBuffer(
      async2::Context& cx, size_t min_bytes);
  Status StageWrite(multibuf::MultiBuf&& data);
  async2::Poll<Status> PendWrite(async2::Context& cx);
  async2::Poll<pw::Status> PendClose(async2::Context& cx);
 
  // Conversions
 
  template <typename Sibling,
            typename = internal::EnableIfConversionIsValid<Channel, Sibling>>
  constexpr operator Sibling&() {
    return as<Sibling>();
  }
  template <typename Sibling,
            typename = internal::EnableIfConversionIsValid<Channel, Sibling>>
  constexpr operator const Sibling&() const {
    return as<Sibling>();
  }
 
  template <typename Sibling>
  [[nodiscard]] Sibling& as() {
    internal::CheckThatConversionIsValid<Channel, Sibling>();
    return static_cast<Sibling&>(static_cast<AnyChannel&>(*this));
  }
  template <typename Sibling>
  [[nodiscard]] const Sibling& as() const {
    internal::CheckThatConversionIsValid<Channel, Sibling>();
    return static_cast<const Sibling&>(static_cast<const AnyChannel&>(*this));
  }
 
  template <Property... kOtherChannelProperties>
  [[nodiscard]] auto& as() {
    return as<Channel<data_type(), kOtherChannelProperties...>>();
  }
  template <Property... kOtherChannelProperties>
  [[nodiscard]] const auto& as() const {
    return as<Channel<data_type(), kOtherChannelProperties...>>();
  }
 
  [[nodiscard]] Channel<DataType::kByte, kProperties...>&
  IgnoreDatagramBoundaries() {
    static_assert(kDataType == DataType::kDatagram,
                  "IgnoreDatagramBoundaries() may only be called to use a "
                  "datagram channel to a byte channel");
    return static_cast<Channel<DataType::kByte, kProperties...>&>(
        static_cast<AnyChannel&>(*this));
  }
 
  [[nodiscard]] const Channel<DataType::kByte, kProperties...>&
  IgnoreDatagramBoundaries() const {
    static_assert(kDataType == DataType::kDatagram,
                  "IgnoreDatagramBoundaries() may only be called to use a "
                  "datagram channel to a byte channel");
    return static_cast<const Channel<DataType::kByte, kProperties...>&>(
        static_cast<const AnyChannel&>(*this));
  }
 
 private:
  static_assert(internal::PropertiesAreValid<kProperties...>());
 
  friend class AnyChannel;
 
  explicit constexpr Channel() = default;
};
 
class AnyChannel
    : private Channel<DataType::kByte, kReadable>,
      private Channel<DataType::kByte, kWritable>,
      private Channel<DataType::kByte, kReadable, kWritable>,
      private Channel<DataType::kByte, kReliable, kReadable>,
      private Channel<DataType::kByte, kReliable, kWritable>,
      private Channel<DataType::kByte, kReliable, kReadable, kWritable>,
      private Channel<DataType::kDatagram, kReadable>,
      private Channel<DataType::kDatagram, kWritable>,
      private Channel<DataType::kDatagram, kReadable, kWritable>,
      private Channel<DataType::kDatagram, kReliable, kReadable>,
      private Channel<DataType::kDatagram, kReliable, kWritable>,
      private Channel<DataType::kDatagram, kReliable, kReadable, kWritable> {
 public:
  virtual ~AnyChannel() = default;
 
  // Returned by Position() if getting the position is not supported.
  // TODO: b/323622630 - `Seek` and `Position` are not yet implemented.
  // static constexpr size_t kUnknownPosition =
  //     std::numeric_limits<size_t>::max();
 
  // Channel properties
 
  [[nodiscard]] constexpr DataType data_type() const { return data_type_; }
 
  [[nodiscard]] constexpr bool reliable() const {
    return (properties_ & Property::kReliable) != 0;
  }
 
  [[nodiscard]] constexpr bool seekable() const {
    return (properties_ & Property::kSeekable) != 0;
  }
 
  [[nodiscard]] constexpr bool readable() const {
    return (properties_ & Property::kReadable) != 0;
  }
 
  [[nodiscard]] constexpr bool writable() const {
    return (properties_ & Property::kWritable) != 0;
  }
 
  [[nodiscard]] constexpr bool is_read_open() const { return read_open_; }
 
  [[nodiscard]] constexpr bool is_write_open() const { return write_open_; }
 
  [[nodiscard]] constexpr bool is_read_or_write_open() const {
    return read_open_ || write_open_;
  }
 
  // Read API
 
  async2::Poll<Result<multibuf::MultiBuf>> PendRead(async2::Context& cx) {
    if (!is_read_open()) {
      return Status::FailedPrecondition();
    }
    async2::Poll<Result<multibuf::MultiBuf>> result = DoPendRead(cx);
    if (result.IsReady() && result->status().IsFailedPrecondition()) {
      set_read_closed();
    }
    return result;
  }
 
  // Write API
 
  async2::Poll<Status> PendReadyToWrite(pw::async2::Context& cx) {
    if (!is_write_open()) {
      return Status::FailedPrecondition();
    }
    async2::Poll<Status> result = DoPendReadyToWrite(cx);
    if (result.IsReady() && result->IsFailedPrecondition()) {
      set_write_closed();
    }
    return result;
  }
 
  async2::Poll<std::optional<multibuf::MultiBuf>> PendAllocateWriteBuffer(
      async2::Context& cx, size_t min_bytes) {
    return DoPendAllocateWriteBuffer(cx, min_bytes);
  }
 
  Status StageWrite(multibuf::MultiBuf&& data) {
    if (!is_write_open()) {
      return Status::FailedPrecondition();
    }
    Status status = DoStageWrite(std::move(data));
    if (status.IsFailedPrecondition()) {
      set_write_closed();
    }
    return status;
  }
 
  async2::Poll<Status> PendWrite(async2::Context& cx) {
    if (!is_write_open()) {
      return Status::FailedPrecondition();
    }
    async2::Poll<Status> status = DoPendWrite(cx);
    if (status.IsReady() && status->IsFailedPrecondition()) {
      set_write_closed();
    }
    return status;
  }
 
  Status Seek(async2::Context& cx, ptrdiff_t position, Whence whence);
 
  size_t Position() const;
 
  async2::Poll<pw::Status> PendClose(async2::Context& cx) {
    if (!is_read_or_write_open()) {
      return Status::FailedPrecondition();
    }
    auto result = DoPendClose(cx);
    if (result.IsReady()) {
      set_read_closed();
      set_write_closed();
    }
    return result;
  }
 
 protected:
  // Marks the channel as closed for reading, but does nothing else.
  //
  // PendClose() always marks the channel closed when DoPendClose() returns
  // Ready(), regardless of the status.
  void set_read_closed() { read_open_ = false; }
 
  // Marks the channel as closed for writing, but does nothing else.
  //
  // PendClose() always marks the channel closed when DoPendClose() returns
  // Ready(), regardless of the status.
  void set_write_closed() { write_open_ = false; }
 
 private:
  template <DataType, Property...>
  friend class Channel;  // Allow static_casts to AnyChannel
 
  template <DataType, Property...>
  friend class internal::BaseChannelImpl;  // Allow inheritance
 
  // `AnyChannel` may only be constructed by deriving from `ChannelImpl`.
  explicit constexpr AnyChannel(DataType type, uint8_t properties)
      : data_type_(type),
        properties_(properties),
        read_open_(readable()),
        write_open_(writable()) {}
 
  // Virtual interface
 
  // Read functions
 
  virtual async2::Poll<Result<multibuf::MultiBuf>> DoPendRead(
      async2::Context& cx) = 0;
 
  // Write functions
 
  virtual async2::Poll<std::optional<multibuf::MultiBuf>>
  DoPendAllocateWriteBuffer(async2::Context& cx, size_t min_bytes) = 0;
 
  virtual pw::async2::Poll<Status> DoPendReadyToWrite(async2::Context& cx) = 0;
 
  virtual Status DoStageWrite(multibuf::MultiBuf&& buffer) = 0;
 
  virtual pw::async2::Poll<Status> DoPendWrite(async2::Context& cx) = 0;
 
  // Seek functions
 
  // virtual Status DoSeek(ptrdiff_t position, Whence whence) = 0;
 
  // virtual size_t DoPosition() const = 0;
 
  // Common functions
  virtual async2::Poll<Status> DoPendClose(async2::Context& cx) = 0;
 
  DataType data_type_;
  uint8_t properties_;
  bool read_open_;
  bool write_open_;
};
 
template <Property... kProperties>
using ByteChannel = Channel<DataType::kByte, kProperties...>;
 
template <Property... kProperties>
using DatagramChannel = Channel<DataType::kDatagram, kProperties...>;
 
using ByteReader = ByteChannel<kReadable>;
using ByteWriter = ByteChannel<kWritable>;
using ByteReaderWriter = ByteChannel<kReadable, kWritable>;
 
using ReliableByteReader = ByteChannel<kReliable, kReadable>;
using ReliableByteWriter = ByteChannel<kReliable, kWritable>;
using ReliableByteReaderWriter = ByteChannel<kReliable, kReadable, kWritable>;
 
using DatagramReader = DatagramChannel<kReadable>;
using DatagramWriter = DatagramChannel<kWritable>;
using DatagramReaderWriter = DatagramChannel<kReadable, kWritable>;
 
using ReliableDatagramReader = DatagramChannel<kReliable, kReadable>;
using ReliableDatagramWriter = DatagramChannel<kReliable, kWritable>;
using ReliableDatagramReaderWriter =
    DatagramChannel<kReliable, kReadable, kWritable>;
 
// Implementation extension classes.
 
template <DataType kDataType, Property... kProperties>
class ChannelImpl {
  static_assert(internal::PropertiesAreValid<kProperties...>());
};
 
template <Property... kProperties>
using ByteChannelImpl = ChannelImpl<DataType::kByte, kProperties...>;
 
template <Property... kProperties>
using DatagramChannelImpl = ChannelImpl<DataType::kDatagram, kProperties...>;
 
template <typename ChannelType>
class Implement;
 
 
template <DataType kDataType, Property... kProperties>
class Implement<Channel<kDataType, kProperties...>>
    : public ChannelImpl<kDataType, kProperties...> {
 protected:
  explicit constexpr Implement() = default;
};
 
}  // namespace pw::channel
 
// Include specializations for supported Channel types.
#include "pw_channel/internal/channel_specializations.h"