[test] ectest: check custom generators
[openssl.git] / include / internal / thread_once.h
1 /*
2  * Copyright 1995-2020 The OpenSSL Project Authors. All Rights Reserved.
3  *
4  * Licensed under the Apache License 2.0 (the "License").  You may not use
5  * this file except in compliance with the License.  You can obtain a copy
6  * in the file LICENSE in the source distribution or at
7  * https://www.openssl.org/source/license.html
8  */
9
10 #include <openssl/crypto.h>
11
12 /*
13  * Initialisation of global data should never happen via "RUN_ONCE" inside the
14  * FIPS module. Global data should instead always be associated with a specific
15  * OPENSSL_CTX object. In this way data will get cleaned up correctly when the
16  * module gets unloaded.
17  */
18 #if !defined(FIPS_MODULE) || defined(ALLOW_RUN_ONCE_IN_FIPS)
19 /*
20  * DEFINE_RUN_ONCE: Define an initialiser function that should be run exactly
21  * once. It takes no arguments and returns and int result (1 for success or
22  * 0 for failure). Typical usage might be:
23  *
24  * DEFINE_RUN_ONCE(myinitfunc)
25  * {
26  *     do_some_initialisation();
27  *     if (init_is_successful())
28  *         return 1;
29  *
30  *     return 0;
31  * }
32  */
33 # define DEFINE_RUN_ONCE(init)                   \
34     static int init(void);                     \
35     int init##_ossl_ret_ = 0;                   \
36     void init##_ossl_(void)                     \
37     {                                           \
38         init##_ossl_ret_ = init();              \
39     }                                           \
40     static int init(void)
41
42 /*
43  * DECLARE_RUN_ONCE: Declare an initialiser function that should be run exactly
44  * once that has been defined in another file via DEFINE_RUN_ONCE().
45  */
46 # define DECLARE_RUN_ONCE(init)                  \
47     extern int init##_ossl_ret_;                \
48     void init##_ossl_(void);
49
50 /*
51  * DEFINE_RUN_ONCE_STATIC: Define an initialiser function that should be run
52  * exactly once. This function will be declared as static within the file. It
53  * takes no arguments and returns and int result (1 for success or 0 for
54  * failure). Typical usage might be:
55  *
56  * DEFINE_RUN_ONCE_STATIC(myinitfunc)
57  * {
58  *     do_some_initialisation();
59  *     if (init_is_successful())
60  *         return 1;
61  *
62  *     return 0;
63  * }
64  */
65 # define DEFINE_RUN_ONCE_STATIC(init)            \
66     static int init(void);                     \
67     static int init##_ossl_ret_ = 0;            \
68     static void init##_ossl_(void)              \
69     {                                           \
70         init##_ossl_ret_ = init();              \
71     }                                           \
72     static int init(void)
73
74 /*
75  * DEFINE_RUN_ONCE_STATIC_ALT: Define an alternative initialiser function. This
76  * function will be declared as static within the file. It takes no arguments
77  * and returns and int result (1 for success or 0 for failure). An alternative
78  * initialiser function is expected to be associated with a primary initialiser
79  * function defined via DEFINE_ONCE_STATIC where both functions use the same
80  * CRYPTO_ONCE object to synchronise. Where an alternative initialiser function
81  * is used only one of the primary or the alternative initialiser function will
82  * ever be called - and that function will be called exactly once. Definition
83  * of an alternative initialiser function MUST occur AFTER the definition of the
84  * primary initialiser function.
85  *
86  * Typical usage might be:
87  *
88  * DEFINE_RUN_ONCE_STATIC(myinitfunc)
89  * {
90  *     do_some_initialisation();
91  *     if (init_is_successful())
92  *         return 1;
93  *
94  *     return 0;
95  * }
96  *
97  * DEFINE_RUN_ONCE_STATIC_ALT(myaltinitfunc, myinitfunc)
98  * {
99  *     do_some_alternative_initialisation();
100  *     if (init_is_successful())
101  *         return 1;
102  *
103  *     return 0;
104  * }
105  */
106 # define DEFINE_RUN_ONCE_STATIC_ALT(initalt, init) \
107     static int initalt(void);                     \
108     static void initalt##_ossl_(void)             \
109     {                                             \
110         init##_ossl_ret_ = initalt();             \
111     }                                             \
112     static int initalt(void)
113
114 /*
115  * RUN_ONCE - use CRYPTO_THREAD_run_once, and check if the init succeeded
116  * @once: pointer to static object of type CRYPTO_ONCE
117  * @init: function name that was previously given to DEFINE_RUN_ONCE,
118  *        DEFINE_RUN_ONCE_STATIC or DECLARE_RUN_ONCE.  This function
119  *        must return 1 for success or 0 for failure.
120  *
121  * The return value is 1 on success (*) or 0 in case of error.
122  *
123  * (*) by convention, since the init function must return 1 on success.
124  */
125 # define RUN_ONCE(once, init)                                            \
126     (CRYPTO_THREAD_run_once(once, init##_ossl_) ? init##_ossl_ret_ : 0)
127
128 /*
129  * RUN_ONCE_ALT - use CRYPTO_THREAD_run_once, to run an alternative initialiser
130  *                function and check if that initialisation succeeded
131  * @once:    pointer to static object of type CRYPTO_ONCE
132  * @initalt: alternative initialiser function name that was previously given to
133  *           DEFINE_RUN_ONCE_STATIC_ALT.  This function must return 1 for
134  *           success or 0 for failure.
135  * @init:    primary initialiser function name that was previously given to
136  *           DEFINE_RUN_ONCE_STATIC.  This function must return 1 for success or
137  *           0 for failure.
138  *
139  * The return value is 1 on success (*) or 0 in case of error.
140  *
141  * (*) by convention, since the init function must return 1 on success.
142  */
143 # define RUN_ONCE_ALT(once, initalt, init)                               \
144     (CRYPTO_THREAD_run_once(once, initalt##_ossl_) ? init##_ossl_ret_ : 0)
145
146 #endif /* FIPS_MODULE */