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
+CRYPTO_atomic_add, CRYPTO_atomic_or, CRYPTO_atomic_load,
+OSSL_set_max_threads, OSSL_get_max_threads,
+OSSL_get_thread_support_flags - OpenSSL thread support
=head1 SYNOPSIS
void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_or(uint64_t *val, uint64_t op, uint64_t *ret,
+ CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_load(uint64_t *val, uint64_t *ret, CRYPTO_RWLOCK *lock);
+
+ int OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads);
+ uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx);
+ uint32_t OSSL_get_thread_support_flags(void);
=head1 DESCRIPTION
=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
+The I<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
+The I<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_read_lock() locks the provided B<lock> for reading.
+CRYPTO_THREAD_read_lock() locks the provided I<lock> for reading.
=item *
-CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing.
+CRYPTO_THREAD_write_lock() locks the provided I<lock> for writing.
=item *
-CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>.
+CRYPTO_THREAD_unlock() unlocks the previously locked I<lock>.
=item *
-CRYPTO_THREAD_lock_free() frees the provided B<lock>.
+CRYPTO_THREAD_lock_free() frees the provided I<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
+CRYPTO_atomic_add() atomically adds I<amount> to I<*val> and returns the
+result of the operation in I<*ret>. I<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.
+be the only way that the variable is modified. If atomic operations are not
+supported and I<lock> is NULL, then the function will fail.
+
+=item *
+
+CRYPTO_atomic_or() performs an atomic bitwise or of I<op> and I<*val> and stores
+the result back in I<*val>. It also returns the result of the operation in
+I<*ret>. I<lock> will be locked, unless atomic operations are supported on the
+specific platform. Because of this, if a variable is modified by
+CRYPTO_atomic_or() or read by CRYPTO_atomic_load() then CRYPTO_atomic_or() must
+be the only way that the variable is modified. If atomic operations are not
+supported and I<lock> is NULL, then the function will fail.
+
+=item *
+
+CRYPTO_atomic_load() atomically loads the contents of I<*val> into I<*ret>.
+I<lock> will be locked, unless atomic operations are supported on the specific
+platform. Because of this, if a variable is modified by CRYPTO_atomic_or() or
+read by CRYPTO_atomic_load() then CRYPTO_atomic_load() must be the only way that
+the variable is read. If atomic operations are not supported and I<lock> is
+NULL, then the function will fail.
+
+=item *
+
+OSSL_set_max_threads() sets the maximum number of threads to be used by the
+thread pool. If the argument is 0, thread pooling is disabled. OpenSSL will
+not create any threads and existing threads in the thread pool will be torn
+down. The maximum thread count is a limit, not a target. Threads will not be
+spawned unless (and until) there is demand. Thread polling is disabled by
+default. To enable threading you must call OSSL_set_max_threads() explicitly.
+Under no circumstances is this done for you.
=back
CRYPTO_THREAD_lock_free() returns no value.
+OSSL_set_max_threads() returns 1 on success and 0 on failure. Returns failure
+if OpenSSL-managed thread pooling is not supported (for example, if it is not
+supported on the current platform, or because OpenSSL is not built with the
+necessary support).
+
+OSSL_get_max_threads() returns the maximum number of threads currently allowed
+to be used by the thread pool. If thread pooling is disabled or not available,
+returns 0.
+
The other functions return 1 on success, or 0 on error.
=head1 NOTES
On Windows platforms the CRYPTO_THREAD_* types and functions in the
-openssl/crypto.h header are dependent on some of the types customarily
-made available by including windows.h. The application developer is
-likely to require control over when the latter is included, commonly as
-one of the first included headers. Therefore it is defined as an
-application developer's responsibility to include windows.h prior to
-crypto.h where use of CRYPTO_THREAD_* types and functions is required.
+F<< <openssl/crypto.h> >> header are dependent on some of the types
+customarily made available by including F<< <windows.h> >>. The application
+developer is likely to require control over when the latter is included,
+commonly as one of the first included headers. Therefore, it is defined as an
+application developer's responsibility to include F<< <windows.h> >> prior to
+F<< <openssl/crypto.h> >> where use of CRYPTO_THREAD_* types and functions is
+required.
=head1 EXAMPLES
+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
+
This example safely initializes and uses a lock.
#ifdef _WIN32
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(7)>
+L<crypto(7)>, L<openssl-threads(7)>.
=head1 COPYRIGHT
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
projects / thirdparty / openssl.git / blobdiff