mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-12-15 06:01:37 +08:00
Code Issues Packages Projects Releases Wiki Activity
b160f2823f
openssl/doc/crypto/threads.pod

83 lines
2.2 KiB
Plaintext
Raw Normal View History

threads mapage.
2000-02-24 02:10:42 +08:00
=pod
=head1 NAME
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL thread support
threads mapage.
2000-02-24 02:10:42 +08:00
=head1 SYNOPSIS
#include <openssl/crypto.h>
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);
int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);
int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);
int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);
void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
In the name section, all the functions described shoud be enumerated. This will also make it much simpler to generate softlinks name like each function to man-pages containing the info.
2000-09-15 05:23:28 +08:00
threads mapage.
2000-02-24 02:10:42 +08:00
=head1 DESCRIPTION
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
OpenSSL can be safely used in multi-threaded applications provided that
support for the underlying OS threading API is built-in. Currently, OpenSSL
supports the pthread and Windows APIs. OpenSSL can also be built without
any multi-threading support, for example on platforms that don't provide
any threading support or that provide a threading API that is not yet
supported by OpenSSL.
The following multi-threading function are provided:
Remove the dual-callback scheme for numeric and pointer thread IDs, deprecate the original (numeric-only) scheme, and replace with the CRYPTO_THREADID object. This hides the platform-specifics and should reduce the possibility for programming errors (where failing to explicitly check both thread ID forms could create subtle, platform-specific bugs). Thanks to Bodo, for invaluable review and feedback.
2008-08-06 23:54:15 +08:00
=over 4
=item *
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write
lock.
Remove the dual-callback scheme for numeric and pointer thread IDs, deprecate the original (numeric-only) scheme, and replace with the CRYPTO_THREADID object. This hides the platform-specifics and should reduce the possibility for programming errors (where failing to explicitly check both thread ID forms could create subtle, platform-specific bugs). Thanks to Bodo, for invaluable review and feedback.
2008-08-06 23:54:15 +08:00
=item *
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading.
Remove the dual-callback scheme for numeric and pointer thread IDs, deprecate the original (numeric-only) scheme, and replace with the CRYPTO_THREADID object. This hides the platform-specifics and should reduce the possibility for programming errors (where failing to explicitly check both thread ID forms could create subtle, platform-specific bugs). Thanks to Bodo, for invaluable review and feedback.
2008-08-06 23:54:15 +08:00
=item *
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing.
Remove the dual-callback scheme for numeric and pointer thread IDs, deprecate the original (numeric-only) scheme, and replace with the CRYPTO_THREADID object. This hides the platform-specifics and should reduce the possibility for programming errors (where failing to explicitly check both thread ID forms could create subtle, platform-specific bugs). Thanks to Bodo, for invaluable review and feedback.
2008-08-06 23:54:15 +08:00
=item *
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>.
Items without a =over and a =back are ignored.
2000-09-15 04:22:14 +08:00
Add support for dynamically created and destroyed mutexes. This will be needed in some ENGINE code, and might serve elsewhere as well. Note that it's implemented in such a way that the locking itself is done through the same CRYPTO_lock function as the static locks. WARNING: This is currently experimental and untested code (it will get tested soon, though :-)).
2000-06-18 23:59:04 +08:00
=item *
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_THREAD_lock_frees() frees the provided B<lock>.
Add support for dynamically created and destroyed mutexes. This will be needed in some ENGINE code, and might serve elsewhere as well. Note that it's implemented in such a way that the locking itself is done through the same CRYPTO_lock function as the static locks. WARNING: This is currently experimental and untested code (it will get tested soon, though :-)).
2000-06-18 23:59:04 +08:00
=item *
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the
result of the operation in B<ret>. B<lock> will be locked, unless atomic
operations are supported on the specific platform. Because of this, if a
variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must
be the only way that the variable is modified.
Add support for dynamically created and destroyed mutexes. This will be needed in some ENGINE code, and might serve elsewhere as well. Note that it's implemented in such a way that the locking itself is done through the same CRYPTO_lock function as the static locks. WARNING: This is currently experimental and untested code (it will get tested soon, though :-)).
2000-06-18 23:59:04 +08:00
Items without a =over and a =back are ignored.
2000-09-15 04:22:14 +08:00
=back
Correct a couple of command errors.
2000-02-24 09:20:31 +08:00
=head1 RETURN VALUES
CRYPTO_num_locks()
2000-02-24 08:22:17 +08:00
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
Add support for dynamically created and destroyed mutexes. This will be needed in some ENGINE code, and might serve elsewhere as well. Note that it's implemented in such a way that the locking itself is done through the same CRYPTO_lock function as the static locks. WARNING: This is currently experimental and untested code (it will get tested soon, though :-)).
2000-06-18 23:59:04 +08:00
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
CRYPTO_THREAD_lock_frees() returns no value.
Add support for dynamically created and destroyed mutexes. This will be needed in some ENGINE code, and might serve elsewhere as well. Note that it's implemented in such a way that the locking itself is done through the same CRYPTO_lock function as the static locks. WARNING: This is currently experimental and untested code (it will get tested soon, though :-)).
2000-06-18 23:59:04 +08:00
Implement new multi-threading API Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org>
2015-10-26 00:43:55 +08:00
The other functions return 1 on success or 0 on error.
CRYPTO_num_locks()
2000-02-24 08:22:17 +08:00
Add better documentation on how id_function() should be defined and what issues there are. PR: 1096
2005-06-18 13:52:16 +08:00
=head1 NOTES
threads mapage.
2000-02-24 02:10:42 +08:00
You can find out if OpenSSL was configured with thread support:
#define OPENSSL_THREAD_DEFINES
#include <openssl/opensslconf.h>
The macro THREADS was changed to OPENSSL_THREADS a long time ago. PR: 1096
2005-06-04 16:44:02 +08:00
#if defined(OPENSSL_THREADS)
threads mapage.
2000-02-24 02:10:42 +08:00
// thread support enabled
#else
// no thread support
#endif
=head1 SEE ALSO
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-18 03:21:33 +08:00
L<crypto(3)>
threads mapage.
2000-02-24 02:10:42 +08:00
=cut
Reference in New Issue Copy Permalink