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