flow_control.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2024, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "kcenon/network/detail/utils/result_types.h"
 
#include <cstdint>
#include <optional>
 
namespace kcenon::network::protocols::quic
{
 
namespace flow_control_error
{
    constexpr int send_blocked = -710;
    constexpr int receive_overflow = -711;
    constexpr int window_exceeded = -712;
} // namespace flow_control_error
 
class flow_controller
{
public:
    explicit flow_controller(uint64_t initial_window = 1048576);
 
    ~flow_controller() = default;
 
    // Copyable
    flow_controller(const flow_controller&) = default;
    auto operator=(const flow_controller&) -> flow_controller& = default;
 
    // Movable
    flow_controller(flow_controller&&) noexcept = default;
    auto operator=(flow_controller&&) noexcept -> flow_controller& = default;
 
    // ========================================================================
    // Send Side (Connection-level limits on our sending)
    // ========================================================================
 
    [[nodiscard]] auto available_send_window() const noexcept -> uint64_t;
 
    [[nodiscard]] auto consume_send_window(uint64_t bytes) -> VoidResult;
 
    void update_send_limit(uint64_t max_data);
 
    [[nodiscard]] auto is_send_blocked() const noexcept -> bool;
 
    [[nodiscard]] auto send_limit() const noexcept -> uint64_t { return send_limit_; }
 
    [[nodiscard]] auto bytes_sent() const noexcept -> uint64_t { return bytes_sent_; }
 
    // ========================================================================
    // Receive Side (Connection-level limits on peer's sending)
    // ========================================================================
 
    [[nodiscard]] auto record_received(uint64_t bytes) -> VoidResult;
 
    void record_consumed(uint64_t bytes);
 
    [[nodiscard]] auto receive_limit() const noexcept -> uint64_t { return receive_limit_; }
 
    [[nodiscard]] auto bytes_received() const noexcept -> uint64_t { return bytes_received_; }
 
    [[nodiscard]] auto bytes_consumed() const noexcept -> uint64_t { return bytes_consumed_; }
 
    // ========================================================================
    // Flow Control Frame Generation
    // ========================================================================
 
    [[nodiscard]] auto should_send_max_data() const noexcept -> bool;
 
    [[nodiscard]] auto generate_max_data() -> std::optional<uint64_t>;
 
    [[nodiscard]] auto should_send_data_blocked() const noexcept -> bool;
 
    void mark_data_blocked_sent();
 
    // ========================================================================
    // Configuration
    // ========================================================================
 
    void set_window_size(uint64_t window);
 
    [[nodiscard]] auto window_size() const noexcept -> uint64_t { return window_size_; }
 
    void set_update_threshold(double threshold);
 
    // ========================================================================
    // Reset
    // ========================================================================
 
    void reset(uint64_t initial_window);
 
private:
    // Send side (peer's limits on us)
    uint64_t send_limit_{0};       // Peer's MAX_DATA (our send limit)
    uint64_t bytes_sent_{0};       // Total bytes we've sent
    bool data_blocked_sent_{false}; // DATA_BLOCKED already sent
 
    // Receive side (our limits on peer)
    uint64_t receive_limit_{0};    // Our MAX_DATA (peer's send limit)
    uint64_t bytes_received_{0};   // Total bytes received
    uint64_t bytes_consumed_{0};   // Bytes consumed by application
 
    // Window management
    uint64_t window_size_;
    double update_threshold_{0.5}; // Send MAX_DATA when 50% consumed
 
    // Track if we need to send MAX_DATA
    uint64_t last_sent_max_data_{0};
};
 
struct flow_control_stats
{
    // Send side
    uint64_t send_limit{0};
    uint64_t bytes_sent{0};
    uint64_t send_window_available{0};
    bool send_blocked{false};
 
    // Receive side
    uint64_t receive_limit{0};
    uint64_t bytes_received{0};
    uint64_t bytes_consumed{0};
    uint64_t receive_window_available{0};
};
 
[[nodiscard]] auto get_flow_control_stats(const flow_controller& fc) -> flow_control_stats;
 
} // namespace kcenon::network::protocols::quic