doc/crypto/threads.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
   6 CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL thread support
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/crypto.h>
  11
  12  CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void);
  13  int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock);
  14  int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock);
  15  int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock);
  16  void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock);
  17
  18  int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock);
  19
  20 =head1 DESCRIPTION
  21
  22 OpenSSL can be safely used in multi-threaded applications provided that
  23 support for the underlying OS threading API is built-in. Currently, OpenSSL
  24 supports the pthread and Windows APIs. OpenSSL can also be built without
  25 any multi-threading support, for example on platforms that don't provide
  26 any threading support or that provide a threading API that is not yet
  27 supported by OpenSSL.
  28
  29 The following multi-threading function are provided:
  30
  31 =over 4
  32
  33 =item *
  34 CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write
  35 lock.
  36
  37 =item *
  38 CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading.
  39
  40 =item *
  41 CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing.
  42
  43 =item *
  44 CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>.
  45
  46 =item *
  47 CRYPTO_THREAD_lock_frees() frees the provided B<lock>.
  48
  49 =item *
  50 CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the
  51 result of the operation in B<ret>. B<lock> will be locked, unless atomic
  52 operations are supported on the specific platform. Because of this, if a
  53 variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must
  54 be the only way that the variable is modified.
  55
  56 =back
  57
  58 =head1 RETURN VALUES
  59
  60 CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
  61
  62 CRYPTO_THREAD_lock_frees() returns no value.
  63
  64 The other functions return 1 on success or 0 on error.
  65
  66 =head1 NOTES
  67
  68 You can find out if OpenSSL was configured with thread support:
  69
  70  #define OPENSSL_THREAD_DEFINES
  71  #include <openssl/opensslconf.h>
  72  #if defined(OPENSSL_THREADS)
  73    // thread support enabled
  74  #else
  75    // no thread support
  76  #endif
  77
  78 =head1 SEE ALSO
  79
  80 L<crypto(3)>
  81
  82 =cut