1CRYPTO_THREAD_RUN_ONCE(3ossl)       OpenSSL      CRYPTO_THREAD_RUN_ONCE(3ossl)
2
3
4

NAME

6       CRYPTO_THREAD_run_once, CRYPTO_THREAD_lock_new,
7       CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
8       CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add,
9       CRYPTO_atomic_or, CRYPTO_atomic_load - OpenSSL thread support
10

SYNOPSIS

12        #include <openssl/crypto.h>
13
14        CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT;
15        int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void));
16
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);
24        int CRYPTO_atomic_or(uint64_t *val, uint64_t op, uint64_t *ret,
25                             CRYPTO_RWLOCK *lock);
26        int CRYPTO_atomic_load(uint64_t *val, uint64_t *ret, CRYPTO_RWLOCK *lock);
27

DESCRIPTION

29       OpenSSL can be safely used in multi-threaded applications provided that
30       support for the underlying OS threading API is built-in. Currently,
31       OpenSSL supports the pthread and Windows APIs. OpenSSL can also be
32       built without any multi-threading support, for example on platforms
33       that don't provide any threading support or that provide a threading
34       API that is not yet supported by OpenSSL.
35
36       The following multi-threading function are provided:
37
38CRYPTO_THREAD_run_once() can be used to perform one-time
39         initialization.  The once argument must be a pointer to a static
40         object of type CRYPTO_ONCE that was statically initialized to the
41         value CRYPTO_ONCE_STATIC_INIT.  The init argument is a pointer to a
42         function that performs the desired exactly once initialization.  In
43         particular, this can be used to allocate locks in a thread-safe
44         manner, which can then be used with the locking functions below.
45
46CRYPTO_THREAD_lock_new() allocates, initializes and returns a new
47         read/write lock.
48
49CRYPTO_THREAD_read_lock() locks the provided lock for reading.
50
51CRYPTO_THREAD_write_lock() locks the provided lock for writing.
52
53CRYPTO_THREAD_unlock() unlocks the previously locked lock.
54
55CRYPTO_THREAD_lock_free() frees the provided lock.
56
57CRYPTO_atomic_add() atomically adds amount to *val and returns the
58         result of the operation in *ret. lock will be locked, unless atomic
59         operations are supported on the specific platform. Because of this,
60         if a variable is modified by CRYPTO_atomic_add() then
61         CRYPTO_atomic_add() must be the only way that the variable is
62         modified. If atomic operations are not supported and lock is NULL,
63         then the function will fail.
64
65CRYPTO_atomic_or() performs an atomic bitwise or of op and *val and
66         stores the result back in *val. It also returns the result of the
67         operation in *ret. lock will be locked, unless atomic operations are
68         supported on the specific platform. Because of this, if a variable is
69         modified by CRYPTO_atomic_or() or read by CRYPTO_atomic_load() then
70         CRYPTO_atomic_or() must be the only way that the variable is
71         modified. If atomic operations are not supported and lock is NULL,
72         then the function will fail.
73
74CRYPTO_atomic_load() atomically loads the contents of *val into *ret.
75         lock will be locked, unless atomic operations are supported on the
76         specific platform. Because of this, if a variable is modified by
77         CRYPTO_atomic_or() or read by CRYPTO_atomic_load() then
78         CRYPTO_atomic_load() must be the only way that the variable is read.
79         If atomic operations are not supported and lock is NULL, then the
80         function will fail.
81

RETURN VALUES

83       CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error.
84
85       CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error.
86
87       CRYPTO_THREAD_lock_free() returns no value.
88
89       The other functions return 1 on success, or 0 on error.
90

NOTES

92       On Windows platforms the CRYPTO_THREAD_* types and functions in the
93       <openssl/crypto.h> header are dependent on some of the types
94       customarily made available by including <windows.h>. The application
95       developer is likely to require control over when the latter is
96       included, commonly as one of the first included headers. Therefore, it
97       is defined as an application developer's responsibility to include
98       <windows.h> prior to <openssl/crypto.h> where use of CRYPTO_THREAD_*
99       types and functions is required.
100

EXAMPLES

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
111       This example safely initializes and uses a lock.
112
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        }
149
150       Finalization of locks is an advanced topic, not covered in this
151       example.  This can only be done at process exit or when a dynamically
152       loaded library is no longer in use and is unloaded.  The simplest
153       solution is to just "leak" the lock in applications and not repeatedly
154       load/unload shared libraries that allocate locks.
155

SEE ALSO

157       crypto(7), openssl-threads(7).
158
160       Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
161
162       Licensed under the Apache License 2.0 (the "License").  You may not use
163       this file except in compliance with the License.  You can obtain a copy
164       in the file LICENSE in the source distribution or at
165       <https://www.openssl.org/source/license.html>.
166
167
168
1693.1.1                             2023-08-31     CRYPTO_THREAD_RUN_ONCE(3ossl)
Impressum