/src/h2/src/proto/streams/stream.rs

Source
use crate::Reason;

use super::*;

use std::fmt;
use std::task::{Context, Waker};
use std::time::Instant;

/// Tracks Stream related state
///
/// # Reference counting
///
/// There can be a number of outstanding handles to a single Stream. These are
/// tracked using reference counting. The `ref_count` field represents the
/// number of outstanding userspace handles that can reach this stream.
///
/// It's important to note that when the stream is placed in an internal queue
/// (such as an accept queue), this is **not** tracked by a reference count.
/// Thus, `ref_count` can be zero and the stream still has to be kept around.
pub(super) struct Stream {
    /// The h2 stream identifier
    pub id: StreamId,

    /// Current state of the stream
    pub state: State,

    /// Set to `true` when the stream is counted against the connection's max
    /// concurrent streams.
    pub is_counted: bool,

    /// Number of outstanding handles pointing to this stream
    pub ref_count: usize,

    // ===== Fields related to sending =====
    /// Next node in the accept linked list
    pub next_pending_send: Option<store::Key>,

    /// Set to true when the stream is pending accept
    pub is_pending_send: bool,

    /// Send data flow control
    pub send_flow: FlowControl,

    /// Amount of send capacity that has been requested, but not yet allocated.
    pub requested_send_capacity: WindowSize,

    /// Amount of data buffered at the prioritization layer.
    /// TODO: Technically this could be greater than the window size...
    pub buffered_send_data: usize,

    /// Task tracking additional send capacity (i.e. window updates).
    send_task: Option<Waker>,

    /// Frames pending for this stream being sent to the socket
    pub pending_send: buffer::Deque,

    /// Next node in the linked list of streams waiting for additional
    /// connection level capacity.
    pub next_pending_send_capacity: Option<store::Key>,

    /// True if the stream is waiting for outbound connection capacity
    pub is_pending_send_capacity: bool,

    /// Set to true when the send capacity has been incremented
    pub send_capacity_inc: bool,

    /// Next node in the open linked list
    pub next_open: Option<store::Key>,

    /// Set to true when the stream is pending to be opened
    pub is_pending_open: bool,

    /// Set to true when a push is pending for this stream
    pub is_pending_push: bool,

    // ===== Fields related to receiving =====
    /// Next node in the accept linked list
    pub next_pending_accept: Option<store::Key>,

    /// Set to true when the stream is pending accept
    pub is_pending_accept: bool,

    /// Receive data flow control
    pub recv_flow: FlowControl,

    pub in_flight_recv_data: WindowSize,

    /// Next node in the linked list of streams waiting to send window updates.
    pub next_window_update: Option<store::Key>,

    /// True if the stream is waiting to send a window update
    pub is_pending_window_update: bool,

    /// The time when this stream may have been locally reset.
    pub reset_at: Option<Instant>,

    /// Next node in list of reset streams that should expire eventually
    pub next_reset_expire: Option<store::Key>,

    /// Frames pending for this stream to read
    pub pending_recv: buffer::Deque,

    /// When the RecvStream drop occurs, no data should be received.
    pub is_recv: bool,

    /// Task tracking receiving frames
    pub recv_task: Option<Waker>,

    /// Task tracking pushed promises.
    pub push_task: Option<Waker>,

    /// The stream's pending push promises
    pub pending_push_promises: store::Queue<NextAccept>,

    /// Validate content-length headers
    pub content_length: ContentLength,
}

/// State related to validating a stream's content-length
#[derive(Debug)]
pub enum ContentLength {
    Omitted,
    Head,
    Remaining(u64),
}

#[derive(Debug)]
pub(super) struct NextAccept;

#[derive(Debug)]
pub(super) struct NextSend;

#[derive(Debug)]
pub(super) struct NextSendCapacity;

#[derive(Debug)]
pub(super) struct NextWindowUpdate;

#[derive(Debug)]
pub(super) struct NextOpen;

#[derive(Debug)]
pub(super) struct NextResetExpire;

impl Stream {
    pub fn new(id: StreamId, init_send_window: WindowSize, init_recv_window: WindowSize) -> Stream {
        let mut send_flow = FlowControl::new();
        let mut recv_flow = FlowControl::new();

        recv_flow
            .inc_window(init_recv_window)
            .expect("invalid initial receive window");
        // TODO: proper error handling?
        let _res = recv_flow.assign_capacity(init_recv_window);
        debug_assert!(_res.is_ok());

        send_flow
            .inc_window(init_send_window)
            .expect("invalid initial send window size");

        Stream {
            id,
            state: State::default(),
            ref_count: 0,
            is_counted: false,

            // ===== Fields related to sending =====
            next_pending_send: None,
            is_pending_send: false,
            send_flow,
            requested_send_capacity: 0,
            buffered_send_data: 0,
            send_task: None,
            pending_send: buffer::Deque::new(),
            is_pending_send_capacity: false,
            next_pending_send_capacity: None,
            send_capacity_inc: false,
            is_pending_open: false,
            next_open: None,
            is_pending_push: false,

            // ===== Fields related to receiving =====
            next_pending_accept: None,
            is_pending_accept: false,
            recv_flow,
            in_flight_recv_data: 0,
            next_window_update: None,
            is_pending_window_update: false,
            reset_at: None,
            next_reset_expire: None,
            pending_recv: buffer::Deque::new(),
            is_recv: true,
            recv_task: None,
            push_task: None,
            pending_push_promises: store::Queue::new(),
            content_length: ContentLength::Omitted,
        }
    }

