OpenMPI  0.1.1
op.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2010 The University of Tennessee and The University
6  * of Tennessee Research Foundation. All rights
7  * reserved.
8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9  * University of Stuttgart. All rights reserved.
10  * Copyright (c) 2004-2005 The Regents of the University of California.
11  * All rights reserved.
12  * Copyright (c) 2006-2007 Los Alamos National Security, LLC. All rights
13  * reserved.
14  * Copyright (c) 2007-2008 UT-Battelle, LLC
15  * Copyright (c) 2007-2009 Cisco Systems, Inc. All rights reserved.
16  * $COPYRIGHT$
17  *
18  * Additional copyrights may follow
19  *
20  * $HEADER$
21  */
22 /**
23  * @file
24  *
25  * MPI_Op back-end operation framework. This framework allows
26  * component-izing the back-end operations of MPI_Op in order to use
27  * specialized hardware (e.g., mathematical accelerators). In short:
28  * each MPI_Op contains a table of function pointers; one for
29  * implementing the operation on each predefined datatype.
30  *
31  * The MPI interface provides error checking and error handler
32  * invocation, but the op components provide all other functionality.
33  *
34  * Component selection is done on a per-MPI_Op basis when each MPI_Op
35  * is created. All MPI_Ops go through the selection process, even
36  * user-defined MPI_Ops -- although it is expected that most (all?)
37  * op components will only be able to handle the predefined MPI_Ops.
38  *
39  * The general sequence of usage for the op framework is:
40  *
41  * 1. ompi_op_base_open() is invoked during MPI_INIT to find/open all
42  * op components.
43  *
44  * 2. ompi_op_base_find_available() is invoked during MPI_INIT to call
45  * each successfully opened op component's opc_init_query() function.
46  * All op components that return OMPI_SUCCESS are kept; all others are
47  * closed and removed from the process.
48  *
49  * 3. ompi_op_base_op_select() is invoked during MPI_INIT for each
50  * predefined MPI_Op (e.g., MPI_SUM). This function will call each
51  * available op component's opc_op_query() function to see if this
52  * component wants to provide a module for one or more of the function
53  * pointers on this MPI_Op. Priorities are used to rank returned
54  * modules; the module with the highest priority has its function
55  * pointers set in the MPI_Op function table.
56  *
57  * Note that a module may only have *some* non-NULL function pointers
58  * (i.e., for the functions that it can support). For example, some
59  * modules may only support operations on single-precision floating
60  * point datatypes. These modules would provide function pointers for
61  * these datatypes and NULL for all the rest. The op framework will
62  * mix-n-match function pointers between modules to obtain a full set
63  * of non-NULL function pointers for a given MPI_Op (note that the op
64  * base provides a complete set of functions for the MPI_Op, usually a
65  * simple C loop around the operation, such as "+=" -- so even if
66  * there is no specialized op component available, there will *always*
67  * be a full set of MPI_Op function pointers). The op framework will
68  * OBJ_RETAIN an op module once for each function pointer where it is
69  * used on a given MPI_Op.
70  *
71  * Note that this scheme can result in up to N different modules being
72  * used for a single MPI_Op, one per needed datatype function.
73  *
74  * 5. Finally, during MPI_FINALIZE, ompi_op_base_close() is invoked to
75  * close all available op components.
76  */
77 
78 #ifndef MCA_OP_H
79 #define MCA_OP_H
80 
81 #include "ompi_config.h"
82 
83 #include "opal/class/opal_object.h"
84 #include "opal/mca/mca.h"
85 
86 /*
87  * This file includes some basic struct declarations (but not
88  * definitions) just so that we can avoid including files like op/op.h
89  * and datatype/datatype.h, which would create #include file loops.
90  */
91 #include "ompi/types.h"
92 
93 BEGIN_C_DECLS
94 
95 /**
96  * Corresponding to the types that we can reduce over. See
97  * MPI-1:4.9.2, p114-115 and
98  * MPI-2:4.15, p76-77
99  */
100 enum {
101  /** C integer: int8_t */
103  /** C integer: uint8_t */
105  /** C integer: int16_t */
107  /** C integer: uint16_t */
109  /** C integer: int32_t */
111  /** C integer: uint32_t */
113  /** C integer: int64_t */
115  /** C integer: uint64_t */
117 
118  /** Fortran integer */
120  /** Fortran integer*1 */
122  /** Fortran integer*2 */
124  /** Fortran integer*4 */
126  /** Fortran integer*8 */
128  /** Fortran integer*16 */
130 
131  /** Floating point: float */
133  /** Floating point: double */
135  /** Floating point: real */
137  /** Floating point: real*2 */
139  /** Floating point: real*4 */
141  /** Floating point: real*8 */
143  /** Floating point: real*16 */
145  /** Floating point: double precision */
147  /** Floating point: long double */
149 
150  /** Logical */
152  /** Bool */
154 
155  /** Complex */
157  /** Double complex */
159  /** Complex8 */
161  /** Complex16 */
163  /** Complex32 */
165 
166  /** Byte */
168 
169  /** 2 location Fortran: 2 real */
171  /** 2 location Fortran: 2 double precision */
173  /** 2 location Fortran: 2 integer */
175 
176  /** 2 location C: float int */
178  /** 2 location C: double int */
180  /** 2 location C: long int */
182  /** 2 location C: int int */
184  /** 2 location C: short int */
186  /** 2 location C: long double int */
188 
189  /** 2 location C: wchar_t */
191 
192  /** Maximum type */
194 };
195 
196 
197 /**
198  * Fortran handles; must be [manually set to be] equivalent to the
199  * values in mpif.h.
200  */
201 enum {
202  /** Corresponds to Fortran MPI_OP_NULL */
204  /** Corresponds to Fortran MPI_MAX */
206  /** Corresponds to Fortran MPI_MIN */
208  /** Corresponds to Fortran MPI_SUM */
210  /** Corresponds to Fortran MPI_PROD */
212  /** Corresponds to Fortran MPI_LAND */
214  /** Corresponds to Fortran MPI_BAND */
216  /** Corresponds to Fortran MPI_LOR */
218  /** Corresponds to Fortran MPI_BOR */
220  /** Corresponds to Fortran MPI_LXOR */
222  /** Corresponds to Fortran MPI_BXOR */
224  /** Corresponds to Fortran MPI_MAXLOC */
226  /** Corresponds to Fortran MPI_MINLOC */
228  /** Corresponds to Fortran MPI_REPLACE */
230 
231  /** Maximum value */
233 };
234 
235 /**
236  * Pre-declare this so that we can pass it as an argument to the
237  * typedef'ed functions.
238  */
240 
242 
243 /**
244  * Typedef for 2-buffer op functions.
245  *
246  * We don't use MPI_User_function because this would create a
247  * confusing dependency loop between this file and mpi.h. So this is
248  * repeated code, but it's better this way (and this typedef will
249  * never change, so there's not much of a maintenance worry).
250  */
251 typedef void (*ompi_op_base_handler_fn_1_0_0_t)(void *, void *, int *,
252  struct ompi_datatype_t **,
253  struct ompi_op_base_module_1_0_0_t *);
254 
255 typedef ompi_op_base_handler_fn_1_0_0_t ompi_op_base_handler_fn_t;
256 
257 /*
258  * Typedef for 3-buffer (two input and one output) op functions.
259  */
260 typedef void (*ompi_op_base_3buff_handler_fn_1_0_0_t)(void *,
261  void *,
262  void *, int *,
263  struct ompi_datatype_t **,
264  struct ompi_op_base_module_1_0_0_t *);
265 
266 typedef ompi_op_base_3buff_handler_fn_1_0_0_t ompi_op_base_3buff_handler_fn_t;
267 
268 /**
269  * Op component initialization
270  *
271  * Initialize the given op component. This function should initialize
272  * any component-level. data. It will be called exactly once during
273  * MPI_INIT.
274  *
275  * @note The component framework is not lazily opened, so attempts
276  * should be made to minimze the amount of memory allocated during
277  * this function.
278  *
279  * @param[in] enable_progress_threads True if the component needs to
280  * support progress threads
281  * @param[in] enable_mpi_threads True if the component needs to
282  * support MPI_THREAD_MULTIPLE
283  *
284  * @retval OMPI_SUCCESS Component successfully initialized
285  * @retval OMPI_ERROR An unspecified error occurred
286  */
288  (bool enable_progress_threads, bool enable_mpi_threads);
289 
290 
291 /**
292  * Query whether a component is available for a specific MPI_Op.
293  *
294  * If the component is available, an object should be allocated and
295  * returned (with refcount at 1). The module will not be used for
296  * reduction operations until module_enable() is called on the module,
297  * but may be destroyed (via OBJ_RELEASE) either before or after
298  * module_enable() is called. If the module needs to release
299  * resources obtained during query(), it should do so in the module
300  * destructor.
301  *
302  * A component may provide NULL to this function to indicate it does
303  * not wish to run or return an error during module_enable().
304  *
305  * @param[in] op The MPI_Op being created
306  * @param[out] priority Priority setting for component on
307  * this op
308  *
309  * @returns An initialized module structure if the component can
310  * provide a module with the requested functionality or NULL if the
311  * component should not be used on the given communicator.
312  */
313 typedef struct ompi_op_base_module_1_0_0_t *
314  (*ompi_op_base_component_op_query_1_0_0_fn_t)
315  (struct ompi_op_t *op, int *priority);
316 
317 /**
318  * Op component interface.
319  *
320  * Component interface for the op framework. A public instance of
321  * this structure, called mca_op_[component_name]_component, must
322  * exist in any op component.
323  */
325  /** Base component description */
327  /** Base component data block */
329 
330  /** Component initialization function */
332  /** Query whether component is useable for given op */
335 
336 
337 /** Per guidence in mca.h, use the unversioned struct name if you just
338  want to always keep up with the most recent version of the
339  interace. */
341 
342 /**
343  * Module initialization function. Should return OPAL_SUCCESS if
344  * everything goes ok. This function can be NULL in the module struct
345  * if the module doesn't need to do anything between the component
346  * query function and being invoked for MPI_Op operations.
347  */
350  struct ompi_op_t *op);
351 
352 /**
353  * Module struct
354  */
356  /** Op modules all inherit from opal_object */
358 
359  /** Enable function called when an op module is (possibly) going
360  to be used for the given MPI_Op */
362 
363  /** Just for reference -- a pointer to the MPI_Op that this module
364  is being used for */
365  struct ompi_op_t *opm_op;
366 
367  /** Function pointers for all the different datatypes to be used
368  with the MPI_Op that this module is used with */
370  ompi_op_base_3buff_handler_fn_1_0_0_t opm_3buff_fns[OMPI_OP_BASE_TYPE_MAX];
372 
373 /**
374  * Declare the module as a class, unversioned
375  */
377 
378 /**
379  * Declare the module as a class, unversioned
380  */
382 
383 /**
384  * Struct that is used in op.h to hold all the function pointers and
385  * pointers to the corresopnding modules (so that we can properly
386  * RETAIN/RELEASE them)
387  */
392 
394 
395 /**
396  * Struct that is used in op.h to hold all the function pointers and
397  * pointers to the corresopnding modules (so that we can properly
398  * RETAIN/RELEASE them)
399  */
401  ompi_op_base_3buff_handler_fn_1_0_0_t fns[OMPI_OP_BASE_TYPE_MAX];
404 
406 
407 /*
408  * Macro for use in modules that are of type op v2.0.0
409  */
410 #define OMPI_OP_BASE_VERSION_1_0_0 \
411  MCA_BASE_VERSION_2_0_0, \
412  "op", 1, 0, 0
413 
414 END_C_DECLS
415 
416 #endif /* OMPI_MCA_OP_H */
Struct that is used in op.h to hold all the function pointers and pointers to the corresopnding modul...
Definition: op.h:400
C integer: uint16_t.
Definition: op.h:108
Corresponds to Fortran MPI_BXOR.
Definition: op.h:223
2 location C: long double int
Definition: op.h:187
Floating point: float.
Definition: op.h:132
Common type for all MCA components.
Definition: mca.h:250
Corresponds to Fortran MPI_BAND.
Definition: op.h:215
2 location Fortran: 2 real
Definition: op.h:170
Module struct.
Definition: op.h:355
Fortran integer.
Definition: op.h:119
ompi_op_base_component_op_query_1_0_0_fn_t opc_op_query
Query whether component is useable for given op.
Definition: op.h:333
C integer: uint32_t.
Definition: op.h:112
2 location C: wchar_t
Definition: op.h:190
Definition: ompi_datatype.h:68
2 location C: long int
Definition: op.h:181
OMPI_DECLSPEC OBJ_CLASS_DECLARATION(ompi_op_base_module_t)
Declare the module as a class, unversioned.
Struct that is used in op.h to hold all the function pointers and pointers to the corresopnding modul...
Definition: op.h:388
Corresponds to Fortran MPI_REPLACE.
Definition: op.h:229
Fortran integer*8.
Definition: op.h:127
struct ompi_op_base_module_1_0_0_t *(* ompi_op_base_component_op_query_1_0_0_fn_t)(struct ompi_op_t *op, int *priority)
Query whether a component is available for a specific MPI_Op.
Definition: op.h:315
Op component interface.
Definition: op.h:324
Corresponds to Fortran MPI_OP_NULL.
Definition: op.h:203
int(* ompi_op_base_component_init_query_fn_t)(bool enable_progress_threads, bool enable_mpi_threads)
Op component initialization.
Definition: op.h:288
opal_object_t super
Op modules all inherit from opal_object.
Definition: op.h:357
Bool.
Definition: op.h:153
Corresponds to Fortran MPI_MAXLOC.
Definition: op.h:225
Corresponds to Fortran MPI_LAND.
Definition: op.h:213
Corresponds to Fortran MPI_MAX.
Definition: op.h:205
C integer: int8_t.
Definition: op.h:102
2 location C: short int
Definition: op.h:185
Logical.
Definition: op.h:151
Corresponds to Fortran MPI_LOR.
Definition: op.h:217
Fortran integer*16.
Definition: op.h:129
Floating point: real*4.
Definition: op.h:140
Maximum value.
Definition: op.h:232
Top-level interface for all MCA components.
Floating point: real*2.
Definition: op.h:138
2 location Fortran: 2 double precision
Definition: op.h:172
struct ompi_op_base_op_fns_1_0_0_t ompi_op_base_op_fns_1_0_0_t
Struct that is used in op.h to hold all the function pointers and pointers to the corresopnding modul...
Floating point: real.
Definition: op.h:136
Maximum type.
Definition: op.h:193
2 location C: int int
Definition: op.h:183
Corresponds to Fortran MPI_LXOR.
Definition: op.h:221
Fortran integer*4.
Definition: op.h:125
mca_base_component_t opc_version
Base component description.
Definition: op.h:326
ompi_op_base_component_init_query_fn_t opc_init_query
Component initialization function.
Definition: op.h:331
Fortran integer*2.
Definition: op.h:123
Corresponds to Fortran MPI_BOR.
Definition: op.h:219
struct ompi_op_base_component_1_0_0_t ompi_op_base_component_1_0_0_t
Op component interface.
int(* ompi_op_base_module_enable_1_0_0_fn_t)(struct ompi_op_base_module_1_0_0_t *module, struct ompi_op_t *op)
Module initialization function.
Definition: op.h:349
Complex16.
Definition: op.h:162
2 location Fortran: 2 integer
Definition: op.h:174
void(* ompi_op_base_handler_fn_1_0_0_t)(void *, void *, int *, struct ompi_datatype_t **, struct ompi_op_base_module_1_0_0_t *)
Typedef for 2-buffer op functions.
Definition: op.h:251
ompi_op_base_handler_fn_1_0_0_t opm_fns[OMPI_OP_BASE_TYPE_MAX]
Function pointers for all the different datatypes to be used with the MPI_Op that this module is used...
Definition: op.h:369
Corresponds to Fortran MPI_PROD.
Definition: op.h:211
Corresponds to Fortran MPI_SUM.
Definition: op.h:209
struct ompi_op_base_module_1_0_0_t ompi_op_base_module_1_0_0_t
Module struct.
Base object.
Definition: opal_object.h:182
C integer: int32_t.
Definition: op.h:110
Meta data for MCA v2.0.0 components.
Definition: mca.h:309
Floating point: real*16.
Definition: op.h:144
ompi_op_base_module_enable_1_0_0_fn_t opm_enable
Enable function called when an op module is (possibly) going to be used for the given MPI_Op...
Definition: op.h:361
mca_base_component_data_t opc_data
Base component data block.
Definition: op.h:328
Floating point: real*8.
Definition: op.h:142
Corresponds to Fortran MPI_MIN.
Definition: op.h:207
2 location C: double int
Definition: op.h:179
struct ompi_op_base_op_3buff_fns_1_0_0_t ompi_op_base_op_3buff_fns_1_0_0_t
Struct that is used in op.h to hold all the function pointers and pointers to the corresopnding modul...
Complex32.
Definition: op.h:164
C integer: int64_t.
Definition: op.h:114
Complex.
Definition: op.h:156
Floating point: double precision.
Definition: op.h:146
2 location C: float int
Definition: op.h:177
C integer: int16_t.
Definition: op.h:106
Byte.
Definition: op.h:167
C integer: uint64_t.
Definition: op.h:116
Floating point: long double.
Definition: op.h:148
Floating point: double.
Definition: op.h:134
Complex8.
Definition: op.h:160
A simple C-language object-oriented system with single inheritance and ownership-based memory managem...
struct ompi_op_t * opm_op
Just for reference – a pointer to the MPI_Op that this module is being used for. ...
Definition: op.h:365
Fortran integer*1.
Definition: op.h:121
Back-end type of MPI_Op.
Definition: op.h:100
Corresponds to Fortran MPI_MINLOC.
Definition: op.h:227
Double complex.
Definition: op.h:158
C integer: uint8_t.
Definition: op.h:104