diff options
author | Hugo Landau <hlandau@openssl.org> | 2023-05-18 13:07:00 +0100 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2023-05-29 08:51:12 +0200 |
commit | 041d48c9636478563b5dcd936c1fe816d1628732 (patch) | |
tree | a89069a7752f394461406e4e373f2f345c96ba9d | |
parent | 06fb6b97174ec8031de9b35203e35dee8f716365 (diff) |
QUIC: Rename SSL_tick etc. in man(7) docs
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20879)
-rw-r--r-- | doc/man7/openssl-quic.pod | 75 | ||||
-rw-r--r-- | 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<SSL_set_blocking_mode(3)> 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<SSL_read(3)> or -L<SSL_write(3)>), or the new function L<SSL_tick(3)>, regularly. If the SSL -object is used in blocking mode, an ongoing blocking call to an I/O function +L<SSL_write(3)>), or the new function L<SSL_handle_events(3)>, 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<SSL_read(3)> or L<SSL_write(3)> regularly. If an application does not do this, it should ensure -that L<SSL_tick(3)> is called regularly. +that L<SSL_handle_events(3)> is called regularly. -L<SSL_get_tick_timeout(3)> can be used to determine when L<SSL_tick(3)> must -next be called. +L<SSL_get_event_timeout(3)> can be used to determine when +L<SSL_handle_events(3)> must next be called. If the SSL object is being used with an underlying network BIO which is pollable (such as L<BIO_s_datagram(3)>), the application can use L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)> to obtain -resources which can be used to determine when L<SSL_tick(3)> should be called -due to network I/O. +resources which can be used to determine when L<SSL_handle_events(3)> 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<SSL_get_tick_timeout(3)> +=item L<SSL_get_event_timeout(3)> Determines when the QUIC implementation should next be woken up via a call to -L<SSL_tick(3)> (or another I/O function such as L<SSL_read(3)> or +L<SSL_handle_events(3)> (or another I/O function such as L<SSL_read(3)> or L<SSL_write(3)>), if ever. This can also be used with DTLS and supersedes L<DTLSv1_get_timeout(3)> for new usage. -=item L<SSL_tick(3)> +=item L<SSL_handle_events(3)> 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<SSL_read(3)> and L<SSL_write(3)> -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<DTLSv1_handle_timeout(3)> 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<SSL_get_rpoll_descriptor(3)> outputs an OS resource which can be used to synchronise on network readability events which should result in -a call to L<SSL_tick(3)>. L<SSL_get_wpoll_descriptor(3)> works in an analogous -fashion for the underlying network write BIO. +a call to L<SSL_handle_events(3)>. L<SSL_get_wpoll_descriptor(3)> works in an +analogous fashion for the underlying network write BIO. The poll descriptors provided by these functions need only be used when L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> return 1, respectively. @@ -770,7 +770,7 @@ synchronisation. It should call L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> 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<SSL_get_tick_timeout(3)> to determine if any timeout event will become +L<SSL_get_event_timeout(3)> to determine if any timeout event will become applicable in the future. =item @@ -791,11 +791,11 @@ The poll descriptor returned by L<SSL_get_wpoll_descriptor(3)> becomes writable =item -The timeout returned by L<SSL_get_tick_timeout(3)> (if any) expires. +The timeout returned by L<SSL_get_event_timeout(3)> (if any) expires. =back -Once any of these events occurs, L<SSL_tick(3)> should be called. +Once any of these events occurs, L<SSL_handle_events(3)> should be called. =back @@ -803,31 +803,32 @@ Once any of these events occurs, L<SSL_tick(3)> should be called. If the network read and write BIOs provided were not pollable (for example, in the case of L<BIO_s_dgram_pair(3)>), the application is responsible for managing -and synchronising network I/O. It should call L<SSL_tick(3)> after it writes -data to a L<BIO_s_dgram_pair(3)> or otherwise takes action so that the QUIC -implementation can read new datagrams via a call to L<BIO_recvmmsg(3)> on the -underlying network BIO. The QUIC implementation may output datagrams via a call -to L<BIO_sendmmsg(3)> and the application is responsible for ensuring these are -transmitted. - -The application must call L<SSL_get_tick_timeout(3)> after every call to -L<SSL_tick(3)> (or another I/O function on the SSL object), and ensure that a -call to L<SSL_tick(3)> is performed after the specified timeout (if any). +and synchronising network I/O. It should call L<SSL_handle_events(3)> after it +writes data to a L<BIO_s_dgram_pair(3)> or otherwise takes action so that the +QUIC implementation can read new datagrams via a call to L<BIO_recvmmsg(3)> on +the underlying network BIO. The QUIC implementation may output datagrams via a +call to L<BIO_sendmmsg(3)> and the application is responsible for ensuring these +are transmitted. + +The application must call L<SSL_get_event_timeout(3)> after every call to +L<SSL_handle_events(3)> (or another I/O function on the SSL object), and ensure +that a call to L<SSL_handle_events(3)> is performed after the specified timeout +(if any). =back =head1 SEE ALSO -L<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<SSL_net_read_desired(3)>, -L<SSL_net_write_desired(3)>, L<SSL_get_rpoll_descriptor(3)>, -L<SSL_get_wpoll_descriptor(3)>, L<SSL_set_blocking_mode(3)>, -L<SSL_shutdown_ex(3)>, L<SSL_set_initial_peer_addr(3)>, -L<SSL_stream_conclude(3)>, L<SSL_stream_reset(3)>, -L<SSL_get_stream_read_state(3)>, L<SSL_get_stream_read_error_code(3)>, -L<SSL_get_conn_close_info(3)>, L<SSL_get0_connection(3)>, -L<SSL_get_stream_type(3)>, L<SSL_get_stream_id(3)>, L<SSL_new_stream(3)>, -L<SSL_accept_stream(3)>, L<SSL_set_incoming_stream_policy(3)>, -L<SSL_set_default_stream_mode(3)> +L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>, +L<SSL_net_read_desired(3)>, L<SSL_net_write_desired(3)>, +L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>, +L<SSL_set_blocking_mode(3)>, L<SSL_shutdown_ex(3)>, +L<SSL_set_initial_peer_addr(3)>, L<SSL_stream_conclude(3)>, +L<SSL_stream_reset(3)>, L<SSL_get_stream_read_state(3)>, +L<SSL_get_stream_read_error_code(3)>, L<SSL_get_conn_close_info(3)>, +L<SSL_get0_connection(3)>, L<SSL_get_stream_type(3)>, L<SSL_get_stream_id(3)>, +L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>, +L<SSL_set_incoming_stream_policy(3)>, L<SSL_set_default_stream_mode(3)> =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)) |