    /// Increment the stream's ref count
    pub fn ref_inc(&mut self) {
        assert!(self.ref_count < usize::MAX);
        self.ref_count += 1;
    }

    /// Decrements the stream's ref count
    pub fn ref_dec(&mut self) {
        assert!(self.ref_count > 0);
        self.ref_count -= 1;
    }

    /// Returns true if stream is currently being held for some time because of
    /// a local reset.
    pub fn is_pending_reset_expiration(&self) -> bool {
        self.reset_at.is_some()
    }

    /// Returns true if frames for this stream are ready to be sent over the wire
    pub fn is_send_ready(&self) -> bool {
        // Why do we check pending_open?
        //
        // We allow users to call send_request() which schedules a stream to be pending_open
        // if there is no room according to the concurrency limit (max_send_streams), and we
        // also allow data to be buffered for send with send_data() if there is no capacity for
        // the stream to send the data, which attempts to place the stream in pending_send.
        // If the stream is not open, we don't want the stream to be scheduled for
        // execution (pending_send). Note that if the stream is in pending_open, it will be
        // pushed to pending_send when there is room for an open stream.
        //
        // In pending_push we track whether a PushPromise still needs to be sent
        // from a different stream before we can start sending frames on this one.
        // This is different from the "open" check because reserved streams don't count
        // toward the concurrency limit.
        // See https://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2
        !self.is_pending_open && !self.is_pending_push
    }

    /// Returns true if the stream is closed
    pub fn is_closed(&self) -> bool {
        // The state has fully transitioned to closed.
        self.state.is_closed() &&
            // Because outbound frames transition the stream state before being
            // buffered, we have to ensure that all frames have been flushed.
            self.pending_send.is_empty() &&
            // Sometimes large data frames are sent out in chunks. After a chunk
            // of the frame is sent, the remainder is pushed back onto the send
            // queue to be rescheduled.
            //
            // Checking for additional buffered data lets us catch this case.
            self.buffered_send_data == 0
    }

    /// Returns true if the stream is no longer in use
    pub fn is_released(&self) -> bool {
        // The stream is closed and fully flushed
        self.is_closed() &&
            // There are no more outstanding references to the stream
            self.ref_count == 0 &&
            // The stream is not in any queue
            !self.is_pending_send && !self.is_pending_send_capacity &&
            !self.is_pending_accept && !self.is_pending_window_update &&
            !self.is_pending_open && self.reset_at.is_none()
    }

    /// Returns true when the consumer of the stream has dropped all handles
    /// (indicating no further interest in the stream) and the stream state is
    /// not actually closed.
    ///
    /// In this case, a reset should be sent.
    pub fn is_canceled_interest(&self) -> bool {
        self.ref_count == 0 && !self.state.is_closed()
    }

    /// Current available stream send capacity
    pub fn capacity(&self, max_buffer_size: usize) -> WindowSize {
        let available = self.send_flow.available().as_size() as usize;
        let buffered = self.buffered_send_data;

        available.min(max_buffer_size).saturating_sub(buffered) as WindowSize
    }

    pub fn assign_capacity(&mut self, capacity: WindowSize, max_buffer_size: usize) {
        let prev_capacity = self.capacity(max_buffer_size);
        debug_assert!(capacity > 0);
        // TODO: proper error handling
        let _res = self.send_flow.assign_capacity(capacity);
        debug_assert!(_res.is_ok());

        tracing::trace!(
            "  assigned capacity to stream; available={}; buffered={}; id={:?}; max_buffer_size={} prev={}",
            self.send_flow.available(),
            self.buffered_send_data,
            self.id,
            max_buffer_size,
            prev_capacity,
        );

        if prev_capacity < self.capacity(max_buffer_size) {
            self.notify_capacity();
        }
    }

    pub fn send_data(&mut self, len: WindowSize, max_buffer_size: usize) {
        let prev_capacity = self.capacity(max_buffer_size);

        // TODO: proper error handling
        let _res = self.send_flow.send_data(len);
        debug_assert!(_res.is_ok());

        // Decrement the stream's buffered data counter
        debug_assert!(self.buffered_send_data >= len as usize);
        self.buffered_send_data -= len as usize;
        self.requested_send_capacity -= len;

        tracing::trace!(
            "  sent stream data; available={}; buffered={}; id={:?}; max_buffer_size={} prev={}",
            self.send_flow.available(),
            self.buffered_send_data,
            self.id,
            max_buffer_size,
            prev_capacity,
        );

        if prev_capacity < self.capacity(max_buffer_size) {
            self.notify_capacity();
        }
    }

