doc: updated async operation text

1 files changed, 30 insertions, 15 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index c15d7f382b..e6b60618f3 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -739,6 +739,7 @@ remaining until the next retransmission, or better the time until
 
 @node Asynchronous operation
 @subsection Asynchronous operation
+
 @acronym{GnuTLS} can be used with asynchronous socket or event-driven programming.
 The approach is similar to using Berkeley sockets under such an environment.
 The blocking, due to network interaction, calls such as
@@ -755,18 +756,34 @@ The only exception is @funcref{gnutls_record_send},
 which if interrupted subsequent calls need not to include the data to be
 sent (can be called with NULL argument).
 
-The @funcintref{select} system call can also be used in combination with the
-@acronym{GnuTLS} functions. @funcintref{select} allows monitoring of sockets
-and notifies on them being ready for reading or writing data. Note however
-that this system call cannot notify on data present in @acronym{GnuTLS}
-read buffers, it is only applicable to the kernel sockets API. Thus if
-you are using it for reading from a @acronym{GnuTLS} session, make sure
-that any cached data are read completely. That can be achieved by checking there 
-are no data waiting to be read (using @funcref{gnutls_record_check_pending}), 
+When using the @funcintref{select} system call though, one should remember
+that it is only applicable to the kernel sockets API. To check for any
+available buffers in a @acronym{GnuTLS} session, 
+utilize @funcref{gnutls_record_check_pending},
 either before the @funcintref{select} system call, or after a call to
 @funcref{gnutls_record_recv}. @acronym{GnuTLS} does not keep a write buffer,
 thus when writing no additional actions are required.
 
+The following paragraphs describe the detailed requirements for non-blocking
+operation when using the TLS or DTLS protocols.
+
+@subsubsection TLS protocol
+There are no special requirements for the TLS protocol operation in non-blocking
+mode if a non-blocking socket is used.
+
+It is recommended, however, for future compatibility, when in non-blocking mode, to
+call the @funcref{gnutls_init} function with the
+@code{GNUTLS_NONBLOCK} flag set (see @ref{Session initialization}).
+
+@subsubsection Datagram TLS protocol
+When in non-blocking mode the function, the @funcref{gnutls_init} function 
+must be called with the @code{GNUTLS_NONBLOCK} flag set (see @ref{Session initialization}). 
+
+In constrast with the TLS protocol, the pull timeout function is required,
+but will only be called with a timeout of zero. In that case it should indicate
+whether there are data to be received or not. When not using the default pull function,
+then @funcref{gnutls_transport_set_pull_timeout_function} should be called.
+
 Although in the TLS protocol implementation each call to receive or send
 function implies to restoring the same function that was interrupted, in
 the DTLS protocol this requirement isn't true.
@@ -775,13 +792,11 @@ a received message and thus @funcref{gnutls_record_get_direction} must be called
 to decide which direction to check prior to restoring a function call.
 @showfuncdesc{gnutls_record_get_direction}
 
-Moreover, to prevent blocking from DTLS' retransmission timers to block a
-handshake, the @funcref{gnutls_init} function should be called with the
-@code{GNUTLS_NONBLOCK} flag set (see @ref{Session initialization}). In that
-case, in order to be able to use the DTLS handshake timers, the function
-@funcref{gnutls_dtls_get_timeout} should be used to estimate when to call
-@funcref{gnutls_handshake} if no packets have been received.
-
+When calling @funcref{gnutls_handshake} through a multi-plexer,
+to be able to handle properly the DTLS handshake retransmission timers,
+the function @funcref{gnutls_dtls_get_timeout}
+should be used to estimate when to call @funcref{gnutls_handshake} if
+no data have been received.
 
 @node DTLS sessions
 @subsection DTLS sessions