doc: added more information on operation under multiple threads

Relates: #713

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 9831db2da4f7339c05e767cd5bc3f3679f8f40bc..21df8e5fb393385a84543c8659382b004ebb3308 100644 (file)
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -234,11 +234,21 @@ Read-only access to objects, for example the credentials holding structures,
 is also thread-safe. 
 
 A @code{gnutls_session_t} object could also be shared by two threads, one sending,
-the other receiving. In that case however, care must be taken during key
-updates and re-handshakes to be handled only by a single thread. The termination of a session 
-should be handled, either by a single thread being active, or by the sender thread 
-using @funcref{gnutls_bye} with @code{GNUTLS_SHUT_WR} and the receiving thread 
-waiting for a return value of zero.
+the other receiving. However, care must be taken on the following use cases:
+@itemize
+@item The re-handshake process in TLS 1.2 or earlier must be handled only in
+a single thread and no other thread may be performing any operation.
+@item The flag @code{GNUTLS_AUTO_REAUTH} cannot be used safely in this mode of operation.
+@item Any other operation which may send or receive data, like key update (c.f.,
+@funcref{gnutls_session_key_update}), must not be performed while threads
+are receiving or writing.
+@item The termination of a session should be handled, either by a single thread being
+active, or by the sender thread using @funcref{gnutls_bye} with @code{GNUTLS_SHUT_WR}
+and the receiving thread waiting for a return value of zero (or timeout on
+certain servers which do not respond).
+@item The functions @funcref{gnutls_transport_set_errno} and @funcref{gnutls_record_get_direction}
+should not be relied during parallel operation.
+@end itemize
 
 For several aspects of the library (e.g., the random generator, PKCS#11
 operations), the library may utilize mutex locks (e.g., pthreads on GNU/Linux and CriticalSection on Windows)

diff --git a/lib/state.c b/lib/state.c
index 540a83c7b800b99fa8b7ffb26737a11c66818ac5..f4ab818ca307c75be5fb62ac90f64a4acb3ecaa2 100644 (file)
--- a/lib/state.c
+++ b/lib/state.c
@@ -1058,7 +1058,7 @@ void
  * interrupted GnuTLS function.
  *
  * This function's output is unreliable if you are using the same
- * @session in different threads, for sending and receiving.
+ * @session in different threads for sending and receiving.
  *
  * Returns: 0 if interrupted while trying to read data, or 1 while trying to write data.
  **/

diff --git a/lib/system_override.c b/lib/system_override.c
index fdf766509ceee896d020997d9642971af21fd20a..3c4805bc56bfa08cc7d285021da6efd5684a958b 100644 (file)
--- a/lib/system_override.c
+++ b/lib/system_override.c
@@ -55,6 +55,9 @@
  * variable that is used by GnuTLS (e.g., the application is linked to
  * msvcr71.dll and gnutls is linked to msvcrt.dll).
  *
+ * This function is unreliable if you are using the same
+ * @session in different threads for sending and receiving.
+ *
  **/
 void gnutls_transport_set_errno(gnutls_session_t session, int err)
 {