]>
Commit | Line | Data |
---|---|---|
69523214 HL |
1 | /* |
2 | * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. | |
3 | * | |
4 | * Licensed under the Apache License 2.0 (the "License"). You may not use | |
5 | * this file except in compliance with the License. You can obtain a copy | |
6 | * in the file LICENSE in the source distribution or at | |
7 | * https://www.openssl.org/source/license.html | |
8 | */ | |
9 | #ifndef OSSL_QUIC_REACTOR_H | |
10 | # define OSSL_QUIC_REACTOR_H | |
11 | ||
12 | # include "internal/time.h" | |
13 | # include "internal/sockets.h" | |
14 | # include <openssl/bio.h> | |
15 | ||
6292519c HL |
16 | # ifndef OPENSSL_NO_QUIC |
17 | ||
69523214 HL |
18 | /* |
19 | * Core I/O Reactor Framework | |
20 | * ========================== | |
21 | * | |
22 | * Manages use of async network I/O which the QUIC stack is built on. The core | |
23 | * mechanic looks like this: | |
24 | * | |
25 | * - There is a pollable FD for both the read and write side respectively. | |
26 | * Readability and writeability of these FDs respectively determines when | |
27 | * network I/O is available. | |
28 | * | |
29 | * - The reactor can export these FDs to the user, as well as flags indicating | |
30 | * whether the user should listen for readability, writeability, or neither. | |
31 | * | |
32 | * - The reactor can export a timeout indication to the user, indicating when | |
33 | * the reactor should be called (via libssl APIs) regardless of whether | |
34 | * the network socket has become ready. | |
35 | * | |
36 | * The reactor is based around a tick callback which is essentially the mutator | |
37 | * function. The mutator attempts to do whatever it can, attempting to perform | |
38 | * network I/O to the extent currently feasible. When done, the mutator returns | |
39 | * information to the reactor indicating when it should be woken up again: | |
40 | * | |
41 | * - Should it be woken up when network RX is possible? | |
42 | * - Should it be woken up when network TX is possible? | |
43 | * - Should it be woken up no later than some deadline X? | |
44 | * | |
45 | * The intention is that ALL I/O-related SSL_* functions with side effects (e.g. | |
46 | * SSL_read/SSL_write) consist of three phases: | |
47 | * | |
48 | * - Optionally mutate the QUIC machine's state. | |
49 | * - Optionally tick the QUIC reactor. | |
50 | * - Optionally mutate the QUIC machine's state. | |
51 | * | |
52 | * For example, SSL_write is a mutation (appending to a stream buffer) followed | |
53 | * by an optional tick (generally expected as we may want to send the data | |
54 | * immediately, though not strictly needed if transmission is being deferred due | |
55 | * to Nagle's algorithm, etc.). | |
56 | * | |
57 | * SSL_read is also a mutation and in principle does not need to tick the | |
58 | * reactor, but it generally will anyway to ensure that the reactor is regularly | |
59 | * ticked by an application which is only reading and not writing. | |
60 | * | |
61 | * If the SSL object is being used in blocking mode, SSL_read may need to block | |
62 | * if no data is available yet, and SSL_write may need to block if buffers | |
63 | * are full. | |
64 | * | |
65 | * The internals of the QUIC I/O engine always use asynchronous I/O. If the | |
66 | * application desires blocking semantics, we handle this by adding a blocking | |
67 | * adaptation layer on top of our internal asynchronous I/O API as exposed by | |
68 | * the reactor interface. | |
69 | */ | |
69523214 | 70 | typedef struct quic_tick_result_st { |
b639475a HL |
71 | char net_read_desired; |
72 | char net_write_desired; | |
69523214 HL |
73 | OSSL_TIME tick_deadline; |
74 | } QUIC_TICK_RESULT; | |
75 | ||
76 | typedef struct quic_reactor_st { | |
77 | /* | |
78 | * BIO poll descriptors which can be polled. poll_r is a poll descriptor | |
79 | * which becomes readable when the QUIC state machine can potentially do | |
80 | * work, and poll_w is a poll descriptor which becomes writable when the | |
81 | * QUIC state machine can potentially do work. Generally, either of these | |
82 | * conditions means that SSL_tick() should be called, or another SSL | |
83 | * function which implicitly calls SSL_tick() (e.g. SSL_read/SSL_write()). | |
84 | */ | |
85 | BIO_POLL_DESCRIPTOR poll_r, poll_w; | |
86 | OSSL_TIME tick_deadline; /* ossl_time_infinite() if none currently applicable */ | |
87 | ||
88 | void (*tick_cb)(QUIC_TICK_RESULT *res, void *arg); | |
89 | void *tick_cb_arg; | |
90 | ||
91 | /* | |
92 | * These are true if we would like to know when we can read or write from | |
93 | * the network respectively. | |
94 | */ | |
b639475a HL |
95 | unsigned int net_read_desired : 1; |
96 | unsigned int net_write_desired : 1; | |
69523214 HL |
97 | } QUIC_REACTOR; |
98 | ||
99 | void ossl_quic_reactor_init(QUIC_REACTOR *rtor, | |
100 | void (*tick_cb)(QUIC_TICK_RESULT *res, void *arg), | |
101 | void *tick_cb_arg, | |
102 | OSSL_TIME initial_tick_deadline); | |
103 | ||
104 | void ossl_quic_reactor_set_poll_r(QUIC_REACTOR *rtor, | |
105 | const BIO_POLL_DESCRIPTOR *r); | |
106 | ||
107 | void ossl_quic_reactor_set_poll_w(QUIC_REACTOR *rtor, | |
108 | const BIO_POLL_DESCRIPTOR *w); | |
109 | ||
110 | const BIO_POLL_DESCRIPTOR *ossl_quic_reactor_get_poll_r(QUIC_REACTOR *rtor); | |
111 | ||
112 | const BIO_POLL_DESCRIPTOR *ossl_quic_reactor_get_poll_w(QUIC_REACTOR *rtor); | |
113 | ||
b639475a | 114 | int ossl_quic_reactor_net_read_desired(QUIC_REACTOR *rtor); |
69523214 | 115 | |
b639475a | 116 | int ossl_quic_reactor_net_write_desired(QUIC_REACTOR *rtor); |
69523214 HL |
117 | |
118 | OSSL_TIME ossl_quic_reactor_get_tick_deadline(QUIC_REACTOR *rtor); | |
119 | ||
120 | /* | |
121 | * Do whatever work can be done, and as much work as can be done. This involves | |
122 | * e.g. seeing if we can read anything from the network (if we want to), seeing | |
123 | * if we can write anything to the network (if we want to), etc. | |
124 | */ | |
125 | int ossl_quic_reactor_tick(QUIC_REACTOR *rtor); | |
126 | ||
127 | /* | |
128 | * Blocking I/O Adaptation Layer | |
129 | * ============================= | |
130 | * | |
131 | * The blocking I/O adaptation layer implements blocking I/O on top of our | |
132 | * asynchronous core. | |
133 | * | |
134 | * The core mechanism is block_until_pred(), which does not return until pred() | |
135 | * returns a value other than 0. The blocker uses OS I/O synchronisation | |
136 | * primitives (e.g. poll(2)) and ticks the reactor until the predicate is | |
137 | * satisfied. The blocker is not required to call pred() more than once between | |
138 | * tick calls. | |
139 | * | |
140 | * When pred returns a non-zero value, that value is returned by this function. | |
141 | * This can be used to allow pred() to indicate error conditions and short | |
142 | * circuit the blocking process. | |
143 | * | |
144 | * A return value of -1 is reserved for network polling errors. Therefore this | |
145 | * return value should not be used by pred() if ambiguity is not desired. Note | |
146 | * that the predicate function can always arrange its own output mechanism, for | |
147 | * example by passing a structure of its own as the argument. | |
148 | * | |
149 | * If the SKIP_FIRST_TICK flag is set, the first call to reactor_tick() before | |
150 | * the first call to pred() is skipped. This is useful if it is known that | |
151 | * ticking the reactor again will not be useful (e.g. because it has already | |
152 | * been done). | |
153 | */ | |
154 | #define SKIP_FIRST_TICK (1U << 0) | |
155 | ||
156 | int ossl_quic_reactor_block_until_pred(QUIC_REACTOR *rtor, | |
157 | int (*pred)(void *arg), void *pred_arg, | |
158 | uint32_t flags); | |
159 | ||
160 | # endif | |
161 | ||
162 | #endif |