From 041d48c9636478563b5dcd936c1fe816d1628732 Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Thu, 18 May 2023 13:07:00 +0100 Subject: QUIC: Rename SSL_tick etc. in man(7) docs Reviewed-by: Matt Caswell Reviewed-by: Tim Hudson Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/20879) --- doc/man7/openssl-quic.pod | 75 ++++++++++++++++++++++++----------------------- test/quic_newcid_test.c | 2 +- 2 files changed, 39 insertions(+), 38 deletions(-) diff --git a/doc/man7/openssl-quic.pod b/doc/man7/openssl-quic.pod index c1d3be431d..6f3ee00f4e 100644 --- a/doc/man7/openssl-quic.pod +++ b/doc/man7/openssl-quic.pod @@ -401,23 +401,23 @@ it must add a call to L to disable blocking mode. If your application does not choose to use thread assisted mode, it must ensure that it calls an I/O function on the SSL object (for example, L or -L), or the new function L, regularly. If the SSL -object is used in blocking mode, an ongoing blocking call to an I/O function +L), or the new function L, regularly. If the +SSL object is used in blocking mode, an ongoing blocking call to an I/O function satisfies this requirement. This is required to ensure that timer events required by QUIC are handled in a timely fashion. Most applications will service the SSL object by calling L or L regularly. If an application does not do this, it should ensure -that L is called regularly. +that L is called regularly. -L can be used to determine when L must -next be called. +L can be used to determine when +L must next be called. If the SSL object is being used with an underlying network BIO which is pollable (such as L), the application can use L, L to obtain -resources which can be used to determine when L should be called -due to network I/O. +resources which can be used to determine when L should be +called due to network I/O. Applications which use thread assisted mode do not need to be concerned with this requirement, as the QUIC implementation ensures timeout events @@ -494,24 +494,24 @@ The following SSL APIs are new but relevant to both QUIC and DTLS: =over 4 -=item L +=item L Determines when the QUIC implementation should next be woken up via a call to -L (or another I/O function such as L or +L (or another I/O function such as L or L), if ever. This can also be used with DTLS and supersedes L for new usage. -=item L +=item L This is a non-specific I/O operation which makes a best effort attempt to perform any pending I/O or timeout processing. It can be used to advance the QUIC state machine by processing incoming network traffic, generating outgoing network traffic and handling any expired timeout events. Most other I/O functions on an SSL object, such as L and L -implicitly perform ticking of the SSL object, so calling this function is only -needed if no other I/O function is to be called. +implicitly perform event handling on the SSL object, so calling this function is +only needed if no other I/O function is to be called. This can also be used with DTLS and supersedes L for new usage. @@ -535,8 +535,8 @@ These functions facilitate operation in nonblocking mode. When an SSL object is being used with an underlying network read BIO which supports polling, L outputs an OS resource which can be used to synchronise on network readability events which should result in -a call to L. L works in an analogous -fashion for the underlying network write BIO. +a call to L. L works in an +analogous fashion for the underlying network write BIO. The poll descriptors provided by these functions need only be used when L and L return 1, respectively. @@ -770,7 +770,7 @@ synchronisation. It should call L and L to determine whether the QUIC implementation is currently interested in readability and writability events on the underlying network BIO which was provided, and call -L to determine if any timeout event will become +L to determine if any timeout event will become applicable in the future. =item @@ -791,11 +791,11 @@ The poll descriptor returned by L becomes writable =item -The timeout returned by L (if any) expires. +The timeout returned by L (if any) expires. =back -Once any of these events occurs, L should be called. +Once any of these events occurs, L should be called. =back @@ -803,31 +803,32 @@ Once any of these events occurs, L should be called. If the network read and write BIOs provided were not pollable (for example, in the case of L), the application is responsible for managing -and synchronising network I/O. It should call L after it writes -data to a L or otherwise takes action so that the QUIC -implementation can read new datagrams via a call to L on the -underlying network BIO. The QUIC implementation may output datagrams via a call -to L and the application is responsible for ensuring these are -transmitted. - -The application must call L after every call to -L (or another I/O function on the SSL object), and ensure that a -call to L is performed after the specified timeout (if any). +and synchronising network I/O. It should call L after it +writes data to a L or otherwise takes action so that the +QUIC implementation can read new datagrams via a call to L on +the underlying network BIO. The QUIC implementation may output datagrams via a +call to L and the application is responsible for ensuring these +are transmitted. + +The application must call L after every call to +L (or another I/O function on the SSL object), and ensure +that a call to L is performed after the specified timeout +(if any). =back =head1 SEE ALSO -L, L, L, -L, L, -L, L, -L, L, -L, L, -L, L, -L, L, -L, L, L, -L, L, -L +L, L, +L, L, +L, L, +L, L, +L, L, +L, L, +L, L, +L, L, L, +L, L, +L, L =head1 COPYRIGHT diff --git a/test/quic_newcid_test.c b/test/quic_newcid_test.c index 2044209ebb..127439ff2a 100644 --- a/test/quic_newcid_test.c +++ b/test/quic_newcid_test.c @@ -112,7 +112,7 @@ static int test_ncid_frame(int fail) goto err; ossl_quic_tserver_tick(qtserv); - if (!TEST_true(SSL_tick(cssl))) + if (!TEST_true(SSL_handle_events(cssl))) goto err; if (!TEST_int_eq(SSL_read(cssl, buf, sizeof(buf)), msglen)) -- cgit v1.2.3