]>
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 | |
8c1cbc72 | 96 | one of the first included headers. Therefore, it is defined as an |
f1f5ee17 AP |
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 | ||
cda77422 | 100 | =head1 EXAMPLES |
5c4328f0 | 101 | |
485d3361 RS |
102 | You can find out if OpenSSL was configured with thread support: |
103 | ||
104 | #include <openssl/opensslconf.h> | |
105 | #if defined(OPENSSL_THREADS) | |
106 | /* thread support enabled */ | |
107 | #else | |
108 | /* no thread support */ | |
109 | #endif | |
110 | ||
5c4328f0 VD |
111 | This example safely initializes and uses a lock. |
112 | ||
2947af32 BB |
113 | #ifdef _WIN32 |
114 | # include <windows.h> | |
115 | #endif | |
116 | #include <openssl/crypto.h> | |
117 | ||
118 | static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT; | |
119 | static CRYPTO_RWLOCK *lock; | |
120 | ||
121 | static void myinit(void) | |
122 | { | |
123 | lock = CRYPTO_THREAD_lock_new(); | |
124 | } | |
125 | ||
126 | static int mylock(void) | |
127 | { | |
128 | if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL) | |
129 | return 0; | |
130 | return CRYPTO_THREAD_write_lock(lock); | |
131 | } | |
132 | ||
133 | static int myunlock(void) | |
134 | { | |
135 | return CRYPTO_THREAD_unlock(lock); | |
136 | } | |
137 | ||
138 | int serialized(void) | |
139 | { | |
140 | int ret = 0; | |
141 | ||
142 | if (mylock()) { | |
143 | /* Your code here, do not return without releasing the lock! */ | |
144 | ret = ... ; | |
145 | } | |
146 | myunlock(); | |
147 | return ret; | |
148 | } | |
5c4328f0 VD |
149 | |
150 | Finalization of locks is an advanced topic, not covered in this example. | |
151 | This can only be done at process exit or when a dynamically loaded library is | |
152 | no longer in use and is unloaded. | |
153 | The simplest solution is to just "leak" the lock in applications and not | |
154 | repeatedly load/unload shared libraries that allocate locks. | |
155 | ||
be7ae175 UM |
156 | =head1 SEE ALSO |
157 | ||
b97fdb57 | 158 | L<crypto(7)> |
be7ae175 | 159 | |
e2f92610 RS |
160 | =head1 COPYRIGHT |
161 | ||
6738bf14 | 162 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 163 | |
4746f25a | 164 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
165 | this file except in compliance with the License. You can obtain a copy |
166 | in the file LICENSE in the source distribution or at | |
167 | L<https://www.openssl.org/source/license.html>. | |
168 | ||
169 | =cut |