OpenMPI  0.1.1
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  */
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  */
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,
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  */
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  */
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  */
217 
218 END_C_DECLS
219 #endif /* MCA_BASE_COLL_H */
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
Collective module interface.
Definition: coll.h:316
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
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
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
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
OMPI_DECLSPEC int mca_coll_base_close(void)
Shut down the coll MCA framework.
Definition: coll_base_close.c:29
Collective Communication Interface.
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
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
Group structure Currently we have four formats for storing the process pointers that are members of t...
Definition: group.h:79
Definition: opal_list.h:147
BEGIN_C_DECLS OMPI_DECLSPEC int mca_coll_base_open(void)
Initialize the coll MCA framework.
Definition: coll_base_open.c:65
Definition: evdns.c:158
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
Definition: communicator.h:118
Main top-level request struct definition.
Definition: request.h:100
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