[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
If you use pthread and your applications forks and does not directly call exec (even calling stdio functions), all kind of problems may occur. Future versions of Libgcrypt will try to cleanup using pthread_atfork but even that may lead to problems. This is a common problem with almost all applications using pthread and fork.
Note that future versions of Libgcrypt will drop this flexible thread support and instead only support the platforms standard thread implementation.
-
The function
gcry_check_version
must be called before any other function in the library, except theGCRYCTL_SET_THREAD_CBS
command (called via thegcry_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 callgcry_check_version
before creating the other threads using Libgcrypt(1). -
Just like the function
gpg_strerror
, the functiongcry_strerror
is not thread safe. You have to usegpg_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 ofGCRYCTL_SET_THREAD_CBS
in order to register the thread callback structure named “gcry_threads_pth”. Example:ret = gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pth);
GCRY_THREAD_OPTION_PTHREAD_IMPL
-
This macro defines the following (static) symbols:
gcry_pthread_mutex_init
,gcry_pthread_mutex_destroy
,gcry_pthread_mutex_lock
,gcry_pthread_mutex_unlock
,gcry_threads_pthread
.After including this macro,
gcry_control()
shall be used with a command ofGCRYCTL_SET_THREAD_CBS
in order to register the thread callback structure named “gcry_threads_pthread”. Example:ret = gcry_control (GCRYCTL_SET_THREAD_CBS, &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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on February 9, 2014 using texi2html 5.0.