lsquic_pr_queue.h revision a5fa05f9 
1/* Copyright (c) 2017 - 2020 LiteSpeed Technologies Inc.  See LICENSE. */
2/*
3 * lsquic_pr_queue.h -- a queue of packet requests
4 *
5 * Some packets need to be replied to outside of context of existing
6 * mini or full connections:
7 *
8 *  1. A version negotiation packet needs to be sent when a packet
9 *     arrives that specifies QUIC version that we do not support.
10 *  2. A public reset packet needs to be sent when we receive a
11 *     packet that does not belong to a known QUIC connection.
12 *
13 * The replies cannot be sent immediately.  They share outgoing
14 * socket with existing connections and must be scheduled according
15 * to prioritization rules.
16 *
17 * The information needed to generate reply packet  -- connection ID,
18 * connection context, and the peer address -- is saved in the Packet
19 * Request Queue.
20 *
21 * When it is time to send packets, the connection iterator knows to
22 * call prq_next_conn() when appropriate.  What is returned is an
23 * evanescent connection object that disappears as soon as the reply
24 * packet is successfully sent out.
25 *
26 * There are two limits associated with Packet Request Queue:
27 *  1. Maximum number of packet requests that are allowed to be
28 *     pending at any one time.  This is simply to prevent memory
29 *     blowout.
30 *  2. Maximum verneg connection objects to be allocated at any one
31 *     time.  This number is the same as the maximum batch size in
32 *     the engine, because the packet (and, therefore, the connection)
33 *     is returned to the Packet Request Queue when it could not be
34 *     sent.
35 *
36 * We call this a "request" queue because it describes what we do with
37 * QUIC packets whose version we do not support or those packets that
38 * do not belong to an existing connection: we send a reply for each of
39 * these packets, which effectively makes them "requests."
40 */
41
42#ifndef LSQUIC_PR_QUEUE_H
43#define LSQUIC_PR_QUEUE_H 1
44
45struct lsquic_conn;
46struct lsquic_packet_in;
47struct lsquic_engine_settings;
48struct pr_queue;
49struct sockaddr;
50
51enum packet_req_type {
52    PACKET_REQ_VERNEG,
53    PACKET_REQ_PUBRES,
54    N_PREQ_TYPES,
55};
56
57extern const char *const lsquic_preqt2str[N_PREQ_TYPES];
58
59struct pr_queue *
60lsquic_prq_create (unsigned max_elems, unsigned max_conns,
61                const struct lsquic_engine_public *);
62
63void
64lsquic_prq_destroy (struct pr_queue *);
65
66int
67lsquic_prq_new_req (struct pr_queue *, enum packet_req_type,
68             const struct lsquic_packet_in *, void *conn_ctx,
69             const struct sockaddr *local_addr,
70             const struct sockaddr *peer_addr);
71
72struct lsquic_conn *
73lsquic_prq_next_conn (struct pr_queue *);
74
75int
76lsquic_prq_have_pending (const struct pr_queue *);
77
78void
79lsquic_prq_drop (struct lsquic_conn *);
80
81#endif
82