6.1.5 Thread safety

The GnuTLS library is thread safe by design, meaning that objects of the library such as TLS sessions, can be safely divided across threads as long as a single thread accesses a single object. This is sufficient to support a server which handles several sessions per thread. If, however, an object needs to be shared across threads then access must be protected with a mutex. Read-only access to objects, for example the credentials holding structures, is also thread-safe.

A gnutls_session_t object can be shared by two threads, one sending, the other receiving. In that case rehandshakes, if required, must only be handled by a single thread being active. The termination of a session should be handled, either by a single thread being active, or by the sender thread using gnutls_bye with GNUTLS_SHUT_WR and the receiving thread waiting for a return value of zero.

The random generator of the cryptographic back-end, utilizes mutex locks (e.g., pthreads on GNU/Linux and CriticalSection on Windows) which are setup by GnuTLS on library initialization. Prior to version 3.3.0 they were setup by calling gnutls_global_init. On special systems you could manually specify the locking system using the function gnutls_global_set_mutex before calling any other GnuTLS function. Setting mutexes manually is not recommended. An example of non-native thread usage is shown below.

#include <gnutls/gnutls.h>

int main()
{
   /* When the system mutexes are not to be used 
    * gnutls_global_set_mutex() must be called explicitly
    */
   gnutls_global_set_mutex (mutex_init, mutex_deinit, 
                            mutex_lock, mutex_unlock);
}

Function: void gnutls_global_set_mutex (mutex_init_func init, mutex_deinit_func deinit, mutex_lock_func lock, mutex_unlock_func unlock)

init: mutex initialization function

deinit: mutex deinitialization function

lock: mutex locking function

unlock: mutex unlocking function

With this function you are allowed to override the default mutex locks used in some parts of gnutls and dependent libraries. This function should be used if you have complete control of your program and libraries. Do not call this function from a library, or preferably from any application unless really needed to. GnuTLS will use the appropriate locks for the running system.

This function must be called prior to any other gnutls function.

Since: 2.12.0