Lines Matching +full:mode +full:- +full:based
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
18 also have the ability to operate in “blocking” mode.
20 - High performance applications (primarily server based) using existing libssl
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
42 QUIC-Related Requirements
43 -------------------------
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.
86 configured in blocking mode or not.
89 mode, this is not an advisable usage mode. If a socket is in blocking mode,
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
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
149 assisted mode. In environments where threading support is not available or
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
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
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
251 For example, while historically none of our own memory-based BIOs have
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
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,
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
295 sockets in blocking mode anyway.
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
305 over I/O than it actually is at present when using libssl in blocking mode.
307 - Feasible to implement and already working in tests.
310 - Does not rely on creating threads and can support blocking I/O at the
311 application level without relying on thread assisted mode.
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
320 than the current TLS stack, which cannot be used in blocking mode when used
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 --------------------------------
331 Based on the above evaluation, implementation has been undertaken using
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
443 reserved for application-defined use. The `value.custom` field of the
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
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
490 ### Configuration of Blocking vs. Non-Blocking Mode
492 Traditionally an SSL object has operated either in blocking mode or non-blocking
493 mode without requiring explicit configuration; if a socket returns EWOULDBLOCK
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.
499 blocking mode, so it is not possible to use the initial state of an underlying
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
512 configure a new QUIC connection accordingly. Blocking mode is chosen as the
515 solution. However, blocking mode cannot be supported with a non-pollable BIO,
516 and thus blocking mode defaults to off when used with such a BIO.
521 non-blocking; for a memory-based BIO it is a no-op; for `BIO_s_ssl` it is
526 When blocking mode is configured, the QUIC implementation will call
533 Blocking mode cannot be used with a non-pollable underlying BIO. If
535 read and write BIOs, blocking mode cannot be enabled and blocking mode defaults