aboutsummaryrefslogtreecommitdiff
path: root/openssl/doc/crypto/threads.pod
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2010-03-30 12:36:28 +0000
committermarha <marha@users.sourceforge.net>2010-03-30 12:36:28 +0000
commitff48c0d9098080b51ea12710029135916d117806 (patch)
tree96e6af9caf170ba21a1027b24e306a07e27d7b75 /openssl/doc/crypto/threads.pod
parentbb731f5ac92655c4860a41fa818a7a63005f8369 (diff)
downloadvcxsrv-ff48c0d9098080b51ea12710029135916d117806.tar.gz
vcxsrv-ff48c0d9098080b51ea12710029135916d117806.tar.bz2
vcxsrv-ff48c0d9098080b51ea12710029135916d117806.zip
svn merge -r514:HEAD ^/branches/released .
Diffstat (limited to 'openssl/doc/crypto/threads.pod')
-rw-r--r--openssl/doc/crypto/threads.pod91
1 files changed, 63 insertions, 28 deletions
diff --git a/openssl/doc/crypto/threads.pod b/openssl/doc/crypto/threads.pod
index 3df4ecd77..dc0e9391d 100644
--- a/openssl/doc/crypto/threads.pod
+++ b/openssl/doc/crypto/threads.pod
@@ -2,7 +2,9 @@
=head1 NAME
-CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks,
+CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback,
+CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy,
+CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks,
CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid,
CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
@@ -11,14 +13,26 @@ CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
#include <openssl/crypto.h>
- void CRYPTO_set_locking_callback(void (*locking_function)(int mode,
- int n, const char *file, int line));
-
- void CRYPTO_set_id_callback(unsigned long (*id_function)(void));
+ /* Don't use this structure directly. */
+ typedef struct crypto_threadid_st
+ {
+ void *ptr;
+ unsigned long val;
+ } CRYPTO_THREADID;
+ /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */
+ void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val);
+ void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr);
+ int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *));
+ void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *);
+ void CRYPTO_THREADID_current(CRYPTO_THREADID *id);
+ int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a,
+ const CRYPTO_THREADID *b);
+ void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest,
+ const CRYPTO_THREADID *src);
+ unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id);
int CRYPTO_num_locks(void);
-
/* struct CRYPTO_dynlock_value needs to be defined by the user */
struct CRYPTO_dynlock_value;
@@ -50,7 +64,8 @@ CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
=head1 DESCRIPTION
OpenSSL can safely be used in multi-threaded applications provided
-that at least two callback functions are set.
+that at least two callback functions are set, locking_function and
+threadid_func.
locking_function(int mode, int n, const char *file, int line) is
needed to perform locking on shared data structures.
@@ -65,10 +80,42 @@ B<CRYPTO_LOCK>, and releases it otherwise.
B<file> and B<line> are the file number of the function setting the
lock. They can be useful for debugging.
-id_function(void) is a function that returns a thread ID, for example
-pthread_self() if it returns an integer (see NOTES below). It isn't
-needed on Windows nor on platforms where getpid() returns a different
-ID for each thread (see NOTES below).
+threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing
+thread's identifier into B<id>. The implementation of this callback should not
+fill in B<id> directly, but should use CRYPTO_THREADID_set_numeric() if thread
+IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based.
+If the application does not register such a callback using
+CRYPTO_THREADID_set_callback(), then a default implementation is used - on
+Windows and BeOS this uses the system's default thread identifying APIs, and on
+all other platforms it uses the address of B<errno>. The latter is satisfactory
+for thread-safety if and only if the platform has a thread-local error number
+facility.
+
+Once threadid_func() is registered, or if the built-in default implementation is
+to be used;
+
+=over 4
+
+=item *
+CRYPTO_THREADID_current() records the currently-executing thread ID into the
+given B<id> object.
+
+=item *
+CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie.
+the same semantics as memcmp()).
+
+=item *
+CRYPTO_THREADID_cpy() duplicates a thread ID value,
+
+=item *
+CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This
+is usually the exact numeric or pointer-based thread ID used internally, however
+this also handles the unusual case where pointers are larger than 'long'
+variables and the platform's thread IDs are pointer-based - in this case, mixing
+is done to attempt to produce a unique numeric value even though it is not as
+wide as the platform's true thread IDs.
+
+=back
Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
of OpenSSL need it for better performance. To enable this, the following
@@ -140,22 +187,6 @@ You can find out if OpenSSL was configured with thread support:
Also, dynamic locks are currently not used internally by OpenSSL, but
may do so in the future.
-Defining id_function(void) has it's own issues. Generally speaking,
-pthread_self() should be used, even on platforms where getpid() gives
-different answers in each thread, since that may depend on the machine
-the program is run on, not the machine where the program is being
-compiled. For instance, Red Hat 8 Linux and earlier used
-LinuxThreads, whose getpid() returns a different value for each
-thread. Red Hat 9 Linux and later use NPTL, which is
-Posix-conformant, and has a getpid() that returns the same value for
-all threads in a process. A program compiled on Red Hat 8 and run on
-Red Hat 9 will therefore see getpid() returning the same value for
-all threads.
-
-There is still the issue of platforms where pthread_self() returns
-something other than an integer. This is a bit unusual, and this
-manual has no cookbook solution for that case.
-
=head1 EXAMPLES
B<crypto/threads/mttest.c> shows examples of the callback functions on
@@ -163,10 +194,14 @@ Solaris, Irix and Win32.
=head1 HISTORY
-CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are
+CRYPTO_set_locking_callback() is
available in all versions of SSLeay and OpenSSL.
CRYPTO_num_locks() was added in OpenSSL 0.9.4.
All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
+B<CRYPTO_THREADID> and associated functions were introduced in OpenSSL 1.0.0
+to replace (actually, deprecate) the previous CRYPTO_set_id_callback(),
+CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed
+thread IDs to always be represented by 'unsigned long'.
=head1 SEE ALSO