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 (c) 2015 Research Organization for Information Science 14 * and Technology (RIST). All rights reserved. 15 * Copyright (c) 2016-2017 IBM Corporation. All rights reserved. 16 * $COPYRIGHT$ 17 * 18 * Additional copyrights may follow 19 * 20 * $HEADER$ 21 */ 22 23 /** 24 * @file 25 * 26 * MCA io base framework public interface functions. 27 */ 28 29 #ifndef MCA_IO_BASE_H 30 #define MCA_IO_BASE_H 31 32 #include "ompi_config.h" 33 34 #include "mpi.h" 35 #include "opal/class/opal_list.h" 36 #include "opal/mca/base/base.h" 37 #include "ompi/mca/io/io.h" 38 39 40 /* 41 * Global functions for MCA overall io open and close 42 */ 43 44 BEGIN_C_DECLS 45 /** 46 * Create list of available io components. 47 * 48 * @param allow_multi_user_threads Will be set to true if any of the 49 * available components will allow multiple user threads 50 * @param have_hidden_threads Will be set to true if any of the 51 * available components have hidden threads. 52 * 53 * @retval OMPI_SUCCESS If one or more io components are available. 54 * @retval OMPI_ERROR If no io components are found to be available. 55 * 56 * This function is invoked during ompi_mpi_init() to query all 57 * successfully opened io components and create a list of all 58 * available io components. 59 * 60 * This function traverses the (internal global variable) 61 * mca_io_base_components_opened list and queries each component to see 62 * if it ever might want to run during this MPI process. It creates 63 * another internal global variable list named 64 * mca_io_base_components_available, consisting of a list of components 65 * that are available for selection when file handles are created. 66 * This variable should \em only be used by other io base 67 * functions -- it is not considered a public interface member -- 68 * and is only mentioned here for completeness. 69 */ 70 OMPI_DECLSPEC int mca_io_base_find_available(bool enable_progress_threads, 71 bool enable_mpi_threads); 72 73 /** 74 * Select an available component for a new file handle. 75 * 76 * @param file File Handle that the component will be selected for. 77 * @param preferred The component that is preferred for this 78 * file handle (or NULL). 79 * 80 * @return OMPI_SUCCESS Upon success. 81 * @return OMPI_ERROR Upon failure. 82 * 83 * Note that the types of the parameters have "struct" in them 84 * (e.g., ompi_file_t" vs. a plain "ompi_file_t") to 85 * avoid an include file loop. All similar types (e.g., "struct 86 * ompi_file_t *", "ompi_file_t *", and "MPI_File") 87 * are all typedef'ed to be the same, so the fact that we use struct 88 * here in the prototype is ok. 89 * 90 * This function is invoked when a new file handle is created and a 91 * io component needs to be selected for it. It should be invoked 92 * near the end of the file handle creation process such that 93 * almost everything else is functional on the file handle. 94 * 95 * This function invokes the selection process for io components, 96 * which works as follows: 97 * 98 * - If the \em preferred argument is NULL, the selection set is 99 * defined to be all the components found during 100 * mca_io_base_find_available(). 101 * - If \em preferred is not NULL, then the selection set is just 102 * that component. (However, in this mode, we may make 2 passes 103 * through the selection process -- more on this below). 104 * - All components in the selection set are queried to see if they 105 * want to run with that file handle. All components that want to 106 * run are ranked by their priority and the highest priority 107 * component is selected. All non-selected components have their 108 * "unquery" function invoked to let them know that they were not 109 * selected. 110 * - The selected module will have its "init" function 111 * invoked to let it know that it was selected. All unselected 112 * components will have their file_unselect function invoked. 113 * - If we fall through this entire process and no component is 114 * selected \em and the \em preferred argument is not NULL, then 115 * run the entire process again as if the \em preferred argument 116 * was NULL (i.e., use the entire available set of components). 117 * 118 * At the end of this process, we'll either have a single 119 * component/module pair that is selected and initialized for the 120 * file handle, or no component was selected and an error is 121 * returned up the stack. 122 */ 123 OMPI_DECLSPEC int mca_io_base_file_select(struct ompi_file_t *file, 124 mca_base_component_t *preferred); 125 126 /** 127 * Finalize a io component on a specific file handle. 128 * 129 * @param file The file handle that is being destroyed. 130 * 131 * @retval OMPI_SUCCESS Always. 132 * 133 * Note that the type of the parameter is only a "struct 134 * ompi_file_t" (vs. a plain "ompi_file_t") to avoid an include file 135 * loop. The types "struct ompi_file_t *", "ompi_file_t *", and 136 * "MPI_File" are all typedef'ed to be the same, so the fact that we 137 * use struct here in the prototype is ok. 138 * 139 * This function is invoked near the beginning of the destruction of 140 * a file handle. It finalizes the io component associated with the 141 * file handle (e.g., allowing the component to clean up and free any 142 * resources allocated for that file handle). Note that similar to 143 * mca_io_base_select(), as result of this function, other 144 * file handles may also be destroyed. 145 */ 146 OMPI_DECLSPEC int mca_io_base_file_unselect(struct ompi_file_t *file); 147 148 /** 149 * Invoke a back-end component to delete a file. 150 * 151 * @param filename Name of the file to be deleted 152 * @param info MPI_Info for additional information 153 * 154 * This function is a bit different than most other MPI_File_* 155 * functions -- it does not take a MPI_File handle. As such, this 156 * function function invokes appropriate delete handlers on all 157 * the available components (rather than some pre-selected 158 * module). See io.h for details. 159 */ 160 OMPI_DECLSPEC int mca_io_base_delete(const char *filename, 161 struct opal_info_t *info); 162 163 OMPI_DECLSPEC int mca_io_base_register_datarep(const char *, 164 MPI_Datarep_conversion_function*, 165 MPI_Datarep_conversion_function*, 166 MPI_Datarep_extent_function*, 167 void*); 168 169 /* 170 * Globals 171 */ 172 173 OMPI_DECLSPEC extern mca_base_framework_t ompi_io_base_framework; 174 175 END_C_DECLS 176 #endif /* MCA_BASE_IO_H */