    /// If the capacity was limited because of the max_send_buffer_size,
    /// then consider waking the send task again...
    pub fn notify_capacity(&mut self) {
        self.send_capacity_inc = true;
        tracing::trace!("  notifying task");
        self.notify_send();
    }

    /// Returns `Err` when the decrement cannot be completed due to overflow.
    pub fn dec_content_length(&mut self, len: usize) -> Result<(), ()> {
        match self.content_length {
            ContentLength::Remaining(ref mut rem) => match rem.checked_sub(len as u64) {
                Some(val) => *rem = val,
                None => return Err(()),
            },
            ContentLength::Head => {
                if len != 0 {
                    return Err(());
                }
            }
            _ => {}
        }

        Ok(())
    }

    pub fn ensure_content_length_zero(&self) -> Result<(), ()> {
        match self.content_length {
            ContentLength::Remaining(0) => Ok(()),
            ContentLength::Remaining(_) => Err(()),
            _ => Ok(()),
        }
    }

    pub fn notify_send(&mut self) {
        if let Some(task) = self.send_task.take() {
            task.wake();
        }
    }

    pub fn wait_send(&mut self, cx: &Context) {
        self.send_task = Some(cx.waker().clone());
    }

    pub fn notify_recv(&mut self) {
        if let Some(task) = self.recv_task.take() {
            task.wake();
        }
    }

    pub(super) fn notify_push(&mut self) {
        if let Some(task) = self.push_task.take() {
            task.wake();
        }
    }

    /// Set the stream's state to `Closed` with the given reason and initiator.
    /// Notify the send and receive tasks, if they exist.
    pub(super) fn set_reset(&mut self, reason: Reason, initiator: Initiator) {
        self.state.set_reset(self.id, reason, initiator);
        self.notify_push();
        self.notify_recv();
    }
}

impl fmt::Debug for Stream {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Stream")
            .field("id", &self.id)
            .field("state", &self.state)
            .field("is_counted", &self.is_counted)
            .field("ref_count", &self.ref_count)
            .h2_field_some("next_pending_send", &self.next_pending_send)
            .h2_field_if("is_pending_send", &self.is_pending_send)
            .field("send_flow", &self.send_flow)
            .field("requested_send_capacity", &self.requested_send_capacity)
            .field("buffered_send_data", &self.buffered_send_data)
            .h2_field_some("send_task", &self.send_task.as_ref().map(|_| ()))
            .h2_field_if_then(
                "pending_send",
                !self.pending_send.is_empty(),
                &self.pending_send,
            )
            .h2_field_some(
                "next_pending_send_capacity",
                &self.next_pending_send_capacity,
            )
            .h2_field_if("is_pending_send_capacity", &self.is_pending_send_capacity)
            .h2_field_if("send_capacity_inc", &self.send_capacity_inc)
            .h2_field_some("next_open", &self.next_open)
            .h2_field_if("is_pending_open", &self.is_pending_open)
            .h2_field_if("is_pending_push", &self.is_pending_push)
            .h2_field_some("next_pending_accept", &self.next_pending_accept)
            .h2_field_if("is_pending_accept", &self.is_pending_accept)
            .field("recv_flow", &self.recv_flow)
            .field("in_flight_recv_data", &self.in_flight_recv_data)
            .h2_field_some("next_window_update", &self.next_window_update)
            .h2_field_if("is_pending_window_update", &self.is_pending_window_update)
            .h2_field_some("reset_at", &self.reset_at)
            .h2_field_some("next_reset_expire", &self.next_reset_expire)
            .h2_field_if_then(
                "pending_recv",
                !self.pending_recv.is_empty(),
                &self.pending_recv,
            )
            .h2_field_if("is_recv", &self.is_recv)
            .h2_field_some("recv_task", &self.recv_task.as_ref().map(|_| ()))
            .h2_field_some("push_task", &self.push_task.as_ref().map(|_| ()))
            .h2_field_if_then(
                "pending_push_promises",
                !self.pending_push_promises.is_empty(),
                &self.pending_push_promises,
            )
            .field("content_length", &self.content_length)
            .finish()
    }
}

impl store::Next for NextAccept {
    fn next(stream: &Stream) -> Option<store::Key> {
        stream.next_pending_accept
    }

    fn set_next(stream: &mut Stream, key: Option<store::Key>) {
        stream.next_pending_accept = key;
    }

    fn take_next(stream: &mut Stream) -> Option<store::Key> {
        stream.next_pending_accept.take()
    }

    fn is_queued(stream: &Stream) -> bool {
        stream.is_pending_accept
    }

    fn set_queued(stream: &mut Stream, val: bool) {
        stream.is_pending_accept = val;
    }
}

impl store::Next for NextSend {
    fn next(stream: &Stream) -> Option<store::Key> {
        stream.next_pending_send
    }

    fn set_next(stream: &mut Stream, key: Option<store::Key>) {
        stream.next_pending_send = key;
    }

    fn take_next(stream: &mut Stream) -> Option<store::Key> {
        stream.next_pending_send.take()
    }

    fn is_queued(stream: &Stream) -> bool {
        stream.is_pending_send
    }

