From: Matt Caswell Date: Tue, 5 Sep 2023 14:17:29 +0000 (+0100) Subject: Expand the explanation of how to go and do useful work in non-blocking X-Git-Tag: openssl-3.2.0-alpha2~117 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=38c3c1dbefa8b8333e78e0d9d38fac7c4359f826;p=thirdparty%2Fopenssl.git Expand the explanation of how to go and do useful work in non-blocking Add additional commentary to the non-blocking examples explaining where to add code to go and do other useful work. Reviewed-by: Tomas Mraz Reviewed-by: Hugo Landau (Merged from https://github.com/openssl/openssl/pull/21950) --- diff --git a/demos/guide/quic-client-block.c b/demos/guide/quic-client-block.c index 3d5a56a8dfb..b63012829f1 100644 --- a/demos/guide/quic-client-block.c +++ b/demos/guide/quic-client-block.c @@ -47,7 +47,7 @@ static BIO *create_socket_bio(const char *hostname, const char *port, */ for (ai = res; ai != NULL; ai = BIO_ADDRINFO_next(ai)) { /* - * Create a TCP socket. We could equally use non-OpenSSL calls such + * Create a UDP socket. We could equally use non-OpenSSL calls such * as "socket" here for this and the subsequent connect and close * functions. But for portability reasons and also so that we get * errors on the OpenSSL stack in the event of a failure we use diff --git a/demos/guide/quic-client-non-block.c b/demos/guide/quic-client-non-block.c index 870dd1c4fe6..be4c9b19676 100644 --- a/demos/guide/quic-client-non-block.c +++ b/demos/guide/quic-client-non-block.c @@ -48,7 +48,7 @@ static BIO *create_socket_bio(const char *hostname, const char *port, */ for (ai = res; ai != NULL; ai = BIO_ADDRINFO_next(ai)) { /* - * Create a TCP socket. We could equally use non-OpenSSL calls such + * Create a UDP socket. We could equally use non-OpenSSL calls such * as "socket" here for this and the subsequent connect and close * functions. But for portability reasons and also so that we get * errors on the OpenSSL stack in the event of a failure we use @@ -139,8 +139,21 @@ static void wait_for_activity(SSL *ssl) /* * Wait until the socket is writeable or readable. We use select here * for the sake of simplicity and portability, but you could equally use - * poll/epoll or similar functions. If we have a timeout we use it to - * ensure that OpenSSL is called when it wants to be. + * poll/epoll or similar functions + * + * NOTE: For the purposes of this demonstration code this effectively + * makes this demo block until it has something more useful to do. In a + * real application you probably want to go and do other work here (e.g. + * update a GUI, or service other connections). + * + * Let's say for example that you want to update the progress counter on + * a GUI every 100ms. One way to do that would be to use the timeout in + * the last parameter to "select" below. If the tvp value is greater + * than 100ms then use 100ms instead. Then, when select returns, you + * check if it did so because of activity on the file descriptors or + * because of the timeout. If the 100ms GUI timeout has expired but the + * tvp timeout has not then go and update the GUI and then restart the + * "select" (with updated timeouts). */ select(width, &rfds, &wfds, NULL, tvp); diff --git a/demos/guide/tls-client-non-block.c b/demos/guide/tls-client-non-block.c index 05db0f529e6..dc6ee4dce89 100644 --- a/demos/guide/tls-client-non-block.c +++ b/demos/guide/tls-client-non-block.c @@ -111,9 +111,21 @@ static void wait_for_activity(SSL *ssl, int write) width = sock + 1; /* - * Wait until the socket is writeable or readable. We use select here for - * the sake of simplicity and portability, but you could equally use + * Wait until the socket is writeable or readable. We use select here + * for the sake of simplicity and portability, but you could equally use * poll/epoll or similar functions + * + * NOTE: For the purposes of this demonstration code this effectively + * makes this demo block until it has something more useful to do. In a + * real application you probably want to go and do other work here (e.g. + * update a GUI, or service other connections). + * + * Let's say for example that you want to update the progress counter on + * a GUI every 100ms. One way to do that would be to add a 100ms timeout + * in the last parameter to "select" below. Then, when select returns, + * you check if it did so because of activity on the file descriptors or + * because of the timeout. If it is due to the timeout then update the + * GUI and then restart the "select". */ if (write) select(width, NULL, &fds, NULL, NULL); diff --git a/doc/man7/ossl-guide-quic-client-non-block.pod b/doc/man7/ossl-guide-quic-client-non-block.pod index b015a6fbf1d..8187bb9b77d 100644 --- a/doc/man7/ossl-guide-quic-client-non-block.pod +++ b/doc/man7/ossl-guide-quic-client-non-block.pod @@ -103,8 +103,21 @@ function C. /* * Wait until the socket is writeable or readable. We use select here * for the sake of simplicity and portability, but you could equally use - * poll/epoll or similar functions. If we have a timeout we use it to - * ensure that OpenSSL is called when it wants to be. + * poll/epoll or similar functions + * + * NOTE: For the purposes of this demonstration code this effectively + * makes this demo block until it has something more useful to do. In a + * real application you probably want to go and do other work here (e.g. + * update a GUI, or service other connections). + * + * Let's say for example that you want to update the progress counter on + * a GUI every 100ms. One way to do that would be to use the timeout in + * the last parameter to "select" below. If the tvp value is greater + * than 100ms then use 100ms instead. Then, when select returns, you + * check if it did so because of activity on the file descriptors or + * because of the timeout. If the 100ms GUI timeout has expired but the + * tvp timeout has not then go and update the GUI and then restart the + * "select" (with updated timeouts). */ select(width, &rfds, &wfds, NULL, tvp); @@ -389,7 +402,7 @@ finished with it. Even though we have received EOF on the stream that we were reading from above, this tell us nothing about the state of the underlying connection. Our demo -applicaiton will initiate the connection shutdown process via +application will initiate the connection shutdown process via L. Since our application is initiating the shutdown then we might expect to see diff --git a/doc/man7/ossl-guide-tls-client-non-block.pod b/doc/man7/ossl-guide-tls-client-non-block.pod index 8f31ac69fbf..ea5e40bd1ca 100644 --- a/doc/man7/ossl-guide-tls-client-non-block.pod +++ b/doc/man7/ossl-guide-tls-client-non-block.pod @@ -99,9 +99,21 @@ the underlying socket has become readable or writeable when it wasn't before. width = sock + 1; /* - * Wait until the socket is writeable or readable. We use select here for - * the sake of simplicity and portability, but you could equally use + * Wait until the socket is writeable or readable. We use select here + * for the sake of simplicity and portability, but you could equally use * poll/epoll or similar functions + * + * NOTE: For the purposes of this demonstration code this effectively + * makes this demo block until it has something more useful to do. In a + * real application you probably want to go and do other work here (e.g. + * update a GUI, or service other connections). + * + * Let's say for example that you want to update the progress counter on + * a GUI every 100ms. One way to do that would be to add a 100ms timeout + * in the last parameter to "select" below. Then, when select returns, + * you check if it did so because of activity on the file descriptors or + * because of the timeout. If it is due to the timeout then update the + * GUI and then restart the "select". */ if (write) select(width, NULL, &fds, NULL, NULL); @@ -116,7 +128,7 @@ the underlying socket(s) to become readable/writeable before returning. It also supports a "timeout" (as do most other similar functions) so in your own applications you can make use of this to periodically wake up and perform work while waiting for the socket state to change. But we don't use that timeout -capability in this example. +capability in this example for the sake of simplicity. =head2 Handling errors from OpenSSL I/O functions