OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

proc.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-2011 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) 2006 Cisco Systems, Inc. All rights reserved.
13 * Copyright (c) 2007 Los Alamos National Security, LLC. All rights
14 * reserved.
15 * Copyright (c) 2010-2012 Oak Ridge National Labs. All rights reserved.
16 * $COPYRIGHT$
17 *
18 * Additional copyrights may follow
19 *
20 * $HEADER$
21 */
22
23
24 /** @file
25 * Process identification structure interface
26 *
27 * Process identification structure interface. The ompi_proc_t
28 * structure contatins basic information about the remote (and local)
29 * processes.
30 */
31
32 #ifndef OMPI_PROC_PROC_H
33 #define OMPI_PROC_PROC_H
34
35 #include "ompi_config.h"
36 #include "ompi/constants.h"
37 #include "ompi/types.h"
38 #include "opal/class/opal_list.h"
39 #include "opal/dss/dss_types.h"
40 #include "opal/mca/paffinity/paffinity.h"
41
42 #include "orte/types.h"
43
44
45 BEGIN_C_DECLS
46
47 /* ******************************************************************** */
48
49
50 /**
51 * Remote Open MPI process structure
52 *
53 * Remote Open MPI process structure. Each process contains exactly
54 * one ompi_proc_t structure for each remote process it knows about.
55 */
56 struct ompi_proc_t {
57 /** allow proc to be placed on a list */
58 opal_list_item_t super;
59 /** this process' name */
60 orte_process_name_t proc_name;
61 /** PML specific proc data */
62 struct mca_pml_endpoint_t* proc_pml;
63 /** BML specific proc data */
64 struct mca_bml_base_endpoint_t* proc_bml;
65 /** architecture of this process */
66 uint32_t proc_arch;
67 /** flags for this proc */
68 opal_paffinity_locality_t proc_flags;
69 /** Base convertor for the proc described by this process */
70 struct opal_convertor_t* proc_convertor;
71 /** A pointer to the name of this host - data is
72 * actually stored in the RTE
73 */
74 char* proc_hostname;
75 #if OPAL_ENABLE_FT_MPI
76 /** Is the process active? */
77 bool proc_active;
78 #endif /* OPAL_ENABLE_FT_MPI */
79 };
80 typedef struct ompi_proc_t ompi_proc_t;
81 OBJ_CLASS_DECLARATION(ompi_proc_t);
82
83 #if OPAL_ENABLE_FT_MPI
84 static inline bool ompi_proc_is_active(ompi_proc_t *proc)
85 {
86 return (proc->proc_active);
87 }
88
89 /* Made a function, so we can do something smarter in the future */
90 static inline void ompi_proc_mark_as_failed(ompi_proc_t *proc)
91 {
92 proc->proc_active = false;
93 }
94 #endif /* OPAL_ENABLE_FT_MPI */
95
96 /**
97 * @private
98 *
99 * Pointer to the ompi_proc_t structure for the local process
100 *
101 * Pointer to the ompi_proc_t structure for the local process.
102 *
103 * @note This pointer is declared here to allow inline functions
104 * within this header file to access the local process quickly.
105 * Please use ompi_proc_local() instead.
106 */
107 OMPI_DECLSPEC extern ompi_proc_t* ompi_proc_local_proc;
108
109
110 /* ******************************************************************** */
111
112
113 /**
114 * Initialize the OMPI process subsystem
115 *
116 * Initialize the Open MPI process subsystem. This function will
117 * query the run-time environment and build a list of the proc
118 * instances in the current MPI_COMM_WORLD. The local information not
119 * easily determined by the run-time ahead of time (architecture and
120 * hostname) will be published during this call.
121 *
122 * @note While an ompi_proc_t will exist with mostly valid information
123 * for each process in the MPI_COMM_WORLD at the conclusion of this
124 * call, some information will not be immediately available. This
125 * includes the architecture and hostname, which will be available by
126 * the conclusion of the stage gate.
127 *
128 * @retval OMPI_SUCESS System successfully initialized
129 * @retval OMPI_ERROR Initialization failed due to unspecified error
130 */
131 OMPI_DECLSPEC int ompi_proc_init(void);
132
133 /**
134 * Complete filling up the proc information (arch, name and locality) for all
135 * procs related to this job. This function is to be called only after
136 * the modex exchange has been completed.
137 *
138 * @retval OMPI_SUCCESS All information correctly set.
139 * @retval OMPI_ERROR Some info could not be initialized.
140 */
141 OMPI_DECLSPEC int ompi_proc_complete_init(void);
142
143 /**
144 * Finalize the OMPI Process subsystem
145 *
146 * Finalize the Open MPI process subsystem. This function will
147 * release all memory created during the life of the application,
148 * including all ompi_proc_t structures.
149 *
150 * @retval OMPI_SUCCESS System successfully finalized
151 */
152 OMPI_DECLSPEC int ompi_proc_finalize(void);
153
154
155 /**
156 * Returns the list of proc instances associated with this job.
157 *
158 * Returns the list of proc instances associated with this job. Given
159 * the current association between a job and an MPI_COMM_WORLD, this
160 * function provides the process instances for the current
161 * MPI_COMM_WORLD.
162 *
163 * @note The reference count of each process in the array is
164 * NOT incremented - the caller is responsible for ensuring the
165 * correctness of the reference count once they are done with
166 * the array.
167 *
168 * @param[in] size Number of processes in the ompi_proc_t array
169 *
170 * @return Array of pointers to proc instances in the current
171 * MPI_COMM_WORLD, or NULL if there is an internal failure.
172 */
173 OMPI_DECLSPEC ompi_proc_t** ompi_proc_world(size_t* size);
174
175
176 /**
177 * Returns the list of all known proc instances.
178 *
179 * Returns the list of all known proc instances, including those in
180 * other MPI_COMM_WORLDs. It is possible that we may no longer be
181 * connected to some of the procs returned (in the MPI sense of the
182 * word connected). In a strictly MPI-1 application, this function
183 * will return the same information as ompi_proc_world().
184 *
185 * @note The reference count of each process in the array is
186 * incremented and the caller is responsible for releasing each
187 * process in the array, as well as freeing the array.
188 *
189 * @param[in] size Number of processes in the ompi_proc_t array
190 *
191 * @return Array of pointers to proc instances in the current
192 * known universe, or NULL if there is an internal failure.
193 */
194 OMPI_DECLSPEC ompi_proc_t** ompi_proc_all(size_t* size);
195
196
197 /**
198 * Returns a list of the local process
199 *
200 * Returns a list containing the local process (and only the local
201 * process). Has calling semantics similar to ompi_proc_world() and
202 * ompi_proc_all().
203 *
204 * @note The reference count of each process in the array is
205 * incremented and the caller is responsible for releasing each
206 * process in the array, as well as freeing the array.
207 *
208 * @param[in] size Number of processes in the ompi_proc_t array
209 *
210 * @return Array of pointers to proc instances in the current
211 * known universe, or NULL if there is an internal failure.
212 */
213 OMPI_DECLSPEC ompi_proc_t** ompi_proc_self(size_t* size);
214
215
216 /**
217 * Returns a pointer to the local process
218 *
219 * Returns a pointer to the local process. Unlike ompi_proc_self(),
220 * the reference count on the local proc instance is not modified by
221 * this function.
222 *
223 * @return Pointer to the local process structure
224 */
225 static inline ompi_proc_t* ompi_proc_local(void)
226 {
227 return ompi_proc_local_proc;
228 }
229
230
231 /**
232 * Returns the proc instance for a given name
233 *
234 * Returns the proc instance for the specified process name. The
235 * reference count for the proc instance is not incremented by this
236 * function.
237 *
238 * @param[in] name The process name to look for
239 *
240 * @return Pointer to the process instance for \c name
241 */
242 OMPI_DECLSPEC ompi_proc_t * ompi_proc_find ( const orte_process_name_t* name );
243
244 /**
245 * Pack proc list into portable buffer
246 *
247 * This function takes a list of ompi_proc_t pointers (e.g. as given
248 * in groups) and returns a orte buffer containing all information
249 * needed to add the proc to a remote list. This includes the ORTE
250 * process name, the architecture, and the hostname. Ordering is
251 * maintained. The buffer is packed to be sent to a remote node with
252 * different architecture (endian or word size). The buffer can be
253 * dss unloaded to be sent using MPI or send using rml_send_packed().
254 *
255 * @param[in] proclist List of process pointers
256 * @param[in] proclistsize Length of the proclist array
257 * @param[in,out] buf An orte_buffer containing the packed names.
258 * The buffer must be constructed but empty when
259 * passed to this function
260 * @retval OMPI_SUCCESS Success
261 * @retval OMPI_ERROR Unspecified error
262 */
263 OMPI_DECLSPEC int ompi_proc_pack(ompi_proc_t **proclist, int proclistsize,
264 opal_buffer_t *buf);
265
266
267 /**
268 * Unpack a portable buffer of procs
269 *
270 * This function unpacks a packed list of ompi_proc_t structures and
271 * returns the ordered list of proc structures. If the given proc is
272 * already "known", the architecture and hostname information in the
273 * buffer is ignored. If the proc is "new" to this process, it will
274 * be added to the global list of known procs, with information
275 * provided in the buffer. The lookup actions are always entirely
276 * local. The proclist returned is a list of pointers to all procs in
277 * the buffer, whether they were previously known or are new to this
278 * process.
279 *
280 * @note In previous versions of this function, The PML's add_procs()
281 * function was called for any new processes discovered as a result of
282 * this operation. That is no longer the case -- the caller must use
283 * the newproclist information to call add_procs() if necessary.
284 *
285 * @note The reference count for procs created as a result of this
286 * operation will be set to 1. Existing procs will not have their
287 * reference count changed. The reference count of a proc at the
288 * return of this function is the same regardless of whether NULL is
289 * provided for newproclist. The user is responsible for freeing the
290 * newproclist array.
291 *
292 * @param[in] buf orte_buffer containing the packed names
293 * @param[in] proclistsize number of expected proc-pointres
294 * @param[out] proclist list of process pointers
295 * @param[out] newproclistsize Number of new procs added as a result
296 * of the unpack operation. NULL may be
297 * provided if information is not needed.
298 * @param[out] newproclist List of new procs added as a result of
299 * the unpack operation. NULL may be
300 * provided if informationis not needed.
301 *
302 * Return value:
303 * OMPI_SUCCESS on success
304 * OMPI_ERROR else
305 */
306 OMPI_DECLSPEC int ompi_proc_unpack(opal_buffer_t *buf,
307 int proclistsize, ompi_proc_t ***proclist,
308 int *newproclistsize, ompi_proc_t ***newproclist);
309
310 /**
311 * Refresh the OMPI process subsystem
312 *
313 * Refresh the Open MPI process subsystem. This function will update
314 * the list of proc instances in the current MPI_COMM_WORLD with
315 * data from the run-time environemnt.
316 *
317 * @note This is primarily used when restarting a process and thus
318 * need to update the jobid and node name.
319 *
320 * @retval OMPI_SUCESS System successfully refreshed
321 * @retval OMPI_ERROR Refresh failed due to unspecified error
322 */
323 OMPI_DECLSPEC int ompi_proc_refresh(void);
324
325 END_C_DECLS
326
327 #endif /* OMPI_PROC_PROC_H */
ompi_proc_finalize
OMPI_DECLSPEC int ompi_proc_finalize(void)
Finalize the OMPI Process subsystem.
Definition: proc.c:195
ompi_proc_t::proc_bml
struct mca_bml_base_endpoint_t * proc_bml
BML specific proc data.
Definition: proc.h:64
ompi_proc_self
OMPI_DECLSPEC ompi_proc_t ** ompi_proc_self(size_t *size)
Returns a list of the local process.
Definition: proc.c:320
ompi_proc_local
static ompi_proc_t * ompi_proc_local(void)
Returns a pointer to the local process.
Definition: proc.h:225
orte_process_name_t
Definition: types.h:146
ompi_proc_world
OMPI_DECLSPEC ompi_proc_t ** ompi_proc_world(size_t *size)
Returns the list of proc instances associated with this job.
Definition: proc.c:228
ompi_proc_t::super
opal_list_item_t super
allow proc to be placed on a list
Definition: proc.h:58
ompi_proc_t::proc_pml
struct mca_pml_endpoint_t * proc_pml
PML specific proc data.
Definition: proc.h:62
opal_list.h
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
ompi_proc_t
Remote Open MPI process structure.
Definition: proc.h:56
ompi_proc_init
OMPI_DECLSPEC int ompi_proc_init(void)
Initialize the OMPI process subsystem.
Definition: proc.c:101
opal_list_item_t
Definition: opal_list.h:98
types.h
ompi_proc_t::proc_name
orte_process_name_t proc_name
this process' name
Definition: proc.h:60
ompi_proc_t::proc_flags
opal_paffinity_locality_t proc_flags
flags for this proc
Definition: proc.h:68
ompi_proc_t::proc_hostname
char * proc_hostname
A pointer to the name of this host - data is actually stored in the RTE.
Definition: proc.h:74
ompi_proc_find
OMPI_DECLSPEC ompi_proc_t * ompi_proc_find(const orte_process_name_t *name)
Returns the proc instance for a given name.
Definition: proc.c:338
ompi_proc_all
OMPI_DECLSPEC ompi_proc_t ** ompi_proc_all(size_t *size)
Returns the list of all known proc instances.
Definition: proc.c:290
dss_types.h
Buffer management types.
paffinity.h
paffinity (processor affinity) framework component interface definitions.
mca_bml_base_endpoint_t
Structure associated w/ ompi_proc_t that contains the set of BTLs used to reach a destination...
Definition: bml.h:222
opal_convertor_t
Definition: opal_convertor.h:90
ompi_proc_refresh
OMPI_DECLSPEC int ompi_proc_refresh(void)
Refresh the OMPI process subsystem.
Definition: proc.c:360
ompi_proc_t::proc_convertor
struct opal_convertor_t * proc_convertor
Base convertor for the proc described by this process.
Definition: proc.h:70
ompi_proc_t::proc_arch
uint32_t proc_arch
architecture of this process
Definition: proc.h:66
opal_buffer_t
Structure for holding a buffer to be used with the RML or OOB subsystems.
Definition: dss_types.h:159
ompi_proc_complete_init
OMPI_DECLSPEC int ompi_proc_complete_init(void)
Complete filling up the proc information (arch, name and locality) for all procs related to this job...
Definition: proc.c:147
ompi_proc_pack
OMPI_DECLSPEC int ompi_proc_pack(ompi_proc_t **proclist, int proclistsize, opal_buffer_t *buf)
Pack proc list into portable buffer.
Definition: proc.c:411
ompi_proc_unpack
OMPI_DECLSPEC int ompi_proc_unpack(opal_buffer_t *buf, int proclistsize, ompi_proc_t ***proclist, int *newproclistsize, ompi_proc_t ***newproclist)
Unpack a portable buffer of procs.
Definition: proc.c:493
OBJ_CLASS_DECLARATION
#define OBJ_CLASS_DECLARATION(NAME)
Declaration for class descriptor.
Definition: opal_object.h:236
ompi_proc_local_proc
OMPI_DECLSPEC ompi_proc_t * ompi_proc_local_proc
Pointer to the ompi_proc_t structure for the local process.
Definition: proc.c:46