#include "cwist/net/http/http2_flow_control.h"
#include <limits.h>
#include <string.h>
#include "h2_wire.h"

Include dependency graph for http2_flow_control.c:

Functions
void	cwist_http2_flow_control_init (cwist_http2_flow_control *flow_control, uint32_t initial_connection_window, uint32_t max_connection_window)
	Initialize connection-level flow-control state.

void	cwist_http2_stream_flow_control_init (cwist_http2_stream_flow_control *flow_control, uint32_t stream_id, uint32_t initial_stream_window, uint32_t max_stream_window)
	Initialize per-stream flow-control state.

void	cwist_http2_flow_control_update_rtt (cwist_http2_flow_control *flow_control, uint64_t rtt_sample_us)
	Feed a new RTT sample into the smoothed estimator and retune.

bool	cwist_http2_flow_control_receive (cwist_http2_flow_control *flow_control, uint32_t bytes)
	Account received DATA bytes against the connection receive window.

bool	cwist_http2_stream_flow_control_receive (cwist_http2_stream_flow_control *flow_control, uint32_t bytes)
	Account received DATA bytes against a stream receive window.

void	cwist_http2_flow_control_consume (cwist_http2_flow_control *flow_control, uint32_t bytes)
	Record application-consumed bytes for the connection.

void	cwist_http2_stream_flow_control_consume (cwist_http2_stream_flow_control *flow_control, uint32_t bytes)
	Record application-consumed bytes for a stream.

int	cwist_http2_flow_control_maybe_window_update (cwist_http2_flow_control flow_control, uint8_t buffer, size_t buffer_len, size_t *written, uint64_t now_us, bool force)
	Emit a connection-level WINDOW_UPDATE when enough credit is due.

int	cwist_http2_stream_flow_control_maybe_window_update (cwist_http2_flow_control connection_flow_control, cwist_http2_stream_flow_control stream_flow_control, uint8_t buffer, size_t buffer_len, size_t written, uint64_t now_us, bool force)
	Emit a stream-level WINDOW_UPDATE when enough credit is due.

void	cwist_http2_flow_control_add_send_window (cwist_http2_flow_control *flow_control, uint32_t increment)
	Credit the connection send window from a WINDOW_UPDATE frame.

void	cwist_http2_stream_flow_control_add_send_window (cwist_http2_stream_flow_control *flow_control, uint32_t increment)
	Credit a stream send window from a WINDOW_UPDATE frame.

size_t	cwist_http2_flow_control_pacing_allowance (cwist_http2_flow_control connection_flow_control, const cwist_http2_stream_flow_control stream_flow_control, size_t requested, uint64_t now_us)
	Compute how much of a send request may proceed right now.

bool	cwist_http2_flow_control_reserve_send (cwist_http2_flow_control connection_flow_control, cwist_http2_stream_flow_control stream_flow_control, uint32_t bytes, uint64_t now_us)
	Reserve send credit for an outgoing write.

Function Documentation

◆ cwist_http2_flow_control_add_send_window()

void cwist_http2_flow_control_add_send_window	(	cwist_http2_flow_control *	flow_control,
		uint32_t	increment
	)

Credit the connection send window from a WINDOW_UPDATE frame.

Saturating add: credit is capped at CWIST_HTTP2_MAX_WINDOW.

Parameters

flow_control	Connection flow-control state.
increment	Send-window increment from the peer.

Definition at line 498 of file http2_flow_control.c.

References cap, and CWIST_HTTP2_MAX_WINDOW.

◆ cwist_http2_flow_control_consume()

void cwist_http2_flow_control_consume	(	cwist_http2_flow_control *	flow_control,
		uint32_t	bytes
	)

Record application-consumed bytes for the connection.

Adds bytes to the pending WINDOW_UPDATE accumulator, saturating at UINT32_MAX instead of wrapping.

Parameters

flow_control	Connection flow-control state.
bytes	Number of bytes the application consumed from the receive buffer.

Definition at line 280 of file http2_flow_control.c.

References cap.

Referenced by cwist_http2_serve_connection_ex().

◆ cwist_http2_flow_control_init()

void cwist_http2_flow_control_init	(	cwist_http2_flow_control *	flow_control,
		uint32_t	initial_connection_window,
		uint32_t	max_connection_window
	)

Initialize connection-level flow-control state.

Windows below the protocol defaults are raised to the defaults, and the maximum window is clamped to CWIST_HTTP2_MAX_WINDOW. Zeroes the whole state, then seeds receive/target/min/send windows with the initial connection window, and grants half a window of initial pacing tokens at 10x the initial window in bytes per second as a provisional pacing rate until RTT samples recalibrate it.

Parameters

flow_control	Connection flow-control state to initialize.
initial_connection_window	Requested initial connection window; values below CWIST_HTTP2_INITIAL_CONNECTION_WINDOW select the default.
max_connection_window	Upper bound for the dynamic window; raised to at least the initial window and capped at CWIST_HTTP2_MAX_WINDOW.

Definition at line 137 of file http2_flow_control.c.

