1 /*
2 * Copyright (c) 2017 IBM Corporation. All rights reserved.
3 * $COPYRIGHT$
4 *
5 * Additional copyrights may follow
6 *
7 * $HEADER$
8 */
9
10 /**
11 * @file
12 *
13 * The hook framework is designed to allow a component of the hook framework
14 * to be called a designated points in the MPI process lifecycle.
15 *
16 * There is not module structure in this framework since the components apply to
17 * the whole process. Further, the component might need to active before mca_init.
18 *
19 * Why not a PMPI library?
20 * - The desire is to allow a component to be built statically into the library
21 * for licensing and disgnostic purposes. As such we need the ability for
22 * the component to be statically linked into the libmpi library.
23 *
24 * Why is there not a hook for location XYZ?
25 * - The number of possible places for hooks is quite large. This framework
26 * supports a set that we think will provide the best coverage for the
27 * common use cases. If you have another use case we are always open to
28 * discussing extensions on the mailing list.
29 */
30 #ifndef MCA_HOOK_H
31 #define MCA_HOOK_H
32
33 #include "ompi_config.h"
34
35 #include "mpi.h"
36 #include "ompi/mca/mca.h"
37 #include "opal/mca/base/base.h"
38
39 BEGIN_C_DECLS
40
41 /*
42 * Some functions are specially marked. See decoder below.
43 *
44 * *** Static Only (Always) ***
45 * Only static components will ever see this callback triggered due to the
46 * position of the hook relative to ompi_mpi_init and ompi_mpi_finalize.
47 *
48 * *** Static Only (Outside MPI), Everyone (Inside MPI) ***
49 * Only static components will ever see this callback triggered when outside
50 * of the ompi_mpi_init and ompi_mpi_finalize region. Others may see this
51 * triggered if the user's program makes additional calls while inside
52 * that region.
53 *
54 * *** Everyone (Inside MPI) ***
55 * Everyone registered will see this callback triggered. It is only triggered
56 * between ompi_mpi_init and ompi_mpi_finalize.
57 *
58 */
59 /* ******************************************************************** */
60
61 /**
62 * *** Static Only (Outside MPI), Everyone (Inside MPI) ***
63 *
64 * Location: mpi/c/initialized.c
65 * At the top of function (outside of mutex)
66 */
67 typedef void (*ompi_hook_base_component_mpi_initialized_top_fn_t)(int *flag);
68
69 /**
70 * *** Static Only (Outside MPI), Everyone (Inside MPI) ***
71 *
72 * Location: mpi/c/initialized.c
73 * At the bottom of function (outside of mutex)
74 */
75 typedef void (*ompi_hook_base_component_mpi_initialized_bottom_fn_t)(int *flag);
76
77 /**
78 * *** Static Only (Outside MPI), Everyone (Inside MPI) ***
79 *
80 * Location: mpi/c/init_thread.c
81 * At the top of function
82 */
83 typedef void (*ompi_hook_base_component_mpi_init_thread_top_fn_t)(int *argc, char ***argv, int required, int *provided);
84
85 /**
86 * *** Static Only (Outside MPI), Everyone (Inside MPI) ***
87 *
88 * Location: mpi/c/init_thread.c
89 * At the bottom of function
90 */
91 typedef void (*ompi_hook_base_component_mpi_init_thread_bottom_fn_t)(int *argc, char ***argv, int required, int *provided);
92
93 /**
94 * *** Static Only (Outside MPI), Everyone (Inside MPI) ***
95 *
96 * Location: mpi/c/finalized.c
97 * At the top of function (outside of mutex)
98 */
99 typedef void (*ompi_hook_base_component_mpi_finalized_top_fn_t)(int *flag);
100
101 /**
102 * *** Static Only (Outside MPI), Everyone (Inside MPI) ***
103 *
104 * Location: mpi/c/finalized.c
105 * At the bottom of function (outside of mutex)
106 */
107 typedef void (*ompi_hook_base_component_mpi_finalized_bottom_fn_t)(int *flag);
108
109 /**
110 * *** Static Only (Always) ***
111 *
112 * Location: runtime/ompi_mpi_init.c
113 * At top of function (outside of mutex)
114 */
115 typedef void (*ompi_hook_base_component_mpi_init_top_fn_t)(int argc, char **argv, int requested, int *provided);
116
117 /**
118 * *** Everyone (Inside MPI) ***
119 *
120 * Location: runtime/ompi_mpi_init.c
121 * Just after opal_init_util and MCA initialization. (inside mutex)
122 * Notes:
123 * This framework has been opened as have its components.
124 */
125 typedef void (*ompi_hook_base_component_mpi_init_top_post_opal_fn_t)(int argc, char **argv, int requested, int *provided);
126
127 /**
128 * *** Everyone (Inside MPI) ***
129 *
130 * Location: runtime/ompi_mpi_init.c
131 * At the bottom of the function. (outside mutex)
132 * Notes:
133 * This framework has been opened as have its components.
134 * Can safely use all MPI functionality.
135 */
136 typedef void (*ompi_hook_base_component_mpi_init_bottom_fn_t)(int argc, char **argv, int requested, int *provided);
137
138 /**
139 * *** Everyone (Inside MPI) ***
140 *
141 * Location: runtime/ompi_mpi_init.c
142 * At the bottom of the error path. (outside mutex)
143 * Notes:
144 * This framework has been opened as have its components.
145 */
146 typedef void (*ompi_hook_base_component_mpi_init_error_fn_t)(int argc, char **argv, int requested, int *provided);
147
148 /**
149 * *** Everyone (Inside MPI) ***
150 *
151 * Location: runtime/ompi_mpi_finalize.c
152 * At the top of the function. (outside mutex)
153 * Notes:
154 * This framework has been opened as have its components.
155 * Can safely use all MPI functionality.
156 */
157 typedef void (*ompi_hook_base_component_mpi_finalize_top_fn_t)(void);
158
159 /**
160 * *** Static Only (Always) ***
161 *
162 * Location: runtime/ompi_mpi_finalize.c
163 * At top of function (outside of mutex)
164 * Notes:
165 * This framework has been closed.
166 */
167 typedef void (*ompi_hook_base_component_mpi_finalize_bottom_fn_t)(void);
168
169
170 /* ******************************************************************** */
171
172 /**
173 * Hook component version and interface functions.
174 */
175 struct ompi_hook_base_component_1_0_0_t {
176 mca_base_component_t hookm_version;
177 mca_base_component_data_t hookm_data;
178
179 /* MPI_Initialized */
180 ompi_hook_base_component_mpi_initialized_top_fn_t hookm_mpi_initialized_top;
181 ompi_hook_base_component_mpi_initialized_bottom_fn_t hookm_mpi_initialized_bottom;
182
183 /* MPI_Init_thread */
184 ompi_hook_base_component_mpi_init_thread_top_fn_t hookm_mpi_init_thread_top;
185 ompi_hook_base_component_mpi_init_thread_bottom_fn_t hookm_mpi_init_thread_bottom;
186
187 /* MPI_Finalized */
188 ompi_hook_base_component_mpi_finalized_top_fn_t hookm_mpi_finalized_top;
189 ompi_hook_base_component_mpi_finalized_bottom_fn_t hookm_mpi_finalized_bottom;
190
191 /* ompi_mpi_init */
192 ompi_hook_base_component_mpi_init_top_fn_t hookm_mpi_init_top;
193 ompi_hook_base_component_mpi_init_top_post_opal_fn_t hookm_mpi_init_top_post_opal;
194 ompi_hook_base_component_mpi_init_bottom_fn_t hookm_mpi_init_bottom;
195 ompi_hook_base_component_mpi_init_error_fn_t hookm_mpi_init_error;
196
197 /* ompi_mpi_finalize */
198 ompi_hook_base_component_mpi_finalize_top_fn_t hookm_mpi_finalize_top;
199 ompi_hook_base_component_mpi_finalize_bottom_fn_t hookm_mpi_finalize_bottom;
200 };
201 typedef struct ompi_hook_base_component_1_0_0_t ompi_hook_base_component_1_0_0_t;
202 typedef ompi_hook_base_component_1_0_0_t ompi_hook_base_component_t;
203 /*
204 * Note: We do -not- expose a component object for this framework.
205 * All interation with the component should go through the base/base.h interfaces.
206 * See that header for more information on calling functions.
207 */
208
209 /* ******************************************************************** */
210
211 /*
212 * Macro for use in components that are of type hook
213 */
214 #define OMPI_HOOK_BASE_VERSION_1_0_0 \
215 OMPI_MCA_BASE_VERSION_2_1_0("hook", 1, 0, 0)
216
217 END_C_DECLS
218
219 #endif /* MCA_HOOK_H */