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) 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 */
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
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
Common type for all MCA components.
Definition: mca.h:250
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
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
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
Definition: info.h:38
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
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
Back-end structure for MPI_File.
Definition: file.h:42
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
BEGIN_C_DECLS OMPI_DECLSPEC int mca_io_base_open(void)
Initialize the io MCA framework.
Definition: io_base_open.c:63
Definition: opal_list.h:147
OMPI_DECLSPEC int mca_io_base_close(void)
Shut down the io MCA framework.
Definition: io_base_close.c:31
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
OMPI_DECLSPEC int mca_io_base_file_unselect(struct ompi_file_t *file)
Finalize a io component on a specific file handle.
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