OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

base.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
3 * University Research and Technology
4 * Corporation. All rights reserved.
5 * Copyright (c) 2004-2005 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) 2010-2012 Oak Ridge National Labs. All rights reserved.
13 * $COPYRIGHT$
14 *
15 * Additional copyrights may follow
16 *
17 * $HEADER$
18 *
19 */
20
21 /** @file
22 * MCA coll base framework public interface functions.
23 *
24 * These functions are normally invoked by the back-ends of:
25 *
26 * - The back-ends of MPI_Init() and MPI_Finalize()
27 * - Communuicactor constructors (e.g., MPI_Comm_split()) and
28 * destructors (e.g., MPI_Comm_free())
29 * - The laminfo command
30 */
31
32 #ifndef MCA_COLL_BASE_H
33 #define MCA_COLL_BASE_H
34
35 #include "ompi_config.h"
36
37 #include "mpi.h"
38 #include "opal/class/opal_list.h"
39 #if OPAL_ENABLE_FT_MPI
40 #include "ompi/mca/coll/coll.h"
41 #endif
42
43 /*
44 * Global functions for MCA overall collective open and close
45 */
46
47 BEGIN_C_DECLS
48 /**
49 * Initialize the coll MCA framework
50 *
51 * @retval OMPI_SUCCESS Upon success
52 * @retval OMPI_ERROR Upon failure
53 *
54 * This must be the first function invoked in the coll MCA
55 * framework. It initializes the coll MCA framework, finds and
56 * opens coll components, etc.
57 *
58 * This function is invoked during ompi_mpi_init() and during the
59 * initialization of the special case of the laminfo command.
60 *
61 * This function fills in the internal global variable
62 * mca_coll_base_components_opened, which is a list of all coll components
63 * that were successfully opened. This variable should \em only be
64 * used by other coll base functions -- it is not considered a
65 * public interface member -- and is only mentioned here for
66 * completeness.
67 */
68 OMPI_DECLSPEC int mca_coll_base_open(void);
69
70 /**
71 * Create list of available coll components.
72 *
73 * @param allow_multi_user_threads Will be set to true if any of the
74 * available components will allow multiple user threads
75 * @param have_hidden_threads Will be set to true if any of the
76 * available components have hidden threads.
77 *
78 * @retval OMPI_SUCCESS If one or more coll components are available.
79 * @retval OMPI_ERROR If no coll components are found to be available.
80 *
81 * This function is invoked during ompi_mpi_init() to query all
82 * successfully opened coll components and create a list of all
83 * available coll components.
84 *
85 * This function traverses the (internal global variable)
86 * mca_coll_base_components_opened list and queries each component to see
87 * if it ever might want to run during this MPI process. It creates
88 * another internal global variable list named
89 * mca_coll_base_components_available, consisting of a list of components
90 * that are available for selection when communicators are created.
91 * This variable should \em only be used by other coll base
92 * functions -- it is not considered a public interface member --
93 * and is only mentioned here for completeness.
94 */
95 int mca_coll_base_find_available(bool enable_progress_threads,
96 bool enable_mpi_threads);
97
98 /**
99 * Select an available component for a new communicator.
100 *
101 * @param comm Communicator that the component will be selected for.
102 * @param preferred The component that is preferred for this
103 * communicator (or NULL).
104 *
105 * @return OMPI_SUCCESS Upon success.
106 * @return OMPI_ERROR Upon failure.
107 *
108 * Note that the types of the parameters have "struct" in them
109 * (e.g., ompi_communicator_t" vs. a plain "ompi_communicator_t") to
110 * avoid an include file loop. All similar types (e.g., "struct
111 * ompi_communicator_t *", "ompi_communicator_t *", and "MPI_Comm")
112 * are all typedef'ed to be the same, so the fact that we use struct
113 * here in the prototype is ok.
114 *
115 * This function is invoked when a new communicator is created and a
116 * coll component needs to be selected for it. It should be invoked
117 * near the end of the communicator creation process such that
118 * almost everything else is functional on the communicator (e.g.,
119 * point-to-point communication).
120 *
121 * Note that new communicators may be created as a result of
122 * invoking this function. Specifically: this function is called in
123 * the depths of communicator creation, but during the execution of
124 * this function, new communicators may be created, and therefore
125 * communicator creation functions may be re-entered (albiet with
126 * different arguments).
127 */
128 int mca_coll_base_comm_select(struct ompi_communicator_t *comm);
129
130 /**
131 * Finalize a coll component on a specific communicator.
132 *
133 * @param comm The communicator that is being destroyed.
134 *
135 * @retval OMPI_SUCCESS Always.
136 *
137 * Note that the type of the parameter is only a "struct
138 * ompi_communicator_t" (vs. a plain "ompi_communicator_t") to avoid
139 * an include file loop. The types "struct ompi_communicator_t *",
140 * "ompi_communicator_t *", and "MPI_Comm" are all typedef'ed to be
141 * the same, so the fact that we use struct here in the prototype is
142 * ok.
143 *
144 * This function is invoked near the beginning of the destruction of
145 * a communicator. It finalizes the coll component associated with the
146 * communicator (e.g., allowing the component to clean up and free any
147 * resources allocated for that communicator). Note that similar to
148 * mca_coll_base_select(), as result of this function, other
149 * communicators may also be destroyed.
150 */
151 int mca_coll_base_comm_unselect(struct ompi_communicator_t *comm);
152
153 /**
154 * Shut down the coll MCA framework.
155 *
156 * @retval OMPI_SUCCESS Always
157 *
158 * This function shuts down everything in the coll MCA framework,
159 * and is called during ompi_mpi_finalize() and the special case of
160 * the laminfo command.
161 *
162 * It must be the last function invoked on the coll MCA framework.
163 */
164 OMPI_DECLSPEC int mca_coll_base_close(void);
165
166 #if OPAL_ENABLE_FT_MPI
167 /*
168 * These are dummy functions for those modules that choose not to
169 * implement these functions.
170 */
171 OMPI_DECLSPEC int mca_coll_base_agreement(struct ompi_communicator_t* comm,
172 struct ompi_group_t **group,
173 int *flag,
174 struct mca_coll_base_module_2_0_0_t *module);
175 OMPI_DECLSPEC int mca_coll_base_iagreement(struct ompi_communicator_t* comm,
176 struct ompi_group_t **group,
177 int *flag,
178 struct mca_coll_base_module_2_0_0_t *module,
179 ompi_request_t **request);
180 #endif /* OPAL_ENABLE_FT_MPI */
181
182 /*
183 * Globals
184 */
185
186 /**
187 * Coll framework debugging stream ID used with opal_output() and
188 * opal_output_verbose().
189 */
190 OMPI_DECLSPEC extern int mca_coll_base_output;
191
192 /**
193 * Indicator as to whether the list of opened coll components is valid or
194 * not.
195 */
196 extern bool mca_coll_base_components_opened_valid;
197
198 /**
199 * List of all opened components; created when the coll framework is
200 * initialized and destroyed when we reduce the list to all available
201 * coll components.
202 */
203 OMPI_DECLSPEC extern opal_list_t mca_coll_base_components_opened;
204
205 /**
206 * Indicator as to whether the list of available coll components is valid
207 * or not.
208 */
209 extern bool mca_coll_base_components_available_valid;
210
211 /**
212 * List of all available components; created by reducing the list of open
213 * components to all those who indicate that they may run during this
214 * process.
215 */
216 extern opal_list_t mca_coll_base_components_available;
217
218 END_C_DECLS
219 #endif /* MCA_BASE_COLL_H */
mca_coll_base_components_available
opal_list_t mca_coll_base_components_available
List of all available components; created by reducing the list of open components to all those who in...
Definition: coll_base_find_available.c:42
mca_coll_base_module_2_0_0_t
Collective module interface.
Definition: coll.h:316
mca_coll_base_comm_unselect
int mca_coll_base_comm_unselect(struct ompi_communicator_t *comm)
Finalize a coll component on a specific communicator.
Definition: coll_base_comm_unselect.c:42
mca_coll_base_comm_select
int mca_coll_base_comm_select(struct ompi_communicator_t *comm)
Select an available component for a new communicator.
Definition: coll_base_comm_select.c:98
mca_coll_base_output
OMPI_DECLSPEC int mca_coll_base_output
Coll framework debugging stream ID used with opal_output() and opal_output_verbose().
Definition: coll_base_open.c:51
opal_list.h
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
mca_coll_base_close
OMPI_DECLSPEC int mca_coll_base_close(void)
Shut down the coll MCA framework.
Definition: coll_base_close.c:29
coll.h
Collective Communication Interface.
mca_coll_base_components_opened
OMPI_DECLSPEC opal_list_t mca_coll_base_components_opened
List of all opened components; created when the coll framework is initialized and destroyed when we r...
Definition: coll_base_open.c:57
mca_coll_base_components_opened_valid
bool mca_coll_base_components_opened_valid
Indicator as to whether the list of opened coll components is valid or not.
Definition: coll_base_open.c:56
ompi_group_t
Group structure Currently we have four formats for storing the process pointers that are members of t...
Definition: group.h:79
opal_list_t
Definition: opal_list.h:147
mca_coll_base_open
BEGIN_C_DECLS OMPI_DECLSPEC int mca_coll_base_open(void)
Initialize the coll MCA framework.
Definition: coll_base_open.c:65
request
Definition: evdns.c:158
mca_coll_base_components_available_valid
bool mca_coll_base_components_available_valid
Indicator as to whether the list of available coll components is valid or not.
Definition: coll_base_find_available.c:41
ompi_communicator_t
Definition: communicator.h:118
ompi_request_t
Main top-level request struct definition.
Definition: request.h:100
mca_coll_base_find_available
int mca_coll_base_find_available(bool enable_progress_threads, bool enable_mpi_threads)
Create list of available coll components.
Definition: coll_base_find_available.c:70