Lines Matching +full:full +full:- +full:custom
11 ----------
13 The [requirements for QUIC](./quic-requirements.md) which have formed the basis
16 - The application must have the ability to be in control of the event loop
20 - High performance applications (primarily server based) using existing libssl
21 APIs; using custom network interaction BIOs in order to get the best
23 handling, using fibres). Would prefer to use the existing APIs - they don’t
30 - We want to support both blocking and non-blocking semantics
33 - In the case of non-blocking applications, it must be possible
37 - We want to support custom BIOs on the network side and to the extent
38 feasible, minimise the level of adaptation needed for any custom BIOs already
42 QUIC-Related Requirements
43 -------------------------
48 over TCP. This will require applications using custom BIOs on the network side
49 to make substantial changes to the implementation of those custom BIOs to model
60 vs. non-blocking I/O in the interface between the QUIC implementation and an
63 libssl, which will support both blocking and non-blocking I/O.
65 Blocking vs. Non-Blocking Modes in Underlying Network BIOs
66 ----------------------------------------------------------
68 The above constraints make it effectively a requirement that non-blocking I/O be
77 - The underlying network write BIO becomes writeable;
78 - The underlying network read BIO becomes readable;
79 - A timeout expires.
99 - It is quite likely that there are buggy OSes out there which perform spurious
102 - The fact that a socket is writeable does not necessarily mean that a datagram
106 - This usage pattern precludes multithreaded use barring some locking scheme
109 multi-threaded network I/O on the backend.
114 have a BIO interface which provides for select(3)-like functionality or which
118 guarantee (under a non-buggy OS) that a single syscall will not block, however
123 violating the BIO abstraction layer, and would not work with custom BIOs (even
131 - a thread which exists solely to execute blocking calls to the `BIO_write` of
133 - a thread which exists solely to execute blocking calls to the `BIO_read` of an
135 - a thread which exists solely to wait for and dispatch timeout events.
140 The premise here is that the front-end I/O API (`SSL_read`, `SSL_write`, etc.)
146 - There is a hard requirement for threading functionality in order to be
150 desired, our APIs would only be usable in a non-blocking fashion.
152 - Several threads are spawned which the application is not in control of.
161 - By blocking in `BIO_write` calls, this precludes correct implementation of
169 aligns optimally to non-blocking I/O and which cannot be accommodated
172 - Since existing custom BIOs will not be expecting concurrent `BIO_read` and
174 likely to require substantial rework of those custom BIOs (trivial locking of
180 - The question is posed of how to handle connection teardown, which does not
191 returns. This obviously is a highly application-visible change (and is likely
192 to be far more disruptive than configuring the socket into non-blocking mode).
194 Moreover, it is not workable anyway because it only works for a socket-based
200 using custom BIOs, this is likely to require substantial rework of those BIOs.
203 accommodating applications using custom network BIOs in a blocking mode, these
206 applications implementing their own custom BIOs will do so in a blocking mode.
208 ### Use of non-blocking I/O
210 By comparison, use of non-blocking I/O and select(3) or similar APIs on the
222 either blocking or non-blocking semantics to the application, based on what the
226 non-blocking mode. Though some OSes support a `MSG_DONTWAIT` flag which allows a
227 single I/O operation to be made non-blocking, not all OSes support this (e.g.
229 socket FD we use into non-blocking mode.
231 Of the approaches outlined in this document, the use of non-blocking I/O has the
236 - We rely on having a select(3) or poll(3) like function available from the
241 - Firstly, we already rely on select(3) in our code, at least in
242 non-`no-sock` builds, so this does not appear to raise any portability
245 - Secondly, we have the option of providing a custom poller interface which
247 select(3)-like function. In fact, this has the potential to be quite
249 BIOs, and therefore perform blocking I/O on top of any custom BIO.
251 For example, while historically none of our own memory-based BIOs have
253 wished choose to implement a custom blocking memory BIO and implement a
254 custom poller which synchronises using a custom poll descriptor based
261 build blocking semantics out of a non-blocking QUIC instance; this is not
262 particularly difficult, though providing custom pollers here would mean
265 - Configuring a socket into non-blocking mode might confuse an application.
269 - Applications will already have to make changes to any network-side BIOs,
271 BIO pair to a `BIO_s_dgram_pair`. Custom BIOs will need to be
279 - In order for an application to be confused by us putting a socket into
280 non-blocking mode, it would need to be trying to use the socket in some
286 - There are some circumstances where an application might want to multiplex
297 - The poll descriptor interface adds complexity to the BIO interface.
301 - An application retains full control of its event loop in non-blocking mode.
303 When using libssl in application-level blocking mode, via a custom poller
307 - Feasible to implement and already working in tests.
310 - Does not rely on creating threads and can support blocking I/O at the
313 - Does not require an application-provided network-side custom BIO to be
316 - The poll descriptor interface will allow applications to implement custom
318 blocking application-level I/O on top of a on a custom memory-based BIO
321 with a memory-based BIO.
323 - Allows performance-optimal implementation of QUIC RFC requirements.
325 - Ensures our internal I/O architecture remains flexible for future evolution
328 Use of Internal Non-Blocking I/O
329 --------------------------------
332 non-blocking I/O internally. Applications can use blocking or non-blocking I/O
333 at the libssl API level. Network-level BIOs must operate in a non-blocking mode
336 
343 must be reconciled with the desire to support application-managed event loops.
346 application event loop in application-level non-blocking mode by exposing an
347 appropriate OS-level synchronisation primitive to the application. On \*NIX
350 - An FD which should be polled for readability, writability, or both; and
351 - A deadline (if any is currently applicable).
361 - The read-pollable FD is the FD of the read BIO.
362 - The write-pollable FD is the FD of the write BIO.
364 However, things become more complex when we are dealing with memory-based BIOs
367 application-provided custom BIO.
369 ### Pollable and Non-Pollable BIOs
372 pollable and non-pollable BIOs.
374 - A pollable BIO is a BIO which can provide some kind of OS-level
378 - A non-pollable BIO has no naturally associated OS-level synchronisation
384 “OS-level synchronisation primitive” is deliberately vague. Most modern OSes use
394 WinSock-specific `select()` call must be used. On the other hand, other kinds of
402 A BIO object will provide methods to retrieve a pollable OS-level
424 } custom[BIO_POLL_DESCRIPTOR_NUM_CUSTOM];
443 reserved for application-defined use. The `value.custom` field of the
447 libssl will not know how to poll custom poll descriptors itself, thus these are
448 only useful when the application will provide a custom poller function, which
450 custom poll descriptors.
456 just yield the socket's FD. For memory-based BIOs, see below.
458 #### Supporting Non-Pollable BIOs
460 Where we are provided with a non-pollable BIO, we cannot provide the application
466 fails, indicating that a non-pollable BIO is being used. Thus, if an application
471 - The QUIC implementation wants to write data to the network but
472 is currently unable to (e.g. `BIO_s_dgram_pair` is full).
479 - The QUIC implementation wants to read data from the network
485 It is worth noting that theoretically a memory-based BIO could be implemented
487 implement a custom BIO, custom poll descriptor and custom poller to facilitate
490 ### Configuration of Blocking vs. Non-Blocking Mode
492 Traditionally an SSL object has operated either in blocking mode or non-blocking
495 no issue. Since the QUIC implementation is building on non-blocking I/O, this
496 implicit configuration of non-blocking mode is not feasible.
500 socket to determine if the application wants to use non-blocking I/O or not.
504 non-blocking mode:
511 Applications desiring non-blocking operation will need to call this API to
515 solution. However, blocking mode cannot be supported with a non-pollable BIO,
521 non-blocking; for a memory-based BIO it is a no-op; for `BIO_s_ssl` it is
528 function (e.g. `select()`) or, if configured, custom poller function, to block.
533 Blocking mode cannot be used with a non-pollable underlying BIO. If