    fn set_queued(stream: &mut Stream, val: bool) {
        if val {
            // ensure that stream is not queued for being opened
            // if it's being put into queue for sending data
            debug_assert!(!stream.is_pending_open);
        }
        stream.is_pending_send = val;
    }
}

impl store::Next for NextSendCapacity {
    fn next(stream: &Stream) -> Option<store::Key> {
        stream.next_pending_send_capacity
    }

    fn set_next(stream: &mut Stream, key: Option<store::Key>) {
        stream.next_pending_send_capacity = key;
    }

    fn take_next(stream: &mut Stream) -> Option<store::Key> {
        stream.next_pending_send_capacity.take()
    }

    fn is_queued(stream: &Stream) -> bool {
        stream.is_pending_send_capacity
    }

    fn set_queued(stream: &mut Stream, val: bool) {
        stream.is_pending_send_capacity = val;
    }
}

impl store::Next for NextWindowUpdate {
    fn next(stream: &Stream) -> Option<store::Key> {
        stream.next_window_update
    }

    fn set_next(stream: &mut Stream, key: Option<store::Key>) {
        stream.next_window_update = key;
    }

    fn take_next(stream: &mut Stream) -> Option<store::Key> {
        stream.next_window_update.take()
    }

    fn is_queued(stream: &Stream) -> bool {
        stream.is_pending_window_update
    }

    fn set_queued(stream: &mut Stream, val: bool) {
        stream.is_pending_window_update = val;
    }
}

impl store::Next for NextOpen {
    fn next(stream: &Stream) -> Option<store::Key> {
        stream.next_open
    }

    fn set_next(stream: &mut Stream, key: Option<store::Key>) {
        stream.next_open = key;
    }

    fn take_next(stream: &mut Stream) -> Option<store::Key> {
        stream.next_open.take()
    }

    fn is_queued(stream: &Stream) -> bool {
        stream.is_pending_open
    }

    fn set_queued(stream: &mut Stream, val: bool) {
        if val {
            // ensure that stream is not queued for being sent
            // if it's being put into queue for opening the stream
            debug_assert!(!stream.is_pending_send);
        }
        stream.is_pending_open = val;
    }
}

impl store::Next for NextResetExpire {
    fn next(stream: &Stream) -> Option<store::Key> {
        stream.next_reset_expire
    }

    fn set_next(stream: &mut Stream, key: Option<store::Key>) {
        stream.next_reset_expire = key;
    }

    fn take_next(stream: &mut Stream) -> Option<store::Key> {
        stream.next_reset_expire.take()
    }

    fn is_queued(stream: &Stream) -> bool {
        stream.reset_at.is_some()
    }

    fn set_queued(stream: &mut Stream, val: bool) {
        if val {
            stream.reset_at = Some(Instant::now());
        } else {
            stream.reset_at = None;
        }
    }
}

// ===== impl ContentLength =====

impl ContentLength {
    pub fn is_head(&self) -> bool {
        matches!(*self, Self::Head)
    }
}

Coverage Report

Created: 2025-10-13 06:32

