DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(gcrypt.info.gz) Multi Threading

Info Catalog (gcrypt.info.gz) Initializing the library (gcrypt.info.gz) Preparation
 
 2.5 Multi Threading
 ===================
 
 As mentioned earlier, the `Libgcrypt' library is thread-safe if you
 adhere to the following requirements:
 
    * If your application is multi-threaded, you must set the thread
      support callbacks with the `GCRYCTL_SET_THREAD_CBS' command
      *before* any other function in the library.
 
      This is easy enough if you are indeed writing an application using
      Libgcrypt.  It is rather problematic if you are writing a library
      instead.  Here are some tips what to do if you are writing a
      library:
 
      If your library requires a certain thread package, just initialize
      Libgcrypt to use this thread package.  If your library supports
      multiple thread packages, but needs to be configured, you will
      have to implement a way to determine which thread package the
      application wants to use with your library anyway.  Then configure
      Libgcrypt to use this thread package.
 
      If your library is fully reentrant without any special support by a
      thread package, then you are lucky indeed.  Unfortunately, this
      does not relieve you from doing either of the two above, or use a
      third option.  The third option is to let the application
      initialize Libgcrypt for you.  Then you are not using Libgcrypt
      transparently, though.
 
      As if this was not difficult enough, a conflict may arise if two
      libraries try to initialize Libgcrypt independently of each
      others, and both such libraries are then linked into the same
      application.  To make it a bit simpler for you, this will probably
      work, but only if both libraries have the same requirement for the
      thread package.  This is currently only supported for the
      non-threaded case, GNU Pth and pthread.  Support for more thread
      packages is easy to add, so contact us if you require it.
 
    * The function `gcry_check_version' must be called before any other
      function in the library, except the `GCRYCTL_SET_THREAD_CBS'
      command (called via the `gcry_control' function), because it
      initializes the thread support subsystem in Libgcrypt.  To achieve
      this in multi-threaded programs, you must synchronize the memory
      with respect to other threads that also want to use Libgcrypt.
      For this, it is sufficient to call `gcry_check_version' before
      creating the other threads using Libgcrypt(1).
 
    *  As with the function `gpg_strerror', `gcry_strerror' is not
      thread safe.  You have to use `gpg_strerror_r' instead.
 
    Libgcrypt contains convenient macros, which define the necessary
 thread callbacks for PThread and for GNU Pth:
 
 `GCRY_THREAD_OPTION_PTH_IMPL'
      This macro defines the following (static) symbols: gcry_pth_init,
      gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock,
      gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write,
      gcry_pth_select, gcry_pth_waitpid, gcry_pth_accept,
      gcry_pth_connect, gcry_threads_pth.
 
      After including this macro, gcry_control() shall be used with a
      command of GCRYCTL_SET_THREAD_CBS in order to register the thread
      callback structure named "gcry_threads_pth".
 
 `GCRY_THREAD_OPTION_PTHREAD_IMPL'
      This macro defines the following (static) symbols:
      gcry_pthread_mutex_init, gcry_pthread_mutex_destroy,
      gcry_mutex_lock, gcry_mutex_unlock, gcry_threads_pthread.
 
      After including this macro, gcry_control() shall be used with a
      command of GCRYCTL_SET_THREAD_CBS in order to register the thread
      callback structure named "gcry_threads_pthread".
 
    Note that these macros need to be terminated with a semicolon.  Keep
 in mind that these are convenient macros for C programmers; C++
 programmers might have to wrap these macros in an "extern C" body.
 
    ---------- Footnotes ----------
 
    (1) At least this is true for POSIX threads, as `pthread_create' is
 a function that synchronizes memory with respects to other threads.
 There are many functions which have this property, a complete list can
 be found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in
 the definition of the term "Memory Synchronization".  For other thread
 packages, more relaxed or more strict rules may apply.
 
Info Catalog (gcrypt.info.gz) Initializing the library (gcrypt.info.gz) Preparation
automatically generated byinfo2html