1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2007 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2008 Sun Microsystems, Inc. All rights reserved.
14 * Copyright (c) 2010-2016 Cisco Systems, Inc. All rights reserved.
15 * Copyright (c) 2014 Intel, Inc. All rights reserved.
16 * Copyright (c) 2018 Triad National Security, LLC. All rights
17 * reserved.
18 * $COPYRIGHT$
19 *
20 * Additional copyrights may follow
21 *
22 * $HEADER$
23 */
24
25 /** @file **/
26
27 #ifndef OPAL_H
28 #define OPAL_H
29
30 #include "opal_config.h"
31 #include "opal/types.h"
32 #include "opal/class/opal_list.h"
33
34 BEGIN_C_DECLS
35
36 /** version string of opal */
37 OPAL_DECLSPEC extern const char opal_version_string[];
38
39 /* Size of a cache line. Initialized to a fixed value (see
40 opal_init.c) until hwloc data is available, at which time it is
41 filled with the smallest size of the lowest cache line (e.g., the
42 smallest line size from all L2 caches found on the current system).
43 If the hwloc data is available, opal_cache_line_size will be set to
44 its final value by the end of orte_init(). */
45 OPAL_DECLSPEC extern int opal_cache_line_size;
46
47 /** Do we want to be warned on fork or not? */
48 OPAL_DECLSPEC extern bool opal_warn_on_fork;
49
50 /**
51 * @brief list of cleanup functions that should be called as part of opal_finalize_util().
52 * opal_finalize()
53 */
54 extern opal_list_t opal_finalize_cleanup_fns;
55
56 /**
57 * Initialize the OPAL layer, including the MCA system.
58 *
59 * @retval OPAL_SUCCESS Upon success.
60 * @retval OPAL_ERROR Upon failure.
61 *
62 * \note If this function is called, opal_init_util() should *not* be
63 * called.
64 */
65 OPAL_DECLSPEC int opal_init(int* pargc, char*** pargv);
66
67 /**
68 * Finalize the OPAL layer, including the MCA system.
69 *
70 * @retval OPAL_SUCCESS Upon success.
71 * @retval OPAL_ERROR Upon failure.
72 *
73 * \note If this function is called, opal_finalize_util() should *not*
74 * be called.
75 */
76 OPAL_DECLSPEC int opal_finalize(void);
77
78 /**
79 * Initialize the OPAL layer, excluding the MCA system.
80 *
81 * @retval OPAL_SUCCESS Upon success.
82 * @retval OPAL_ERROR Upon failure.
83 *
84 * \note If this function is called, opal_init() should *not*
85 * be called.
86 */
87 OPAL_DECLSPEC int opal_init_util(int* pargc, char*** pargv);
88
89 /**
90 * Disable PSM/PSM2 signal hijacking.
91 *
92 * See comment in the function for more detail.
93 */
94 OPAL_DECLSPEC int opal_init_psm(void);
95
96 /**
97 * Finalize the OPAL layer, excluding the MCA system.
98 *
99 * @retval OPAL_SUCCESS Upon success.
100 * @retval OPAL_ERROR Upon failure.
101 *
102 * \note If this function is called, opal_finalize() should *not*
103 * be called.
104 */
105 OPAL_DECLSPEC int opal_finalize_util(void);
106
107 OPAL_DECLSPEC void opal_warn_fork(void);
108
109 /**
110 * Internal function. Only valid when called from opal_init_util().
111 */
112 OPAL_DECLSPEC int opal_register_params(void);
113
114 /* finalize cleanup */
115 /**
116 * @brief Cleanup domain
117 *
118 * Cleanup domains are made up of a list of functions that need to be
119 * called at finalize. A domain can be allocated/constructed then be
120 * passed to opal_finalize_domain_init() to give it a name. The name
121 * is optional and is used only for debugging purposes (this mean it
122 * *is* optional *but* still recommended. You can then set the
123 * finalize domain using opal_finalize_set_domain(). Once this is
124 * called all cleanup functions registered with
125 * opal_finalize_append_cleanup() will be registered to the set
126 * domain. To call the finalize functions in a domain call
127 * the opal_finalize_cleanup_domain() API.
128 */
129 struct opal_finalize_domain_t {
130 /** domains are opal lists */
131 opal_list_t super;
132 /** name of this finalize domain */
133 char *domain_name;
134 };
135 typedef struct opal_finalize_domain_t opal_finalize_domain_t;
136
137 OBJ_CLASS_DECLARATION(opal_finalize_domain_t);
138
139 /**
140 * @brief Initialize a finalize domain.
141 *
142 * @param[in] domain Finalize domain to initialize
143 * @param[in] domain_name Name for this finalize domain (may be NULL)
144 *
145 * This function sets the name of a finalize domain. The domain must
146 * have already been initialized by OBJ_CONSTRUCT() or OBJ_NEW().
147 */
148 void opal_finalize_domain_init (opal_finalize_domain_t *domain, const char *domain_name);
149
150 /**
151 * @brief Set the current finalize domain for opal_finalize_append_cleanup()
152 *
153 * @param[in] domain Finalize domain to use
154 *
155 * This function sets the current finalize domain. This API is not thread safe
156 * and is must be protected from multi-threaded invocation.
157 */
158 void opal_finalize_set_domain (opal_finalize_domain_t *domain);
159
160 /**
161 * @brief Finalize a domain
162 *
163 * @param[in] domain Finalize domain to cleanup
164 *
165 * This function calls all the finalization functions registered with the
166 * specified domain in reverse-registration order. This function releases
167 * any memory allocated by the relevant calls to opal_finalize_append_cleanup()
168 * and effectively empties the cleanup domain.
169 */
170 void opal_finalize_cleanup_domain (opal_finalize_domain_t *domain);
171
172 /**
173 * @brief Cleanup domain function
174 *
175 * The argument is optional. It is valid to use the opal_finalize_register_cleanup()
176 * macro to register a function that is of type void (*) (void).
177 */
178 typedef void (*opal_cleanup_fn_t) (void *);
179
180 /**
181 * @brief Append a cleanup function to the current domain
182 *
183 * @param[in] cleanup_fn Cleanup function to register
184 * @param[in] fn_name Name of the cleanup function (for debugging)
185 * @param[in] user_data User data to pass to the cleanup function
186 */
187 void opal_finalize_append_cleanup (opal_cleanup_fn_t cleanup_fn, const char *fn_name, void *user_data);
188
189 #define opal_finalize_register_cleanup_3(x, y, z) opal_finalize_append_cleanup((opal_cleanup_fn_t) x, y, z)
190 #define opal_finalize_register_cleanup_arg(x, y) opal_finalize_append_cleanup((opal_cleanup_fn_t) x, # x "(" #y ")", y)
191 #define opal_finalize_register_cleanup(x) opal_finalize_register_cleanup_3((opal_cleanup_fn_t) (x), # x, NULL)
192
193 /* opal cleanup domains */
194 extern opal_finalize_domain_t opal_init_util_domain;
195 extern opal_finalize_domain_t opal_init_domain;
196
197
198 END_C_DECLS
199
200 #endif