From 7c34680c910089bf6d102664d767940d0ceeca64 Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Sun, 10 Apr 2011 14:12:41 +0200 Subject: documentation updates. --- doc/cha-library.texi | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) (limited to 'doc/cha-library.texi') diff --git a/doc/cha-library.texi b/doc/cha-library.texi index 6c783bef2f..7618c4208e 100644 --- a/doc/cha-library.texi +++ b/doc/cha-library.texi @@ -62,6 +62,7 @@ small library, with the required features, can be generated. * General Idea:: * Error handling:: * Memory handling:: +* Thread safety:: * Callback functions:: @end menu @@ -153,6 +154,46 @@ used in cases where even the system's swap memory is not considered secure. See the documentation of @acronym{Libgcrypt} for more information. +@node Thread safety +@section Thread safety + +Although the @acronym{GnuTLS} library is thread safe by design, some +parts of the cryptographic backend, such as the random generator, are not. +Applications can either call @ref{gnutls_global_init} which will use the default +operating system provided locks (i.e. @code{pthreads} on GNU/Linux and +@code{CriticalSection} on Windows), or specify manualy the locking system using +the function @ref{gnutls_global_set_mutex} before calling @ref{gnutls_global_init}. +Setting manually mutexes is recommended +only to applications that have full control of the underlying libraries. If this +is not the case, the use of the operating system defaults is suggested. + + +There are helper macros to help you properly initialize the libraries. +Examples are shown below. + +@itemize + +@item Native threads +@example +#include + +int main() +@{ + gnutls_global_init(); +@} +@end example + +@item Other thread packages +@example + +int main() +@{ + gnutls_global_mutex_set (mutex_init, mutex_deinit, mutex_lock, mutex_unlock); + gnutls_global_init(); +@} +@end example +@end itemize + @node Callback functions @section Callback Functions @cindex Callback functions -- cgit v1.2.1