1 files changed, 65 insertions, 13 deletions
diff --git a/doc/crypto/threads.pod b/doc/crypto/threads.pod
index afa45cd76c..dc0e9391dc 100644
--- a/doc/crypto/threads.pod
+++ b/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,9 +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. It is not
-needed on Windows nor on platforms where getpid() returns a different
-ID for each thread (most notably Linux).
+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
@@ -124,13 +172,13 @@ CRYPTO_get_new_dynlockid() returns the index to the newly created lock.
 
 The other functions return no values.
 
-=head1 NOTE
+=head1 NOTES
 
 You can find out if OpenSSL was configured with thread support:
 
  #define OPENSSL_THREAD_DEFINES
  #include <openssl/opensslconf.h>
- #if defined(THREADS)
+ #if defined(OPENSSL_THREADS)
    // thread support enabled
  #else
    // no thread support
@@ -146,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