updated documentation on library initialization to reflex the changes in 3.3.0.

1 files changed, 19 insertions, 31 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 9c5bb12a21..34c7cf00db 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -171,16 +171,13 @@ 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. 
 
-The random generator of the cryptographic back-end, is not thread safe and requires
-mutex locks which are setup by @acronym{GnuTLS}.
-Applications can either call @funcref{gnutls_global_init} which will initialize the default
-operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
-@code{CriticalSection} on Windows), or manually specify the locking system using
-the function @funcref{gnutls_global_set_mutex} before calling @funcref{gnutls_global_init}. 
-Setting mutexes manually is recommended
-only for applications that have full control of the underlying libraries. If this
-is not the case, the use of the operating system defaults is recommended. An example of 
-non-native thread usage is shown below.
+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 @acronym{GnuTLS} on library initialization. Prior to version 3.3.0
+they were setup by calling @funcref{gnutls_global_init}. On special systems
+you could manually specify the locking system using
+the function @funcref{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.
 
 @example
 #include <gnutls/gnutls.h>
@@ -192,14 +189,9 @@ int main()
     */
    gnutls_global_set_mutex (mutex_init, mutex_deinit, 
                             mutex_lock, mutex_unlock);
-   gnutls_global_init();
 @}
 @end example
 
-Note that @funcref{gnutls_global_init} is itself not thread safe. It is also not recommended
-to initialize it on every available thread, but if need to, it should be protected using
-mutex locks.
-
 @showfuncdesc{gnutls_global_set_mutex}
 
 @node Callback functions
@@ -249,21 +241,17 @@ library.
 @subsection Initialization
 
 GnuTLS must be initialized before it can be used.  The library is
-initialized by calling @funcref{gnutls_global_init}. That call
-typically enables CPU-specific acceleration, performs any required
-precalculations needed, and initializes subsystems that could be
-used later (e.g., PKCS #11 -- see @ref{PKCS11 Initialization}).
-Note that since GnuTLS 3.3.0 it is no longer required to call
-@funcref{gnutls_global_init} in systems that support library constructors
-(i.e, ELF systems and Windows).
-
-The resources allocated by the initialization process can be released if the
-application no longer has a need to call GnuTLS functions, this is
-done by calling @funcref{gnutls_global_deinit}.
-
-In order to take advantage of the internationalization features in
-GnuTLS, such as translated error messages, the application must set
-the current locale using @code{setlocale} before initializing GnuTLS.
+initialized on load; prior to 3.3.0 was initialized by calling @funcref{gnutls_global_init}. 
+The initialization typically enables CPU-specific acceleration, performs any required
+precalculations needed, opens any required system devices (e.g., /dev/urandom on Linux)
+and initializes subsystems that could be used later.
+
+The resources allocated by the initialization process will be released 
+on library deinitialization, or explictly by calling @funcref{gnutls_global_deinit}.
+
+@c In order to take advantage of the internationalization features in
+@c GnuTLS, such as translated error messages, the application must set
+@c the current locale using @code{setlocale} before initializing GnuTLS.
 
 @node Version check
 @subsection Version check
@@ -336,7 +324,7 @@ When a program uses the GNU autoconf system, then the following
 line or similar can be used to detect the presence of GnuTLS.
 
 @example
-PKG_CHECK_MODULES([LIBGNUTLS], [gnutls >= 3.0.0])
+PKG_CHECK_MODULES([LIBGNUTLS], [gnutls >= 3.3.0])
 
 AC_SUBST([LIBGNUTLS_CFLAGS])
 AC_SUBST([LIBGNUTLS_LIBS])