Implement new multi-threading API
[openssl.git] / 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