References cap, CWIST_HTTP2_INITIAL_CONNECTION_WINDOW, CWIST_HTTP2_MAX_WINDOW, and CWIST_HTTP2_NETWORK_QUALITY_NORMAL.

◆ cwist_http2_flow_control_maybe_window_update()

int cwist_http2_flow_control_maybe_window_update	(	cwist_http2_flow_control *	flow_control,
		uint8_t *	buffer,
		size_t	buffer_len,
		size_t *	written,
		uint64_t	now_us,
		bool	force
	)

Emit a connection-level WINDOW_UPDATE when enough credit is due.

Does nothing until at least half the target window has been consumed (unless force), then retunes the target against the measured bandwidth-delay product and serializes a WINDOW_UPDATE for stream 0 into the caller's buffer. On success the receive window is credited with the increment (saturating at CWIST_HTTP2_MAX_WINDOW), the pending accumulator is cleared, and the update timestamp is advanced.

Parameters

flow_control	Connection flow-control state.
buffer	Destination buffer for the serialized frame.
buffer_len	Available bytes in `buffer` (at least 13 required).
written	Set to 0 when no frame is emitted, to 13 on success.
now_us	Current time in microseconds; drives retuning.
force	Emit the update even when less than half the target window is pending.

Returns: 1 when a WINDOW_UPDATE frame was written, 0 when no update is due or flow_control is NULL, -1 when the frame could not be serialized.

Definition at line 385 of file http2_flow_control.c.

References cap, and CWIST_HTTP2_MAX_WINDOW.

◆ cwist_http2_flow_control_pacing_allowance()

size_t cwist_http2_flow_control_pacing_allowance	(	cwist_http2_flow_control *	connection_flow_control,
		const cwist_http2_stream_flow_control *	stream_flow_control,
		size_t	requested,
		uint64_t	now_us
	)

Compute how much of a send request may proceed right now.

Refills the pacing token bucket from the elapsed time since the last call, capping the refill at one target window's worth of tokens (and capping the elapsed computation so it stays inside uint64 regardless of idle time). The result is the smallest of the requested size, the connection send window, the stream send window, and the available pacing tokens.

Parameters

connection_flow_control	Connection flow-control state holding the pacing bucket.
stream_flow_control	Stream flow-control state holding the stream send window.
requested	Number of bytes the caller wants to send.
now_us	Current time in microseconds.

Returns: Allowed byte count; 0 when either flow-control pointer is NULL or no credit of any kind is available.

Definition at line 541 of file http2_flow_control.c.

References cap.

Referenced by cwist_http2_flow_control_reserve_send().

◆ cwist_http2_flow_control_receive()

bool cwist_http2_flow_control_receive	(	cwist_http2_flow_control *	flow_control,
		uint32_t	bytes
	)

Account received DATA bytes against the connection receive window.

Parameters

flow_control	Connection flow-control state.
bytes	Number of bytes received from the peer.

Return values

true	`bytes` fit in the remaining receive window and were debited.
false	`flow_control` is NULL or `bytes` exceed the remaining window; nothing is debited.

Definition at line 246 of file http2_flow_control.c.

References cap.

Referenced by cwist_http2_serve_connection_ex().

◆ cwist_http2_flow_control_reserve_send()

bool cwist_http2_flow_control_reserve_send	(	cwist_http2_flow_control *	connection_flow_control,
		cwist_http2_stream_flow_control *	stream_flow_control,
		uint32_t	bytes,
		uint64_t	now_us
	)

Reserve send credit for an outgoing write.

Checks cwist_http2_flow_control_pacing_allowance() first; on success the requested bytes are debited from the connection send window, the stream send window, and the pacing token bucket, so the caller must actually transmit the bytes it reserved.

Parameters

connection_flow_control	Connection flow-control state.
stream_flow_control	Stream flow-control state.
bytes	Number of bytes to reserve.
now_us	Current time in microseconds, forwarded to the allowance computation.

Return values

true	The reservation succeeded and all three credit pools were debited by `bytes`.
false	Insufficient connection/stream window or pacing tokens; nothing is debited.

Definition at line 606 of file http2_flow_control.c.

References cap, and cwist_http2_flow_control_pacing_allowance().

◆ cwist_http2_flow_control_update_rtt()

void cwist_http2_flow_control_update_rtt	(	cwist_http2_flow_control *	flow_control,
		uint64_t	rtt_sample_us
	)

Feed a new RTT sample into the smoothed estimator and retune.

Ignores NULL state and zero samples. The first sample seeds srtt and sets rttvar to half of it; later samples feed exponential updates (rttvar: 3/4 old + 1/4 deviation, srtt: 7/8 old + 1/8 sample) and then trigger cwist_http2_flow_control_adjust() to recompute network quality, the target window, and the pacing rate.

Parameters

flow_control	Connection flow-control state holding the estimator.
rtt_sample_us	Measured round-trip time in microseconds; must be non-zero to be accepted.

Definition at line 219 of file http2_flow_control.c.

References cap.

Referenced by cwist_http2_serve_connection_ex().

◆ cwist_http2_stream_flow_control_add_send_window()

void cwist_http2_stream_flow_control_add_send_window	(	cwist_http2_stream_flow_control *	flow_control,
		uint32_t	increment
	)

