]>
Commit | Line | Data |
---|---|---|
be7ae175 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5c4328f0 | 5 | CRYPTO_THREAD_run_once, |
71a04cfc | 6 | CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock, |
d2b86364 AP |
7 | CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, |
8 | CRYPTO_atomic_add - OpenSSL thread support | |
be7ae175 UM |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/crypto.h> | |
13 | ||
5c4328f0 VD |
14 | CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT; |
15 | int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void)); | |
16 | ||
71a04cfc AG |
17 | CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void); |
18 | int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock); | |
19 | int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock); | |
20 | int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock); | |
21 | void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock); | |
22 | ||
23 | int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock); | |
e1b78bc6 | 24 | |
be7ae175 UM |
25 | =head1 DESCRIPTION |
26 | ||
71a04cfc AG |
27 | OpenSSL can be safely used in multi-threaded applications provided that |
28 | support for the underlying OS threading API is built-in. Currently, OpenSSL | |
29 | supports the pthread and Windows APIs. OpenSSL can also be built without | |
30 | any multi-threading support, for example on platforms that don't provide | |
31 | any threading support or that provide a threading API that is not yet | |
32 | supported by OpenSSL. | |
33 | ||
34 | The following multi-threading function are provided: | |
4c329696 | 35 | |
2f61bc2e | 36 | =over 2 |
4c329696 | 37 | |
5c4328f0 | 38 | =item * |
2f61bc2e | 39 | |
5c4328f0 VD |
40 | CRYPTO_THREAD_run_once() can be used to perform one-time initialization. |
41 | The B<once> argument must be a pointer to a static object of type | |
42 | B<CRYPTO_ONCE> that was statically initialized to the value | |
43 | B<CRYPTO_ONCE_STATIC_INIT>. | |
44 | The B<init> argument is a pointer to a function that performs the desired | |
45 | exactly once initialization. | |
46 | In particular, this can be used to allocate locks in a thread-safe manner, | |
47 | which can then be used with the locking functions below. | |
48 | ||
4c329696 | 49 | =item * |
2f61bc2e | 50 | |
71a04cfc AG |
51 | CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write |
52 | lock. | |
4c329696 GT |
53 | |
54 | =item * | |
2f61bc2e | 55 | |
71a04cfc | 56 | CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading. |
4c329696 GT |
57 | |
58 | =item * | |
2f61bc2e | 59 | |
71a04cfc | 60 | CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing. |
4c329696 GT |
61 | |
62 | =item * | |
2f61bc2e | 63 | |
71a04cfc | 64 | CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>. |
54731d75 | 65 | |
c7922304 | 66 | =item * |
2f61bc2e | 67 | |
b9ed9ab3 | 68 | CRYPTO_THREAD_lock_free() frees the provided B<lock>. |
c7922304 RL |
69 | |
70 | =item * | |
2f61bc2e | 71 | |
71a04cfc AG |
72 | CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the |
73 | result of the operation in B<ret>. B<lock> will be locked, unless atomic | |
74 | operations are supported on the specific platform. Because of this, if a | |
75 | variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must | |
76 | be the only way that the variable is modified. | |
c7922304 | 77 | |
54731d75 RL |
78 | =back |
79 | ||
9f7f1ff7 | 80 | =head1 RETURN VALUES |
b6891e9c | 81 | |
5c4328f0 VD |
82 | CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error. |
83 | ||
71a04cfc | 84 | CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error. |
c7922304 | 85 | |
b9ed9ab3 | 86 | CRYPTO_THREAD_lock_free() returns no value. |
c7922304 | 87 | |
b9ed9ab3 | 88 | The other functions return 1 on success, or 0 on error. |
b6891e9c | 89 | |
f1f5ee17 AP |
90 | =head1 NOTES |
91 | ||
92 | On Windows platforms the CRYPTO_THREAD_* types and functions in the | |
93 | openssl/crypto.h header are dependent on some of the types customarily | |
94 | made available by including windows.h. The application developer is | |
95 | likely to require control over when the latter is included, commonly as | |
96 | one of the first included headers. Therefore it is defined as an | |
97 | application developer's responsibility to include windows.h prior to | |
98 | crypto.h where use of CRYPTO_THREAD_* types and functions is required. | |
99 | ||
5c4328f0 VD |
100 | =head1 EXAMPLE |
101 | ||
102 | This example safely initializes and uses a lock. | |
103 | ||
2947af32 BB |
104 | #ifdef _WIN32 |
105 | # include <windows.h> | |
106 | #endif | |
107 | #include <openssl/crypto.h> | |
108 | ||
109 | static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT; | |
110 | static CRYPTO_RWLOCK *lock; | |
111 | ||
112 | static void myinit(void) | |
113 | { | |
114 | lock = CRYPTO_THREAD_lock_new(); | |
115 | } | |
116 | ||
117 | static int mylock(void) | |
118 | { | |
119 | if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL) | |
120 | return 0; | |
121 | return CRYPTO_THREAD_write_lock(lock); | |
122 | } | |
123 | ||
124 | static int myunlock(void) | |
125 | { | |
126 | return CRYPTO_THREAD_unlock(lock); | |
127 | } | |
128 | ||
129 | int serialized(void) | |
130 | { | |
131 | int ret = 0; | |
132 | ||
133 | if (mylock()) { | |
134 | /* Your code here, do not return without releasing the lock! */ | |
135 | ret = ... ; | |
136 | } | |
137 | myunlock(); | |
138 | return ret; | |
139 | } | |
5c4328f0 VD |
140 | |
141 | Finalization of locks is an advanced topic, not covered in this example. | |
142 | This can only be done at process exit or when a dynamically loaded library is | |
143 | no longer in use and is unloaded. | |
144 | The simplest solution is to just "leak" the lock in applications and not | |
145 | repeatedly load/unload shared libraries that allocate locks. | |
146 | ||
eef468e3 | 147 | =head1 NOTES |
be7ae175 UM |
148 | |
149 | You can find out if OpenSSL was configured with thread support: | |
150 | ||
be7ae175 | 151 | #include <openssl/opensslconf.h> |
19ac1902 | 152 | #if defined(OPENSSL_THREADS) |
95dd5fb2 | 153 | /* thread support enabled */ |
be7ae175 | 154 | #else |
95dd5fb2 | 155 | /* no thread support */ |
be7ae175 UM |
156 | #endif |
157 | ||
be7ae175 UM |
158 | =head1 SEE ALSO |
159 | ||
b97fdb57 | 160 | L<crypto(7)> |
be7ae175 | 161 | |
e2f92610 RS |
162 | =head1 COPYRIGHT |
163 | ||
6738bf14 | 164 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
165 | |
166 | Licensed under the OpenSSL license (the "License"). You may not use | |
167 | this file except in compliance with the License. You can obtain a copy | |
168 | in the file LICENSE in the source distribution or at | |
169 | L<https://www.openssl.org/source/license.html>. | |
170 | ||
171 | =cut |