Lines Matching full:an
41 An application can create multiple QLSOs (see the [server API design
43 pair. Therefore an application needs to be able to poll:
57 - There are a large number of event types an application might want to poll on.
67 able for an application to request wakeup on the first of an arbitrary subset
76 - **Support external polling.** An application must be able to be in control
123 quoting an incorrect FD in the reported events, unless a process takes care to
127 to add a new FD registration and modify an existing FD registration, when
128 most of the time what is desired is an “upsert” (update or insert) call. Thus
129 callers have to track whether an FD has already been added or not.
136 are polling for such an event, only one of these threads should be woken up.
149 An application has two QCSOs open each with one QSSO. The QCSOs and QSSOs might
163 An application has two QCSOs open each with one QSSO, all in non-blocking mode.
171 - An application collects file descriptors and event flags to poll from our QUIC
177 - An application does its own polling and timeout handling.
179 - An application calls `SSL_handle_events` if the polling process indicated
180 an event for either of the QUIC poll descriptors or the QUIC event handling
181 timeout has expired. The call need be made only on an Event Leader but can
184 - An application calls `SSL_poll` similarly to the above example, but with
189 This demonstrates the principle of hierarchical polling, whereby an application
196 - An application must be able to use our polling interface without blocking and
203 notion of poll descriptors is used to provide an abstraction over arbitrary
211 To date, `BIO_POLL_DESCRIPTOR` structures have been used to contain an OS socket
251 for example due to a permanent error on an underlying network BIO.
283 - It is important to provide an adequate granularity of event types so as to
284 ensure an application can avoid wakeups it doesn't want.
375 an underlying network BIO encounters a permanent error.
391 A. An application which is not immediately concerned by the failure of an
392 individual connection likely still needs to be notified if an entire port fails.
409 application, thus there is no valid need for an application to poll on it.
418 A. Idle timeout is an immediate transition to `TERMINATED` as per the channel
429 **Q. Does it make sense for an application to be able to mask this?**
434 **Q. Does it make sense for an application to be able to listen for this but not
437 A. Yes, since `EL` implies `EC`, it is valid for an application to handle
503 A. If an application receives an `R` event, this means more application data is
508 If a stream reset is triggered by a peer, this needs to be notifiable to an
518 A. This would enable an application to listen for more application data but not
531 and has no `RESET_STREAM` transition. Moreover, after an application is done
609 A. Probably not, since shutdown is under local application control and so if an
615 A. It is useful for an application to be able to determine if something odd has
619 protocol-defined semantics, it is important an application can be notified of
624 A. This would enable an application to listen for the opportunity to write but
663 to initiate an outgoing bidirectional or unidirectional stream.
708 specifying an unsupported `BIO_POLL_DESCRIPTOR` type, or an unsupported `SSL`
710 from an exception condition on a successfully polled resource (e.g. `ER`, `EW`,
719 **Q. What happens if an `F` event is raised?**
737 - Sketch A: An “immediate-mode” poller interface similar to poll(2).
781 * on an item. This may or may not also include events which were not requested
784 * Specifying an item with an events field of zero is a no-op; the array entry
789 * BIO_POLL_DESCRIPTOR is an extensible tagged union structure which describes
830 * If timeout is NULL or non-zero, specifying this flag is an error.
835 * with the total number of items having an revents field, which,
841 * polled (such as a connection being terminated) and an failure in the polling
844 * the polling mechanism itself fails (for example, because an unsupported
855 * The initial value of an revents field when this function is called is of no
859 * an API which requires advanced registration of pollables.
881 there is no way for an event to be efficiently distributed to just one of
887 an API which does not provide significant impedance discontinuities to
893 Alternatively, an API which requires advance registration of pollable objects is
899 distribution of work to threads by auto-disabling an event mask bit after
910 - Addition of registered events and mutation of existing events uses an
918 * The means of obtaining an SSL_POLL_GROUP instance is discussed
958 /* An opaque application value passed through in any reported event. */
1009 * If timeout is NULL, this function blocks forever until an applicable event
1019 * desired to provide an event array to allow errors when processing changes
1034 * An error may occur when processing a change. If this occurs, an entry
1035 * describing the error is written out as an event to the event array. The
1040 * When an event is output from this function, desc is set to the original
1047 * An event structure which represents a change processing error will have the
1053 * instance). Changing an existing event is done by passing a change structure
1059 * To unregister an event, pass a matching poll descriptor and instance value
1063 * before freeing the underlying resource. If an object which is registered
1065 * descriptor used. For example, libssl has no safe way to detect if an OS
1072 * this, applications must still ensure no events in an SSL_POLL_EVENT
1204 /* Wait for an incoming stream or conn error on conn 1 and 2. */
1218 /* Wait for an incoming connection. */
1223 /* Also poll on an ordinary OS socket. */
1228 /* Immediately register all of these events and wait for an event. */
1355 It is also desirable to support custom poller methods provided by an
1356 application. This allows an application to support custom poll descriptor types
1357 and provide a way to poll on those poll descriptors. For example, an application
1370 the OS. Since an OS only knows how to block on resources it issues, this means
1375 two QSSOs on that QCSO, and an OS socket handle:
1388 - The resulting set of poll descriptors is then passed on to an underlying
1390 also be a custom method provided by an application if one of the SSL objects
1410 - Internal polling for blocking API: This is where an SSL object automatically
1411 polls internally to support blocking API operation. If an underlying network
1414 is an OS socket handle, or if a custom poller is configured that knows how to
1417 - External polling support: This is where an application calls a polling API.
1493 Here is how an application might define and create a `SSL_POLL_METHOD` instance
1570 To support custom pollers for internal polling, SSL objects receive an API that
1572 only be configured on an event leader, but the getter function will return the
1573 custom poller configured on an event leader when called on any QUIC SSL object
1576 An `SSL_POLL_METHOD` can be associated with an SSL object. It can also be set
1588 An SSL object created from a `SSL_CTX` which has never had
1613 An application can also use an `SSL_POLL_METHOD` itself, whether via the
1619 of implementation-specific polling data. For example, suppose an application
1622 an SSL object can be cached.
1629 to switch to an internal thread-based reactor design, and signal readiness not
1630 via an OS socket handle but via a condition variable or Linux-style `eventfd`.
1637 variable and other resources, so there are issues here unless an additional
1641 type. A QUIC SSL object simply starts returning an eventfd fd for
1702 an OS device for fast polling (e.g. epoll) and register these resources
1726 here is that an SSL object registered into a poll group can be automatically
1741 * Either the read or write network BIO on an SSL object has just been changed,
1743 * If a BIO reference is being set to NULL on an SSL object, the 'new' pointer
1744 * will be NULL; conversely, if a BIO is being set on an SSL object where
1762 /* Returns an SSL object associated with the event (if applicable) */
1775 * registered. *cookie is written with an opaque value which may be used to
1798 internal blocking code, so this should also work OK. Remember that an external
1799 poller method does not interact with an internal poller method (i.e., a method
1800 set on an SSL object). In particular, no two poller methods ever interact
1807 A. We assume an application uses its own polling arrangements initially and then
1808 uses calls to an OpenSSL external polling API (such as `SSL_poll` or a poll
1810 no issue here. An application can also use OpenSSL polling APIs instead of its
1824 A. Using an extensible function table. An application can set a function
1828 **Q. If an application sets a poll method on both an event leader and a poll
1831 A. Setting a poll method on an event leader provides a mechanism used for internal
1844 (QUIC domains) and an application then tries to poll them all?**
1846 A. Because the poll method configured on an event leader is ignored in favour of
1856 A. It uses the default poll method. If an application wishes to use a different
1859 **Q. An application creates a poll group, registers an SSL object and later
1865 - An application is not allowed to have the poll descriptors returned by a BIO
1878 This might cause issues with epoll because we don't have an opportunity
1879 to deregister an FD in this case.
1883 **Q. An application creates a poll group, registers a QCSO and some subsidiary
1887 A. We must assume a poll group retains an SSL object pointer if such an object
1898 **Q. An application creates a poll group, registers a (non-QUIC-related) OS
1902 is not really possible to handle this automatically. It is essential that an
1915 is largely because Windows chose an approach based around I/O *completion*
1916 notification rather than around I/O *readiness* notification. While an implementation
1921 has proven impossible in practice to create an I/O readiness API as an
1923 fairly easy to create an I/O completion notification API over an I/O readiness
1947 5. `IOCTL_AFD_POLL`. This is an undocumented function of Winsock internals
1953 notifications to an IOCP, so this can be quite performant.
1955 `IOCTL_AFD_POLL` is an internal, undocumented API. It is however widely used,
1968 An immediate mode interface can be implemented using option 1.
1972 option 5 being the preferred approach for projects wanting an epoll/kqueue-style
1988 Sometimes an application knows it does not need to do anything until at least N
1994 an individual QUIC stream:
2017 example, an application might want to perform a blocking read from a peer but
2038 * starts whenever an operation is commenced.
2058 * example if called on an unsupported SSL object type).
2065 * Returns 1 if the last invocation of an applicable operation specified by
2088 There are no compatibility issues here because it will only be returned if an
2097 We automatically engage in event handling when an I/O function such as
2108 * single future call to an operation of that type (INHIBIT_ONCE), after which