doc/man3/CRYPTO_THREAD_run_once.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 CRYPTO_THREAD_run_once,
   6 CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
   7 CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free,
   8 CRYPTO_atomic_add, CRYPTO_atomic_or, CRYPTO_atomic_load, CRYPTO_atomic_store,
   9 CRYPTO_atomic_load_int,
  10 OSSL_set_max_threads, OSSL_get_max_threads,
  11 OSSL_get_thread_support_flags, OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL,
  12 OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN - OpenSSL thread support
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/crypto.h>
  17
  18  CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;
  19  int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
  20
  21  CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);
  22  int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);
  23  int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);
  24  int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);
  25  void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
  26
  27  int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
  28  int CRYPTO_atomic_or(uint64_t *val, uint64_t op, uint64_t *ret,
  29                       CRYPTO_RWLOCK *lock);
  30  int CRYPTO_atomic_load(uint64_t *val, uint64_t *ret, CRYPTO_RWLOCK *lock);
  31  int CRYPTO_atomic_store(uint64_t *dst, uint64_t val, CRYPTO_RWLOCK *lock);
  32  int CRYPTO_atomic_load_int(int *val, int *ret, CRYPTO_RWLOCK *lock);
  33
  34  int OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads);
  35  uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx);
  36  uint32_t OSSL_get_thread_support_flags(void);
  37
  38  #define OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL
  39  #define OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN
  40
  41 =head1 DESCRIPTION
  42
  43 OpenSSL can be safely used in multi-threaded applications provided that
  44 support for the underlying OS threading API is built-in. Currently, OpenSSL
  45 supports the pthread and Windows APIs. OpenSSL can also be built without
  46 any multi-threading support, for example on platforms that don't provide
  47 any threading support or that provide a threading API that is not yet
  48 supported by OpenSSL.
  49
  50 The following multi-threading function are provided:
  51
  52 =over 2
  53
  54 =item *
  55
  56 CRYPTO_THREAD_run_once() can be used to perform one-time initialization.
  57 The I<once> argument must be a pointer to a static object of type
  58 B<CRYPTO_ONCE> that was statically initialized to the value
  59 B<CRYPTO_ONCE_STATIC_INIT>.
  60 The I<init> argument is a pointer to a function that performs the desired
  61 exactly once initialization.
  62 In particular, this can be used to allocate locks in a thread-safe manner,
  63 which can then be used with the locking functions below.
  64
  65 =item *
  66
  67 CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write
  68 lock.
  69
  70 =item *
  71
  72 CRYPTO_THREAD_read_lock() locks the provided I<lock> for reading.
  73
  74 =item *
  75
  76 CRYPTO_THREAD_write_lock() locks the provided I<lock> for writing.
  77
  78 =item *
  79
  80 CRYPTO_THREAD_unlock() unlocks the previously locked I<lock>.
  81
  82 =item *
  83
  84 CRYPTO_THREAD_lock_free() frees the provided I<lock>.
  85
  86 =item *
  87
  88 CRYPTO_atomic_add() atomically adds I<amount> to I<*val> and returns the
  89 result of the operation in I<*ret>. I<lock> will be locked, unless atomic
  90 operations are supported on the specific platform. Because of this, if a
  91 variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must
  92 be the only way that the variable is modified. If atomic operations are not
  93 supported and I<lock> is NULL, then the function will fail.
  94
  95 =item *
  96
  97 CRYPTO_atomic_or() performs an atomic bitwise or of I<op> and I<*val> and stores
  98 the result back in I<*val>. It also returns the result of the operation in
  99 I<*ret>. I<lock> will be locked, unless atomic operations are supported on the
 100 specific platform. Because of this, if a variable is modified by
 101 CRYPTO_atomic_or() or read by CRYPTO_atomic_load() then CRYPTO_atomic_or() must
 102 be the only way that the variable is modified. If atomic operations are not
 103 supported and I<lock> is NULL, then the function will fail.
 104
 105 =item *
 106
 107 CRYPTO_atomic_load() atomically loads the contents of I<*val> into I<*ret>.
 108 I<lock> will be locked, unless atomic operations are supported on the specific
 109 platform. Because of this, if a variable is modified by CRYPTO_atomic_or() or
 110 read by CRYPTO_atomic_load() then CRYPTO_atomic_load() must be the only way that
 111 the variable is read. If atomic operations are not supported and I<lock> is
 112 NULL, then the function will fail.
 113
 114 =item *
 115
 116 CRYPTO_atomic_store() atomically stores the contents of I<val> into I<*dst>.
 117 I<lock> will be locked, unless atomic operations are supported on the specific
 118 plaform.
 119
 120 =item *
 121
 122 CRYPTO_atomic_load_int() works identically to CRYPTO_atomic_load() but operates
 123 on an I<int> value instead of a I<uint64_t> value.
 124
 125 =item *
 126
 127 OSSL_set_max_threads() sets the maximum number of threads to be used by the
 128 thread pool. If the argument is 0, thread pooling is disabled. OpenSSL will
 129 not create any threads and existing threads in the thread pool will be torn
 130 down. The maximum thread count is a limit, not a target. Threads will not be
 131 spawned unless (and until) there is demand. Thread polling is disabled by
 132 default. To enable threading you must call OSSL_set_max_threads() explicitly.
 133 Under no circumstances is this done for you.
 134
 135 =item *
 136
 137 OSSL_get_thread_support_flags() determines what thread pool functionality
 138 OpenSSL is compiled with and is able to support in the current run time
 139 environment. B<OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL> indicates that the base
 140 thread pool functionality is available, and
 141 B<OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN> indicates that the default thread pool
 142 model is available. The default thread pool model is currently the only model
 143 available, therefore both of these flags must be set for thread pool
 144 functionality to be used.
 145
 146 =back
 147
 148 =head1 RETURN VALUES
 149
 150 CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.
 151
 152 CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
 153
 154 CRYPTO_THREAD_lock_free() returns no value.
 155
 156 OSSL_set_max_threads() returns 1 on success and 0 on failure. Returns failure
 157 if OpenSSL-managed thread pooling is not supported (for example, if it is not
 158 supported on the current platform, or because OpenSSL is not built with the
 159 necessary support).
 160
 161 OSSL_get_max_threads() returns the maximum number of threads currently allowed
 162 to be used by the thread pool. If thread pooling is disabled or not available,
 163 returns 0.
 164
 165 OSSL_get_thread_support_flags() returns zero or more B<OSSL_THREAD_SUPPORT_FLAG>
 166 values.
 167
 168 The other functions return 1 on success, or 0 on error.
 169
 170 =head1 NOTES
 171
 172 On Windows platforms the CRYPTO_THREAD_* types and functions in the
 173 F<< <openssl/crypto.h> >> header are dependent on some of the types
 174 customarily made available by including F<< <windows.h> >>. The application
 175 developer is likely to require control over when the latter is included,
 176 commonly as one of the first included headers. Therefore, it is defined as an
 177 application developer's responsibility to include F<< <windows.h> >> prior to
 178 F<< <openssl/crypto.h> >> where use of CRYPTO_THREAD_* types and functions is
 179 required.
 180
 181 =head1 EXAMPLES
 182
 183 You can find out if OpenSSL was configured with thread support:
 184
 185  #include <openssl/opensslconf.h>
 186  #if defined(OPENSSL_THREADS)
 187      /* thread support enabled */
 188  #else
 189      /* no thread support */
 190  #endif
 191
 192 This example safely initializes and uses a lock.
 193
 194  #ifdef _WIN32
 195  # include <windows.h>
 196  #endif
 197  #include <openssl/crypto.h>
 198
 199  static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;
 200  static CRYPTO_RWLOCK *lock;
 201
 202  static void myinit(void)
 203  {
 204      lock = CRYPTO_THREAD_lock_new();
 205  }
 206
 207  static int mylock(void)
 208  {
 209      if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL)
 210          return 0;
 211      return CRYPTO_THREAD_write_lock(lock);
 212  }
 213
 214  static int myunlock(void)
 215  {
 216      return CRYPTO_THREAD_unlock(lock);
 217  }
 218
 219  int serialized(void)
 220  {
 221      int ret = 0;
 222
 223      if (mylock()) {
 224          /* Your code here, do not return without releasing the lock! */
 225          ret = ... ;
 226      }
 227      myunlock();
 228      return ret;
 229  }
 230
 231 Finalization of locks is an advanced topic, not covered in this example.
 232 This can only be done at process exit or when a dynamically loaded library is
 233 no longer in use and is unloaded.
 234 The simplest solution is to just "leak" the lock in applications and not
 235 repeatedly load/unload shared libraries that allocate locks.
 236
 237 =head1 SEE ALSO
 238
 239 L<crypto(7)>, L<openssl-threads(7)>.
 240
 241 =head1 HISTORY
 242
 243 CRYPTO_atomic_store() was added in OpenSSL 3.4.0
 244
 245 =head1 COPYRIGHT
 246
 247 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
 248
 249 Licensed under the Apache License 2.0 (the "License").  You may not use
 250 this file except in compliance with the License.  You can obtain a copy
 251 in the file LICENSE in the source distribution or at
 252 L<https://www.openssl.org/source/license.html>.
 253
 254 =cut