Documentation for SetParam QUIC_PARAM_STREAM_PRIORITY

[Johan511]

Describe the feature you'd like supported

Currently the documentation does not elaborate on what the priority parameter actually means, does lower priority number mean the stream is drained first or is it the other way around?

Over here

#define QUIC_PARAM_STREAM_PRIORITY                      0x08000003  // uint16_t - 0 (low) to 0xFFFF (high) - 0x7FFF (default)

it is mentioned that 0 is low and 0xFFFF is high, which logically seems to imply that 0xFFFF gets drained first

Over here
The circular linked list (Stream->SendLink) seems to be ordered from highest priority to lowest priority

void
QuicSendUpdateStreamPriority(
    _In_ QUIC_SEND* Send,
    _In_ QUIC_STREAM* Stream
    )
{
    CXPLAT_DBG_ASSERT(Stream->SendLink.Flink != NULL);
    CxPlatListEntryRemove(&Stream->SendLink);

    CXPLAT_LIST_ENTRY* Entry = Send->SendStreams.Blink;
    while (Entry != &Send->SendStreams) {
        //
        // Search back to front for the right place (based on priority) to
        // insert the stream.
        //
        if (Stream->SendPriority <=
            CXPLAT_CONTAINING_RECORD(Entry, QUIC_STREAM, SendLink)->SendPriority) {
            break;
        }
        Entry = Entry->Blink;
    }
    CxPlatListInsertHead(Entry, &Stream->SendLink); // Insert after current Entry
}

Over here
The first stream which can be sent seems to be sent, which would imply stream with a higher priority number is sent first.

_Success_(return != NULL)
QUIC_STREAM*
QuicSendGetNextStream(
    _In_ QUIC_SEND* Send,
    _Out_ uint32_t* PacketCount
    )
{
    QUIC_CONNECTION* Connection = QuicSendGetConnection(Send);
    CXPLAT_DBG_ASSERT(!QuicConnIsClosed(Connection) || CxPlatListIsEmpty(&Send->SendStreams));

    CXPLAT_LIST_ENTRY* Entry = Send->SendStreams.Flink;
    while (Entry != &Send->SendStreams) {

        //
        // TODO: performance: We currently search through blocked
        // streams repeatedly as we loop.
        //

        QUIC_STREAM* Stream = CXPLAT_CONTAINING_RECORD(Entry, QUIC_STREAM, SendLink);

        //
        // Make sure, given the current state of the connection and the stream,
        // that we can use the stream to frame a packet.
        //
        if (QuicSendCanSendStreamNow(Stream)) {

            if (Connection->State.UseRoundRobinStreamScheduling) {
                //
                // Move the stream after any streams of the same priority. Start
                // with the "next" entry in the list and keep going until the
                // next entry's priority is less. Then move the stream before
                // that entry.
                //
                CXPLAT_LIST_ENTRY* LastEntry = Stream->SendLink.Flink;
                while (LastEntry != &Send->SendStreams) {
                    if (Stream->SendPriority >
                        CXPLAT_CONTAINING_RECORD(LastEntry, QUIC_STREAM, SendLink)->SendPriority) {
                        break;
                    }
                    LastEntry = LastEntry->Flink;
                }
                if (LastEntry->Blink != &Stream->SendLink) {
                    CxPlatListEntryRemove(&Stream->SendLink);
                    CxPlatListInsertTail(LastEntry, &Stream->SendLink);
                }

                *PacketCount = QUIC_STREAM_SEND_BATCH_COUNT;

            } else { // FIFO prioritization scheme
                *PacketCount = UINT32_MAX;
            }

            return Stream;
        }

        Entry = Entry->Flink;
    }

    return NULL;
}

Proposed solution

Add to description of stream priority in Settings.md.

Additional context

No response

[nibanks]

We will try to get this documented in the next couple of weeks. But for now, yes, the streams should be sent in order of high to low priority.