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) 2008 Cisco Systems, Inc. All rights reserved.
13 * $COPYRIGHT$
14 *
15 * Additional copyrights may follow
16 *
17 * $HEADER$
18 */
19
20 /**
21 * @file
22 *
23 * MCA io base framework public interface functions.
24 */
25
26 #ifndef MCA_IO_BASE_H
27 #define MCA_IO_BASE_H
28
29 #include "ompi_config.h"
30
31 #include "mpi.h"
32 #include "opal/class/opal_list.h"
33 #include "ompi/class/ompi_free_list.h"
34 #include "ompi/mca/io/io.h"
35
36
37 /*
38 * Global functions for MCA overall io open and close
39 */
40
41 BEGIN_C_DECLS
42 /**
43 * Initialize the io MCA framework
44 *
45 * @retval OMPI_SUCCESS Upon success
46 * @retval OMPI_ERROR Upon failure
47 *
48 * This must be the first function invoked in the io MCA
49 * framework. It initializes the io MCA framework, finds and
50 * opens io components, etc.
51 *
52 * This function is invoked during ompi_mpi_init() and during the
53 * initialization of the special case of the laminfo command.
54 *
55 * This function fills in the internal global variable
56 * mca_io_base_components_opened, which is a list of all io components
57 * that were successfully opened. This variable should \em only be
58 * used by other io base functions -- it is not considered a
59 * public interface member -- and is only mentioned here for
60 * completeness.
61 */
62 OMPI_DECLSPEC int mca_io_base_open(void);
63
64 /**
65 * Create list of available io components.
66 *
67 * @param allow_multi_user_threads Will be set to true if any of the
68 * available components will allow multiple user threads
69 * @param have_hidden_threads Will be set to true if any of the
70 * available components have hidden threads.
71 *
72 * @retval OMPI_SUCCESS If one or more io components are available.
73 * @retval OMPI_ERROR If no io components are found to be available.
74 *
75 * This function is invoked during ompi_mpi_init() to query all
76 * successfully opened io components and create a list of all
77 * available io components.
78 *
79 * This function traverses the (internal global variable)
80 * mca_io_base_components_opened list and queries each component to see
81 * if it ever might want to run during this MPI process. It creates
82 * another internal global variable list named
83 * mca_io_base_components_available, consisting of a list of components
84 * that are available for selection when file handles are created.
85 * This variable should \em only be used by other io base
86 * functions -- it is not considered a public interface member --
87 * and is only mentioned here for completeness.
88 */
89 OMPI_DECLSPEC int mca_io_base_find_available(bool enable_progress_threads,
90 bool enable_mpi_threads);
91
92 /**
93 * Select an available component for a new file handle.
94 *
95 * @param file File Handle that the component will be selected for.
96 * @param preferred The component that is preferred for this
97 * file handle (or NULL).
98 *
99 * @return OMPI_SUCCESS Upon success.
100 * @return OMPI_ERROR Upon failure.
101 *
102 * Note that the types of the parameters have "struct" in them
103 * (e.g., ompi_file_t" vs. a plain "ompi_file_t") to
104 * avoid an include file loop. All similar types (e.g., "struct
105 * ompi_file_t *", "ompi_file_t *", and "MPI_File")
106 * are all typedef'ed to be the same, so the fact that we use struct
107 * here in the prototype is ok.
108 *
109 * This function is invoked when a new file handle is created and a
110 * io component needs to be selected for it. It should be invoked
111 * near the end of the file handle creation process such that
112 * almost everything else is functional on the file handle.
113 *
114 * This function invokes the selection process for io components,
115 * which works as follows:
116 *
117 * - If the \em preferred argument is NULL, the selection set is
118 * defined to be all the components found during
119 * mca_io_base_find_available().
120 * - If \em preferred is not NULL, then the selection set is just
121 * that component. (However, in this mode, we may make 2 passes
122 * through the selection process -- more on this below).
123 * - All components in the selection set are queried to see if they
124 * want to run with that file handle. All components that want to
125 * run are ranked by their priority and the highest priority
126 * component is selected. All non-selected components have their
127 * "unquery" function invoked to let them know that they were not
128 * selected.
129 * - The selected module will have its "init" function
130 * invoked to let it know that it was selected. All unselected
131 * components will have their file_unselect function invoked.
132 * - If we fall through this entire process and no component is
133 * selected \em and the \em preferred argument is not NULL, then
134 * run the entire process again as if the \em preferred argument
135 * was NULL (i.e., use the entire available set of components).
136 *
137 * At the end of this process, we'll either have a single
138 * component/module pair that is selected and initialized for the
139 * file handle, or no component was selected and an error is
140 * returned up the stack.
141 */
142 OMPI_DECLSPEC int mca_io_base_file_select(struct ompi_file_t *file,
143 mca_base_component_t *preferred);
144
145 /**
146 * Finalize a io component on a specific file handle.
147 *
148 * @param file The file handle that is being destroyed.
149 *
150 * @retval OMPI_SUCCESS Always.
151 *
152 * Note that the type of the parameter is only a "struct
153 * ompi_file_t" (vs. a plain "ompi_file_t") to avoid an include file
154 * loop. The types "struct ompi_file_t *", "ompi_file_t *", and
155 * "MPI_File" are all typedef'ed to be the same, so the fact that we
156 * use struct here in the prototype is ok.
157 *
158 * This function is invoked near the beginning of the destruction of
159 * a file handle. It finalizes the io component associated with the
160 * file handle (e.g., allowing the component to clean up and free any
161 * resources allocated for that file handle). Note that similar to
162 * mca_io_base_select(), as result of this function, other
163 * file handles may also be destroyed.
164 */
165 OMPI_DECLSPEC int mca_io_base_file_unselect(struct ompi_file_t *file);
166
167 /**
168 * Invoke a back-end component to delete a file.
169 *
170 * @param filename Name of the file to be deleted
171 * @param info MPI_Info for additional information
172 *
173 * This function is a bit different than most other MPI_File_*
174 * functions -- it does not take a MPI_File handle. As such, this
175 * function function invokes appropriate delete handlers on all
176 * the available components (rather than some pre-selected
177 * module). See io.h for details.
178 */
179 OMPI_DECLSPEC int mca_io_base_delete(char *filename,
180 struct ompi_info_t *info);
181
182 /**
183 * Shut down the io MCA framework.
184 *
185 * @retval OMPI_SUCCESS Always
186 *
187 * This function shuts down everything in the io MCA framework,
188 * and is called during ompi_mpi_finalize() and the special case of
189 * the laminfo fileand.
190 *
191 * It must be the last function invoked on the io MCA framework.
192 */
193 OMPI_DECLSPEC int mca_io_base_close(void);
194
195 OMPI_DECLSPEC int mca_io_base_register_datarep(char *,
196 MPI_Datarep_conversion_function*,
197 MPI_Datarep_conversion_function*,
198 MPI_Datarep_extent_function*,
199 void*);
200
201 /*
202 * Globals
203 */
204
205 /**
206 * Index number from the "io" MCA parameter, created when the io
207 * framework is initialized and used during scope selection.
208 */
209 OMPI_DECLSPEC extern int mca_io_base_param;
210 /**
211 * io framework debugging stream ID used with opal_output() and
212 * opal_output_verbose().
213 */
214 OMPI_DECLSPEC extern int mca_io_base_output;
215
216 /**
217 * Indicator as to whether the list of opened io components is valid or
218 * not.
219 */
220 OMPI_DECLSPEC extern bool mca_io_base_components_opened_valid;
221 /**
222 * List of all opened components; created when the io framework is
223 * initialized and destroyed when we reduce the list to all available
224 * io components.
225 */
226 OMPI_DECLSPEC extern opal_list_t mca_io_base_components_opened;
227 /**
228 * Indicator as to whether the list of available io components is valid
229 * or not.
230 */
231 OMPI_DECLSPEC extern bool mca_io_base_components_available_valid;
232 /**
233 * List of all available components; created by reducing the list of open
234 * components to all those who indicate that they may run during this
235 * process.
236 */
237 OMPI_DECLSPEC extern opal_list_t mca_io_base_components_available;
238
239 END_C_DECLS
240 #endif /* MCA_BASE_IO_H */
mca_io_base_param
OMPI_DECLSPEC int mca_io_base_param
Index number from the "io" MCA parameter, created when the io framework is initialized and used durin...
Definition: io_base_open.c:49
mca_io_base_components_opened_valid
OMPI_DECLSPEC bool mca_io_base_components_opened_valid
Indicator as to whether the list of opened io components is valid or not.
Definition: io_base_open.c:52
mca_base_component_2_0_0_t
Common type for all MCA components.
Definition: mca.h:250
mca_io_base_components_available_valid
OMPI_DECLSPEC bool mca_io_base_components_available_valid
Indicator as to whether the list of available io components is valid or not.
Definition: io_base_open.c:55
mca_io_base_components_opened
OMPI_DECLSPEC opal_list_t mca_io_base_components_opened
List of all opened components; created when the io framework is initialized and destroyed when we red...
Definition: io_base_open.c:53
opal_list.h
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
ompi_info_t
Definition: info.h:38
mca_io_base_output
OMPI_DECLSPEC int mca_io_base_output
io framework debugging stream ID used with opal_output() and opal_output_verbose().
Definition: io_base_open.c:50
mca_io_base_delete
OMPI_DECLSPEC int mca_io_base_delete(char *filename, struct ompi_info_t *info)
Invoke a back-end component to delete a file.
Definition: io_base_delete.c:76
ompi_file_t
Back-end structure for MPI_File.
Definition: file.h:42
mca_io_base_components_available
OMPI_DECLSPEC opal_list_t mca_io_base_components_available
List of all available components; created by reducing the list of open components to all those who in...
Definition: io_base_open.c:56
mca_io_base_open
BEGIN_C_DECLS OMPI_DECLSPEC int mca_io_base_open(void)
Initialize the io MCA framework.
Definition: io_base_open.c:63
opal_list_t
Definition: opal_list.h:147
mca_io_base_close
OMPI_DECLSPEC int mca_io_base_close(void)
Shut down the io MCA framework.
Definition: io_base_close.c:31
mca_io_base_find_available
OMPI_DECLSPEC int mca_io_base_find_available(bool enable_progress_threads, bool enable_mpi_threads)
Create list of available io components.
Definition: io_base_find_available.c:63
mca_io_base_file_unselect
OMPI_DECLSPEC int mca_io_base_file_unselect(struct ompi_file_t *file)
Finalize a io component on a specific file handle.
mca_io_base_file_select
OMPI_DECLSPEC int mca_io_base_file_select(struct ompi_file_t *file, mca_base_component_t *preferred)
Select an available component for a new file handle.
Definition: io_base_file_select.c:92