OpenMPI  0.1.1
file.h
1 /* -*- Mode: C; c-basic-offset:4 ; -*- */
2 /*
3  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
4  * University Research and Technology
5  * Corporation. All rights reserved.
6  * Copyright (c) 2004-2007 The University of Tennessee and The University
7  * of Tennessee Research Foundation. All rights
8  * reserved.
9  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10  * University of Stuttgart. All rights reserved.
11  * Copyright (c) 2004-2005 The Regents of the University of California.
12  * All rights reserved.
13  * Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
14  * $COPYRIGHT$
15  *
16  * Additional copyrights may follow
17  *
18  * $HEADER$
19  */
20 
21 #ifndef OMPI_FILE_H
22 #define OMPI_FILE_H
23 
24 #include "ompi_config.h"
25 #include "mpi.h"
26 #include "opal/class/opal_list.h"
28 #include "opal/threads/mutex.h"
29 #include "ompi/mca/io/io.h"
30 
31 /*
32  * Flags
33  */
34 #define OMPI_FILE_ISCLOSED 0x00000001
35 #define OMPI_FILE_HIDDEN 0x00000002
36 
37 BEGIN_C_DECLS
38 
39 /**
40  * Back-end structure for MPI_File
41  */
42 struct ompi_file_t {
43  /** Base of OBJ_* interface */
45 
46  /** Communicator that this file was created with */
48 
49  /** Filename that this file was created with */
50  char *f_filename;
51 
52  /** Amode that this file was created with */
53  int f_amode;
54 
55  /** MPI_Info that this file was created with. Note that this is
56  *NOT* what should be returned from OMPI_FILE_GET_INFO! */
58 
59  /** Bit flags */
60  int32_t f_flags;
61 
62  /** Index in Fortran <-> C translation array */
64 
65  /** Error handler. This field does not have the "f_" prefix so
66  that the OMPI_ERRHDL_* macros can find it, regardless of
67  whether it's a comm, window, or file. */
69 
70  /** Type of the error handler. This field does not have the "f_"
71  prefix for the same reason as the field error_handler. */
73 
74  /** Indicate what version of the IO component we're using (this
75  indicates what member to look at in the union, below) */
76  mca_io_base_version_t f_io_version;
77 
78  /** The selected component (note that this is a union) -- we need
79  this to add and remove the component from the list of
80  components currently in use by the io framework for
81  progression porpoises. */
83 
84  /** The selected module (note that this is a union) */
86 
87  /** Allow the selected module to cache data on the file */
88  struct mca_io_base_file_t *f_io_selected_data;
89 };
90 /**
91  * Convenience typedef
92  */
93 typedef struct ompi_file_t ompi_file_t;
94 
95 /**
96  * Padded struct to maintain back compatibiltiy.
97  * See ompi/communicator/communicator.h comments with struct ompi_communicator_t
98  * for full explanation why we chose the following padding construct for predefines.
99  */
100 #define PREDEFINED_FILE_PAD (sizeof(void*) * 192)
101 
103  struct ompi_file_t file;
104  char padding[PREDEFINED_FILE_PAD - sizeof(ompi_file_t)];
105 };
107 
108 /**
109  * Back-end instances for MPI_FILE_NULL
110  */
111 OMPI_DECLSPEC extern ompi_predefined_file_t ompi_mpi_file_null;
112 
113 
114 /**
115  * Fortran to C conversion table
116  */
117 extern opal_pointer_array_t ompi_file_f_to_c_table;
118 
119 /**
120  * Initialize MPI_File handling.
121  *
122  * @retval OMPI_SUCCESS Always.
123  *
124  * Invoked during ompi_mpi_init().
125  */
126 int ompi_file_init(void);
127 
128 /**
129  * Back-end to MPI_FILE_OPEN: create a file handle, select an io
130  * component to use, and have that componet open the file.
131  *
132  * @param comm Communicator
133  * @param filename String filename
134  * @param amode Mode flags
135  * @param info Info
136  * @param fh Output file handle
137  *
138  * @retval OMPI_SUCCESS Upon success
139  * @retval OMPI_ERR* Upon error
140  *
141  * Create a file handle and select an io module to be paired with
142  * it. There is a corresponding ompi_file_close() function; it
143  * mainly calls OBJ_RELEASE() but also does some other error
144  * handling as well.
145  */
146 int ompi_file_open(struct ompi_communicator_t *comm, char *filename,
147  int amode, struct ompi_info_t *info,
148  ompi_file_t **fh);
149 
150 /**
151  * Atomicly set a name on a file handle.
152  *
153  * @param file MPI_File handle to set the name on
154  * @param name NULL-terminated string to use
155  *
156  * @returns OMPI_SUCCESS Always.
157  *
158  * At most (MPI_MAX_OBJECT_NAME-1) characters will be copied over to
159  * the file name's name. This function is performed atomically -- a
160  * lock is used to ensure that there are not multiple writers to the
161  * name to ensure that we don't end up with an erroneous name (e.g.,
162  * a name without a \0 at the end). After invoking this function,
163  * ompi_file_is_name_set() will return true.
164  */
165 int ompi_file_set_name(ompi_file_t *file, char *name);
166 
167 /**
168  * Back-end to MPI_FILE_CLOSE: destroy an ompi_file_t handle and
169  * close the file.
170  *
171  * @param file Pointer to ompi_file_t
172  *
173  * @returns OMPI_SUCCESS Always.
174  *
175  * This is the preferred mechanism for freeing an ompi_file_t.
176  * Although the main action that it performs is OBJ_RELEASE(), it
177  * also does some additional handling for error checking, etc.
178  */
179 int ompi_file_close(ompi_file_t **file);
180 
181 /**
182  * Tear down MPI_File handling.
183  *
184  * @retval OMPI_SUCCESS Always.
185  *
186  * Invoked during ompi_mpi_finalize().
187  */
188 int ompi_file_finalize(void);
189 
190 /**
191  * Check to see if an MPI_File handle is valid.
192  *
193  * @param file The MPI file handle
194  *
195  * @retval true If the file handle is not valid
196  * @retval false If the file handle is valid
197  *
198  * This is a convenience function, mainly for error checking in
199  * top-level MPI API functions.
200  */
201 static inline bool ompi_file_invalid(ompi_file_t *file)
202 {
203  return (NULL == file ||
204  &ompi_mpi_file_null.file == file ||
205  0 != (file->f_flags & OMPI_FILE_ISCLOSED));
206 }
207 
208 END_C_DECLS
209 
210 #endif /* OMPI_FILE_H */
dynamic pointer array
Definition: opal_pointer_array.h:45
char * f_filename
Filename that this file was created with.
Definition: file.h:50
Back-end type for MPI_Errorhandler.
Definition: errhandler.h:108
Definition: io.h:126
mca_io_base_version_t f_io_version
Indicate what version of the IO component we're using (this indicates what member to look at in the u...
Definition: file.h:76
Definition: io.h:351
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
struct ompi_info_t * f_info
MPI_Info that this file was created with.
Definition: file.h:57
int f_f_to_c_index
Index in Fortran <-> C translation array.
Definition: file.h:63
int f_amode
Amode that this file was created with.
Definition: file.h:53
Definition: info.h:38
struct mca_io_base_file_t * f_io_selected_data
Allow the selected module to cache data on the file.
Definition: file.h:88
mca_io_base_modules_t f_io_selected_module
The selected module (note that this is a union)
Definition: file.h:85
Back-end structure for MPI_File.
Definition: file.h:42
opal_object_t super
Base of OBJ_* interface.
Definition: file.h:44
struct ompi_communicator_t * f_comm
Communicator that this file was created with.
Definition: file.h:47
Base object.
Definition: opal_object.h:182
struct ompi_errhandler_t * error_handler
Error handler.
Definition: file.h:68
mca_io_base_components_t f_io_selected_component
The selected component (note that this is a union) – we need this to add and remove the component fr...
Definition: file.h:82
ompi_errhandler_type_t errhandler_type
Type of the error handler.
Definition: file.h:72
Mutual exclusion functions.
Definition: file.h:102
Definition: communicator.h:118
ompi_errhandler_type_t
Enum used to describe what kind MPI object an error handler is used for.
Definition: errhandler.h:84
int32_t f_flags
Bit flags.
Definition: file.h:60