Line	Count	Source
1		use crate::Reason;
2
3		use super::*;
4
5		use std::fmt;
6		use std::task::{Context, Waker};
7		use std::time::Instant;
8
9		/// Tracks Stream related state
10		///
11		/// # Reference counting
12		///
13		/// There can be a number of outstanding handles to a single Stream. These are
14		/// tracked using reference counting. The `ref_count` field represents the
15		/// number of outstanding userspace handles that can reach this stream.
16		///
17		/// It's important to note that when the stream is placed in an internal queue
18		/// (such as an accept queue), this is not tracked by a reference count.
19		/// Thus, `ref_count` can be zero and the stream still has to be kept around.
20		pub(super) struct Stream {
21		/// The h2 stream identifier
22		pub id: StreamId,
23
24		/// Current state of the stream
25		pub state: State,
26
27		/// Set to `true` when the stream is counted against the connection's max
28		/// concurrent streams.
29		pub is_counted: bool,
30
31		/// Number of outstanding handles pointing to this stream
32		pub ref_count: usize,
33
34		// ===== Fields related to sending =====
35		/// Next node in the accept linked list
36		pub next_pending_send: Option<store::Key>,
37
38		/// Set to true when the stream is pending accept
39		pub is_pending_send: bool,
40
41		/// Send data flow control
42		pub send_flow: FlowControl,
43
44		/// Amount of send capacity that has been requested, but not yet allocated.
45		pub requested_send_capacity: WindowSize,
46
47		/// Amount of data buffered at the prioritization layer.
48		/// TODO: Technically this could be greater than the window size...
49		pub buffered_send_data: usize,
50
51		/// Task tracking additional send capacity (i.e. window updates).
52		send_task: Option<Waker>,
53
54		/// Frames pending for this stream being sent to the socket
55		pub pending_send: buffer::Deque,
56
57		/// Next node in the linked list of streams waiting for additional
58		/// connection level capacity.
59		pub next_pending_send_capacity: Option<store::Key>,
60
61		/// True if the stream is waiting for outbound connection capacity
62		pub is_pending_send_capacity: bool,
63
64		/// Set to true when the send capacity has been incremented
65		pub send_capacity_inc: bool,
66
67		/// Next node in the open linked list
68		pub next_open: Option<store::Key>,
69
70		/// Set to true when the stream is pending to be opened
71		pub is_pending_open: bool,
72
73		/// Set to true when a push is pending for this stream
74		pub is_pending_push: bool,
75
76		// ===== Fields related to receiving =====
77		/// Next node in the accept linked list
78		pub next_pending_accept: Option<store::Key>,
79
80		/// Set to true when the stream is pending accept
81		pub is_pending_accept: bool,
82
83		/// Receive data flow control
84		pub recv_flow: FlowControl,
85
86		pub in_flight_recv_data: WindowSize,
87
88		/// Next node in the linked list of streams waiting to send window updates.
89		pub next_window_update: Option<store::Key>,
90
91		/// True if the stream is waiting to send a window update
92		pub is_pending_window_update: bool,
93
94		/// The time when this stream may have been locally reset.
95		pub reset_at: Option<Instant>,
96
97		/// Next node in list of reset streams that should expire eventually
98		pub next_reset_expire: Option<store::Key>,
99
100		/// Frames pending for this stream to read
101		pub pending_recv: buffer::Deque,
102
103		/// When the RecvStream drop occurs, no data should be received.
104		pub is_recv: bool,
105
106		/// Task tracking receiving frames
107		pub recv_task: Option<Waker>,
108
109		/// Task tracking pushed promises.
110		pub push_task: Option<Waker>,
111
112		/// The stream's pending push promises
113		pub pending_push_promises: store::Queue<NextAccept>,
114
115		/// Validate content-length headers
116		pub content_length: ContentLength,
117		}
118
119		/// State related to validating a stream's content-length
120		#[derive(Debug)]
121		pub enum ContentLength {
122		Omitted,
123		Head,
124		Remaining(u64),
125		}
126
127		#[derive(Debug)]
128		pub(super) struct NextAccept;
129
130		#[derive(Debug)]
131		pub(super) struct NextSend;
132
133		#[derive(Debug)]
134		pub(super) struct NextSendCapacity;
135
136		#[derive(Debug)]
137		pub(super) struct NextWindowUpdate;
138
139		#[derive(Debug)]
140		pub(super) struct NextOpen;
141
142		#[derive(Debug)]
143		pub(super) struct NextResetExpire;
144
145		impl Stream {
146	463k	pub fn new(id: StreamId, init_send_window: WindowSize, init_recv_window: WindowSize) -> Stream {
147	463k	let mut send_flow = FlowControl::new();
148	463k	let mut recv_flow = FlowControl::new();
149
150	463k	recv_flow
151	463k	.inc_window(init_recv_window)
152	463k	.expect("invalid initial receive window");
153		// TODO: proper error handling?
154	463k	let _res = recv_flow.assign_capacity(init_recv_window);
155	463k	debug_assert!(_res.is_ok());
156
157	463k	send_flow
158	463k	.inc_window(init_send_window)
159	463k	.expect("invalid initial send window size");
160
161	463k	Stream {
162	463k	id,
163	463k	state: State::default(),
164	463k	ref_count: 0,
165	463k	is_counted: false,
166	463k
167	463k	// ===== Fields related to sending =====
168	463k	next_pending_send: None,
169	463k	is_pending_send: false,
170	463k	send_flow,
171	463k	requested_send_capacity: 0,
172	463k	buffered_send_data: 0,
173	463k	send_task: None,
174	463k	pending_send: buffer::Deque::new(),
175	463k	is_pending_send_capacity: false,
176	463k	next_pending_send_capacity: None,
177	463k	send_capacity_inc: false,
178	463k	is_pending_open: false,
179	463k	next_open: None,
180	463k	is_pending_push: false,
181	463k
182	463k	// ===== Fields related to receiving =====
183	463k	next_pending_accept: None,
184	463k	is_pending_accept: false,
185	463k	recv_flow,
186	463k	in_flight_recv_data: 0,
187	463k	next_window_update: None,
188	463k	is_pending_window_update: false,
189	463k	reset_at: None,
190	463k	next_reset_expire: None,
191	463k	pending_recv: buffer::Deque::new(),
192	463k	is_recv: true,
193	463k	recv_task: None,
194	463k	push_task: None,
195	463k	pending_push_promises: store::Queue::new(),
196	463k	content_length: ContentLength::Omitted,
197	463k	}
198	463k	}
199
200		/// Increment the stream's ref count
201	855k	pub fn ref_inc(&mut self) {
202	855k	assert!(self.ref_count < usize::MAX);
203	855k	self.ref_count += 1;
204	855k	}
205
206		/// Decrements the stream's ref count
207	855k	pub fn ref_dec(&mut self) {
208	855k	assert!(self.ref_count > 0);
209	855k	self.ref_count -= 1;
210	855k	}
211
212		/// Returns true if stream is currently being held for some time because of
213		/// a local reset.
214	4.31M	pub fn is_pending_reset_expiration(&self) -> bool {
215	4.31M	self.reset_at.is_some()
216	4.31M	}
217
218		/// Returns true if frames for this stream are ready to be sent over the wire
219	912k	pub fn is_send_ready(&self) -> bool {
220		// Why do we check pending_open?
221		//
222		// We allow users to call send_request() which schedules a stream to be pending_open
223		// if there is no room according to the concurrency limit (max_send_streams), and we
224		// also allow data to be buffered for send with send_data() if there is no capacity for
225		// the stream to send the data, which attempts to place the stream in pending_send.
226		// If the stream is not open, we don't want the stream to be scheduled for
227		// execution (pending_send). Note that if the stream is in pending_open, it will be
228		// pushed to pending_send when there is room for an open stream.
229		//
230		// In pending_push we track whether a PushPromise still needs to be sent
231		// from a different stream before we can start sending frames on this one.
232		// This is different from the "open" check because reserved streams don't count
233		// toward the concurrency limit.
234		// See https://httpwg.org/specs/rfc7540.html#rfc.section.5.1.2
235	912k	!self.is_pending_open && !self.is_pending_push
236	912k	}
237
238		/// Returns true if the stream is closed
239	5.93M	pub fn is_closed(&self) -> bool {
240		// The state has fully transitioned to closed.
241	5.93M	self.state.is_closed() &&
242		// Because outbound frames transition the stream state before being
243		// buffered, we have to ensure that all frames have been flushed.
244	3.58M	self.pending_send.is_empty() &&
245		// Sometimes large data frames are sent out in chunks. After a chunk
246		// of the frame is sent, the remainder is pushed back onto the send
247		// queue to be rescheduled.
248		//
249		// Checking for additional buffered data lets us catch this case.
250	3.25M	self.buffered_send_data == 0
251	5.93M	}
252
253		/// Returns true if the stream is no longer in use
254	2.75M	pub fn is_released(&self) -> bool {
255		// The stream is closed and fully flushed
256	2.75M	self.is_closed() &&
257		// There are no more outstanding references to the stream
258	1.45M	self.ref_count == 0 &&
259		// The stream is not in any queue
260	933k	!self.is_pending_send && !self.is_pending_send_capacity &&
261	614k	!self.is_pending_accept && !self.is_pending_window_update &&
262	613k	!self.is_pending_open && self.reset_at.is_none()
263	2.75M	}
264
265		/// Returns true when the consumer of the stream has dropped all handles
266		/// (indicating no further interest in the stream) and the stream state is
267		/// not actually closed.
268		///
269		/// In this case, a reset should be sent.
270	855k	pub fn is_canceled_interest(&self) -> bool {
271	855k	self.ref_count == 0 && !self.state.is_closed()
272	855k	}
273
274		/// Current available stream send capacity
275	213k	pub fn capacity(&self, max_buffer_size: usize) -> WindowSize {
276	213k	let available = self.send_flow.available().as_size() as usize;
277	213k	let buffered = self.buffered_send_data;
278
279	213k	available.min(max_buffer_size).saturating_sub(buffered) as WindowSize
280	213k	}
281
282	88.3k	pub fn assign_capacity(&mut self, capacity: WindowSize, max_buffer_size: usize) {
283	88.3k	let prev_capacity = self.capacity(max_buffer_size);
284	88.3k	debug_assert!(capacity > 0);
285		// TODO: proper error handling
286	88.3k	let _res = self.send_flow.assign_capacity(capacity);
287	88.3k	debug_assert!(_res.is_ok());
288
289	88.3k	tracing::trace!(
290	0	" assigned capacity to stream; available={}; buffered={}; id={:?}; max_buffer_size={} prev={}",
291	0	self.send_flow.available(),
292		self.buffered_send_data,
293		self.id,
294		max_buffer_size,
295		prev_capacity,
296		);
297
298	88.3k	if prev_capacity < self.capacity(max_buffer_size) {
299	0	self.notify_capacity();
300	88.3k	}
301	88.3k	}
302
303	18.1k	pub fn send_data(&mut self, len: WindowSize, max_buffer_size: usize) {
304	18.1k	let prev_capacity = self.capacity(max_buffer_size);
305
306		// TODO: proper error handling
307	18.1k	let _res = self.send_flow.send_data(len);
308	18.1k	debug_assert!(_res.is_ok());
309
310		// Decrement the stream's buffered data counter
311	18.1k	debug_assert!(self.buffered_send_data >= len as usize);
312	18.1k	self.buffered_send_data -= len as usize;
313	18.1k	self.requested_send_capacity -= len;
314
315	18.1k	tracing::trace!(
316	0	" sent stream data; available={}; buffered={}; id={:?}; max_buffer_size={} prev={}",
317	0	self.send_flow.available(),
318		self.buffered_send_data,
319		self.id,
320		max_buffer_size,
321		prev_capacity,
322		);
323
324	18.1k	if prev_capacity < self.capacity(max_buffer_size) {
325	0	self.notify_capacity();
326	18.1k	}
327	18.1k	}
328
329		/// If the capacity was limited because of the max_send_buffer_size,
330		/// then consider waking the send task again...
331	0	pub fn notify_capacity(&mut self) {
332	0	self.send_capacity_inc = true;
333	0	tracing::trace!(" notifying task");
334	0	self.notify_send();
335	0	}
336
337		/// Returns `Err` when the decrement cannot be completed due to overflow.
338	2.82k	pub fn dec_content_length(&mut self, len: usize) -> Result<(), ()> {
339	2.82k	match self.content_length {
340	1.63k	ContentLength::Remaining(ref mut rem) => match rem.checked_sub(len as u64) {
341	1.63k	Some(val) => *rem = val,
342	1	None => return Err(()),
343		},
344		ContentLength::Head => {
345	0	if len != 0 {
346	0	return Err(());
347	0	}
348		}
349	1.19k	_ => {}
350		}
351
352	2.82k	Ok(())
353	2.82k	}
354
355	108	pub fn ensure_content_length_zero(&self) -> Result<(), ()> {
356	108	match self.content_length {
357	2	ContentLength::Remaining(0) => Ok(()),
358	52	ContentLength::Remaining(_) => Err(()),
359	54	_ => Ok(()),
360		}
361	108	}
362
363	769k	pub fn notify_send(&mut self) {
364	769k	if let Some(task) = self.send_task.take() {
365	238	task.wake();
366	769k	}
367	769k	}
368
369	1.90k	pub fn wait_send(&mut self, cx: &Context) {
370	1.90k	self.send_task = Some(cx.waker().clone());
371	1.90k	}
372
373	760k	pub fn notify_recv(&mut self) {
374	760k	if let Some(task) = self.recv_task.take() {
375	424k	task.wake();
376	424k	}
377	760k	}
378
379	697k	pub(super) fn notify_push(&mut self) {
380	697k	if let Some(task) = self.push_task.take() {
381	0	task.wake();
382	697k	}
383	697k	}
384
385		/// Set the stream's state to `Closed` with the given reason and initiator.
386		/// Notify the send and receive tasks, if they exist.
387	107k	pub(super) fn set_reset(&mut self, reason: Reason, initiator: Initiator) {
388	107k	self.state.set_reset(self.id, reason, initiator);
389	107k	self.notify_push();
390	107k	self.notify_recv();
391	107k	}
392		}
393
394		impl fmt::Debug for Stream {
395	0	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
396	0	f.debug_struct("Stream")
397	0	.field("id", &self.id)
398	0	.field("state", &self.state)
399	0	.field("is_counted", &self.is_counted)
400	0	.field("ref_count", &self.ref_count)
401	0	.h2_field_some("next_pending_send", &self.next_pending_send)
402	0	.h2_field_if("is_pending_send", &self.is_pending_send)
403	0	.field("send_flow", &self.send_flow)
404	0	.field("requested_send_capacity", &self.requested_send_capacity)
405	0	.field("buffered_send_data", &self.buffered_send_data)
406	0	.h2_field_some("send_task", &self.send_task.as_ref().map(\|_\| ()))
407	0	.h2_field_if_then(
408	0	"pending_send",
409	0	!self.pending_send.is_empty(),
410	0	&self.pending_send,
411		)
412	0	.h2_field_some(
413	0	"next_pending_send_capacity",
414	0	&self.next_pending_send_capacity,
415		)
416	0	.h2_field_if("is_pending_send_capacity", &self.is_pending_send_capacity)
417	0	.h2_field_if("send_capacity_inc", &self.send_capacity_inc)
418	0	.h2_field_some("next_open", &self.next_open)
419	0	.h2_field_if("is_pending_open", &self.is_pending_open)
420	0	.h2_field_if("is_pending_push", &self.is_pending_push)
421	0	.h2_field_some("next_pending_accept", &self.next_pending_accept)
422	0	.h2_field_if("is_pending_accept", &self.is_pending_accept)
423	0	.field("recv_flow", &self.recv_flow)
424	0	.field("in_flight_recv_data", &self.in_flight_recv_data)
425	0	.h2_field_some("next_window_update", &self.next_window_update)
426	0	.h2_field_if("is_pending_window_update", &self.is_pending_window_update)
427	0	.h2_field_some("reset_at", &self.reset_at)
428	0	.h2_field_some("next_reset_expire", &self.next_reset_expire)
429	0	.h2_field_if_then(
430	0	"pending_recv",
431	0	!self.pending_recv.is_empty(),
432	0	&self.pending_recv,
433		)
434	0	.h2_field_if("is_recv", &self.is_recv)
435	0	.h2_field_some("recv_task", &self.recv_task.as_ref().map(\|_\| ()))
436	0	.h2_field_some("push_task", &self.push_task.as_ref().map(\|_\| ()))
437	0	.h2_field_if_then(
438	0	"pending_push_promises",
439	0	!self.pending_push_promises.is_empty(),
440	0	&self.pending_push_promises,
441		)
442	0	.field("content_length", &self.content_length)
443	0	.finish()
444	0	}
445		}
446
447		impl store::Next for NextAccept {
448	168	fn next(stream: &Stream) -> Option<store::Key> {
449	168	stream.next_pending_accept
450	168	}
451
452	37	fn set_next(stream: &mut Stream, key: Option<store::Key>) {
453	37	stream.next_pending_accept = key;
454	37	}
455
456	34	fn take_next(stream: &mut Stream) -> Option<store::Key> {
457	34	stream.next_pending_accept.take()
458	34	}
459
460	207	fn is_queued(stream: &Stream) -> bool {
461	207	stream.is_pending_accept
462	207	}
463
464	409	fn set_queued(stream: &mut Stream, val: bool) {
465	409	stream.is_pending_accept = val;
466	409	}
467		}
468
469		impl store::Next for NextSend {
470	6.48k	fn next(stream: &Stream) -> Option<store::Key> {
471	6.48k	stream.next_pending_send
472	6.48k	}
473
474	407k	fn set_next(stream: &mut Stream, key: Option<store::Key>) {
475	407k	stream.next_pending_send = key;
476	407k	}
477
478	407k	fn take_next(stream: &mut Stream) -> Option<store::Key> {
479	407k	stream.next_pending_send.take()
480	407k	}
481
482	750k	fn is_queued(stream: &Stream) -> bool {
483	750k	stream.is_pending_send
484	750k	}
485
486	827k	fn set_queued(stream: &mut Stream, val: bool) {
487	827k	if val {
488		// ensure that stream is not queued for being opened
489		// if it's being put into queue for sending data
490	413k	debug_assert!(!stream.is_pending_open);
491	413k	}
492	827k	stream.is_pending_send = val;
493	827k	}
494		}
495
496		impl store::Next for NextSendCapacity {
497	2.18k	fn next(stream: &Stream) -> Option<store::Key> {
498	2.18k	stream.next_pending_send_capacity
499	2.18k	}
500
501	244k	fn set_next(stream: &mut Stream, key: Option<store::Key>) {
502	244k	stream.next_pending_send_capacity = key;
503	244k	}
504
505	244k	fn take_next(stream: &mut Stream) -> Option<store::Key> {
506	244k	stream.next_pending_send_capacity.take()
507	244k	}
508
509	302k	fn is_queued(stream: &Stream) -> bool {
510	302k	stream.is_pending_send_capacity
511	302k	}
512
513	492k	fn set_queued(stream: &mut Stream, val: bool) {
514	492k	stream.is_pending_send_capacity = val;
515	492k	}
516		}
517
518		impl store::Next for NextWindowUpdate {
519	0	fn next(stream: &Stream) -> Option<store::Key> {
520	0	stream.next_window_update
521	0	}
522
523	0	fn set_next(stream: &mut Stream, key: Option<store::Key>) {
524	0	stream.next_window_update = key;
525	0	}
526
527	0	fn take_next(stream: &mut Stream) -> Option<store::Key> {
528	0	stream.next_window_update.take()
529	0	}
530
531	0	fn is_queued(stream: &Stream) -> bool {
532	0	stream.is_pending_window_update
533	0	}
534
535	0	fn set_queued(stream: &mut Stream, val: bool) {
536	0	stream.is_pending_window_update = val;
537	0	}
538		}
539
540		impl store::Next for NextOpen {
541	4.27k	fn next(stream: &Stream) -> Option<store::Key> {
542	4.27k	stream.next_open
543	4.27k	}
544
545	422k	fn set_next(stream: &mut Stream, key: Option<store::Key>) {
546	422k	stream.next_open = key;
547	422k	}
548
549	422k	fn take_next(stream: &mut Stream) -> Option<store::Key> {
550	422k	stream.next_open.take()
551	422k	}
552
553	427k	fn is_queued(stream: &Stream) -> bool {
554	427k	stream.is_pending_open
555	427k	}
556
557	854k	fn set_queued(stream: &mut Stream, val: bool) {
558	854k	if val {
559		// ensure that stream is not queued for being sent
560		// if it's being put into queue for opening the stream
561	427k	debug_assert!(!stream.is_pending_send);
562	427k	}
563	854k	stream.is_pending_open = val;
564	854k	}
565		}
566
567		impl store::Next for NextResetExpire {
568	4.87k	fn next(stream: &Stream) -> Option<store::Key> {
569	4.87k	stream.next_reset_expire
570	4.87k	}
571
572	44.5k	fn set_next(stream: &mut Stream, key: Option<store::Key>) {
573	44.5k	stream.next_reset_expire = key;
574	44.5k	}
575
576	44.5k	fn take_next(stream: &mut Stream) -> Option<store::Key> {
577	44.5k	stream.next_reset_expire.take()
578	44.5k	}
579
580	49.4k	fn is_queued(stream: &Stream) -> bool {
581	49.4k	stream.reset_at.is_some()
582	49.4k	}
583
584	98.8k	fn set_queued(stream: &mut Stream, val: bool) {
585	98.8k	if val {
586	49.4k	stream.reset_at = Some(Instant::now());
587	49.4k	} else {
588	49.4k	stream.reset_at = None;
589	49.4k	}
590	98.8k	}
591		}
592
593		// ===== impl ContentLength =====
594
595		impl ContentLength {
596	1.62k	pub fn is_head(&self) -> bool {
597	1.62k	matches!(*self, Self::Head)
598	1.62k	}
599		}