141 lines
3.8 KiB
Text
141 lines
3.8 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
CRYPTO_THREAD_run_once,
|
|
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
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/crypto.h>
|
|
|
|
CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;
|
|
int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
|
|
|
|
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);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
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:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
CRYPTO_THREAD_run_once() can be used to perform one-time initialization.
|
|
The B<once> argument must be a pointer to a static object of type
|
|
B<CRYPTO_ONCE> that was statically initialized to the value
|
|
B<CRYPTO_ONCE_STATIC_INIT>.
|
|
The B<init> argument is a pointer to a function that performs the desired
|
|
exactly once initialization.
|
|
In particular, this can be used to allocate locks in a thread-safe manner,
|
|
which can then be used with the locking functions below.
|
|
|
|
=item *
|
|
CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write
|
|
lock.
|
|
|
|
=item *
|
|
CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading.
|
|
|
|
=item *
|
|
CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing.
|
|
|
|
=item *
|
|
CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>.
|
|
|
|
=item *
|
|
CRYPTO_THREAD_lock_frees() frees the provided B<lock>.
|
|
|
|
=item *
|
|
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.
|
|
|
|
=back
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.
|
|
|
|
CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
|
|
|
|
CRYPTO_THREAD_lock_frees() returns no value.
|
|
|
|
The other functions return 1 on success or 0 on error.
|
|
|
|
=head1 EXAMPLE
|
|
|
|
This example safely initializes and uses a lock.
|
|
|
|
#include <openssl/crypto.h>
|
|
|
|
static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;
|
|
static CRYPTO_RWLOCK *lock;
|
|
|
|
static void myinit(void)
|
|
{
|
|
lock = CRYPTO_THREAD_lock_new();
|
|
}
|
|
|
|
static int mylock(void)
|
|
{
|
|
if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)
|
|
return 0;
|
|
return CRYPTO_THREAD_write_lock(lock);
|
|
}
|
|
|
|
static int myunlock(void)
|
|
{
|
|
return CRYPTO_THREAD_unlock(lock);
|
|
}
|
|
|
|
int serialized(void)
|
|
{
|
|
int ret = 0;
|
|
|
|
if (mylock()) {
|
|
/* Your code here, do not return without releasing the lock! */
|
|
ret = ... ;
|
|
}
|
|
myunlock();
|
|
return ret;
|
|
}
|
|
|
|
Finalization of locks is an advanced topic, not covered in this example.
|
|
This can only be done at process exit or when a dynamically loaded library is
|
|
no longer in use and is unloaded.
|
|
The simplest solution is to just "leak" the lock in applications and not
|
|
repeatedly load/unload shared libraries that allocate locks.
|
|
|
|
=head1 NOTES
|
|
|
|
You can find out if OpenSSL was configured with thread support:
|
|
|
|
#include <openssl/opensslconf.h>
|
|
#if defined(OPENSSL_THREADS)
|
|
// thread support enabled
|
|
#else
|
|
// no thread support
|
|
#endif
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<crypto(3)>
|
|
|
|
=cut
|