Credit a stream send window from a WINDOW_UPDATE frame.

Saturating add: credit is capped at CWIST_HTTP2_MAX_WINDOW.

Parameters

flow_control	Stream flow-control state.
increment	Send-window increment from the peer.

Definition at line 515 of file http2_flow_control.c.

References cap, and CWIST_HTTP2_MAX_WINDOW.

◆ cwist_http2_stream_flow_control_consume()

void cwist_http2_stream_flow_control_consume	(	cwist_http2_stream_flow_control *	flow_control,
		uint32_t	bytes
	)

Record application-consumed bytes for a stream.

Adds bytes to the stream's pending WINDOW_UPDATE accumulator, saturating at UINT32_MAX instead of wrapping.

Parameters

flow_control	Stream flow-control state.
bytes	Number of bytes the application consumed from the stream's receive buffer.

Definition at line 297 of file http2_flow_control.c.

References cap.

Referenced by cwist_http2_serve_connection_ex().

◆ cwist_http2_stream_flow_control_init()

void cwist_http2_stream_flow_control_init	(	cwist_http2_stream_flow_control *	flow_control,
		uint32_t	stream_id,
		uint32_t	initial_stream_window,
		uint32_t	max_stream_window
	)

Initialize per-stream flow-control state.

Windows below the protocol defaults are raised to the defaults, and the maximum window is clamped to CWIST_HTTP2_MAX_WINDOW. Zeroes the whole state, then records the stream identifier and seeds receive/target/min/send windows with the initial stream window.

Parameters

flow_control	Stream flow-control state to initialize.
stream_id	HTTP/2 stream identifier to associate with the state.
initial_stream_window	Requested initial stream window; values below CWIST_HTTP2_INITIAL_STREAM_WINDOW select the default.
max_stream_window	Upper bound for the dynamic window; raised to at least the initial window and capped at CWIST_HTTP2_MAX_WINDOW.

Definition at line 181 of file http2_flow_control.c.

References cap, CWIST_HTTP2_INITIAL_STREAM_WINDOW, and CWIST_HTTP2_MAX_WINDOW.

◆ cwist_http2_stream_flow_control_maybe_window_update()

int cwist_http2_stream_flow_control_maybe_window_update	(	cwist_http2_flow_control *	connection_flow_control,
		cwist_http2_stream_flow_control *	stream_flow_control,
		uint8_t *	buffer,
		size_t	buffer_len,
		size_t *	written,
		uint64_t	now_us,
		bool	force
	)

Emit a stream-level WINDOW_UPDATE when enough credit is due.

Server-side only client-initiated (odd, non-zero) streams may receive a stream-level WINDOW_UPDATE; other stream IDs return 0 without emitting anything. Requires at least half the target window in pending credit unless force. When due, the stream target is retuned against the connection's RTT estimate and a WINDOW_UPDATE for the stream is serialized; the stream receive window is credited (saturating at CWIST_HTTP2_MAX_WINDOW), the pending accumulator is cleared, and the update timestamp is advanced.

Parameters

connection_flow_control	Connection flow-control state supplying the RTT estimate.
stream_flow_control	Stream flow-control state to update.
buffer	Destination buffer for the serialized frame.
buffer_len	Available bytes in `buffer` (at least 13 required).
written	Set to 0 when no frame is emitted, to 13 on success.
now_us	Current time in microseconds; drives retuning.
force	Emit the update even when less than half the target window is pending.

Returns: 1 when a WINDOW_UPDATE frame was written, 0 when the stream is ineligible or no update is due, -1 when flow_control arguments are NULL or the frame could not be serialized.

Definition at line 443 of file http2_flow_control.c.

References cap, and CWIST_HTTP2_MAX_WINDOW.

◆ cwist_http2_stream_flow_control_receive()

bool cwist_http2_stream_flow_control_receive	(	cwist_http2_stream_flow_control *	flow_control,
		uint32_t	bytes
	)

Account received DATA bytes against a stream receive window.

Parameters

flow_control	Stream flow-control state.
bytes	Number of bytes received from the peer on the stream.

Return values

true	`bytes` fit in the remaining receive window and were debited.
false	`flow_control` is NULL or `bytes` exceed the remaining window; nothing is debited.

Definition at line 262 of file http2_flow_control.c.

References cap.

Referenced by cwist_http2_serve_connection_ex().

Functions

Function Documentation

◆ cwist_http2_flow_control_add_send_window()

◆ cwist_http2_flow_control_consume()

◆ cwist_http2_flow_control_init()

◆ cwist_http2_flow_control_maybe_window_update()

◆ cwist_http2_flow_control_pacing_allowance()

◆ cwist_http2_flow_control_receive()

◆ cwist_http2_flow_control_reserve_send()

◆ cwist_http2_flow_control_update_rtt()

◆ cwist_http2_stream_flow_control_add_send_window()

◆ cwist_http2_stream_flow_control_consume()

◆ cwist_http2_stream_flow_control_init()

◆ cwist_http2_stream_flow_control_maybe_window_update()

◆ cwist_http2_stream_flow_control_receive()