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 <tomas@openssl.org>
Reviewed-by: Hugo Landau <hlandau@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21950)

2 files changed, 31 insertions, 6 deletions

diff --git a/doc/man7/ossl-guide-quic-client-non-block.pod b/doc/man7/ossl-guide-quic-client-non-block.pod
index b015a6fbf1..8187bb9b77 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_for_activity()>.
         /*
          * 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<SSL_shutdown(3)>.
 
 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 8f31ac69fb..ea5e40bd1c 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