OpenMPI  0.1.1
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"
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 */
59  /** this process' name */
61  /** PML specific proc data */
62  struct mca_pml_endpoint_t* proc_pml;
63  /** BML specific proc data */
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 */
71  /** A pointer to the name of this host - data is
72  * actually stored in the RTE
73  */
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;
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_DECLSPEC int ompi_proc_finalize(void)
Finalize the OMPI Process subsystem.
Definition: proc.c:195
struct mca_bml_base_endpoint_t * proc_bml
BML specific proc data.
Definition: proc.h:64
OMPI_DECLSPEC ompi_proc_t ** ompi_proc_self(size_t *size)
Returns a list of the local process.
Definition: proc.c:320
static ompi_proc_t * ompi_proc_local(void)
Returns a pointer to the local process.
Definition: proc.h:225
Definition: types.h:146
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
opal_list_item_t super
allow proc to be placed on a list
Definition: proc.h:58
struct mca_pml_endpoint_t * proc_pml
PML specific proc data.
Definition: proc.h:62
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
Remote Open MPI process structure.
Definition: proc.h:56
OMPI_DECLSPEC int ompi_proc_init(void)
Initialize the OMPI process subsystem.
Definition: proc.c:101
Definition: opal_list.h:98
orte_process_name_t proc_name
this process' name
Definition: proc.h:60
opal_paffinity_locality_t proc_flags
flags for this proc
Definition: proc.h:68
char * proc_hostname
A pointer to the name of this host - data is actually stored in the RTE.
Definition: proc.h:74
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_DECLSPEC ompi_proc_t ** ompi_proc_all(size_t *size)
Returns the list of all known proc instances.
Definition: proc.c:290
Buffer management types.
paffinity (processor affinity) framework component interface definitions.
Structure associated w/ ompi_proc_t that contains the set of BTLs used to reach a destination...
Definition: bml.h:222
Definition: opal_convertor.h:90
OMPI_DECLSPEC int ompi_proc_refresh(void)
Refresh the OMPI process subsystem.
Definition: proc.c:360
struct opal_convertor_t * proc_convertor
Base convertor for the proc described by this process.
Definition: proc.h:70
uint32_t proc_arch
architecture of this process
Definition: proc.h:66
Structure for holding a buffer to be used with the RML or OOB subsystems.
Definition: dss_types.h:159
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_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_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
#define OBJ_CLASS_DECLARATION(NAME)
Declaration for class descriptor.
Definition: opal_object.h:236
OMPI_DECLSPEC ompi_proc_t * ompi_proc_local_proc
Pointer to the ompi_proc_t structure for the local process.
Definition: proc.c:46