OpenMPI  0.1.1
group.h
Go to the documentation of this file.
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) 2006-2007 University of Houston. All rights reserved.
14  * Copyright (c) 2007 Cisco Systems, Inc. All rights reserved.
15  * Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
16  * Copyright (c) 2012 Oak Ridge National Labs. All rights reserved.
17  * $COPYRIGHT$
18  *
19  * Additional copyrights may follow
20  *
21  * $HEADER$
22  */
23 
24 /**
25  * @file:
26  *
27  * Infrastructure for MPI group support.
28  */
29 #ifndef OMPI_GROUP_H
30 #define OMPI_GROUP_H
31 
32 #include "ompi_config.h"
33 #include "ompi/proc/proc.h"
34 #include "mpi.h"
36 #include "opal/util/output.h"
37 
38 BEGIN_C_DECLS
39 
40 #define BSIZE ((int)sizeof(unsigned char)*8)
41 
43 {
44  int rank_first;
45  int length;
46 };
47 
49 {
50  struct ompi_group_sporadic_list_t *grp_sporadic_list;
51  /** list to hold the sporadic struct */
52  int grp_sporadic_list_len;/** length of the structure*/
53 };
55 {
56  int grp_strided_offset; /** offset to start from when including or excluding */
57  int grp_strided_stride; /** stride for including or excluding */
58  int grp_strided_last_element; /** the last element to be included for */
59 };
61 {
62  unsigned char *grp_bitmap_array; /* the bit map array for sparse groups of type BMAP */
63  int grp_bitmap_array_len; /* length of the bit array */
64 };
65 
66 /**
67  * Group structure
68  * Currently we have four formats for storing the process pointers that are members
69  * of the group.
70  * PList: a dense format that stores all the process pointers of the group.
71  * Sporadic: a sparse format that stores the ranges of the ranks from the parent group,
72  * that are included in the current group.
73  * Strided: a sparse format that stores three integers that describe a red-black pattern
74  * that the current group is formed from its parent group.
75  * Bitmap: a sparse format that maintains a bitmap of the included processes from the
76  * parent group. For each process that is included from the parent group
77  * its corresponding rank is set in the bitmap array.
78  */
79 struct ompi_group_t {
80  opal_object_t super; /**< base class */
81  int grp_proc_count; /**< number of processes in group */
82  int grp_my_rank; /**< rank in group */
83  int grp_f_to_c_index; /**< index in Fortran <-> C translation array */
85  /**< list of pointers to ompi_proc_t structures
86  for each process in the group */
87  uint32_t grp_flags; /**< flags, e.g. freed, cannot be freed etc.*/
88  /** pointer to the original group when using sparse storage */
90  union
91  {
92  struct ompi_group_sporadic_data_t grp_sporadic;
93  struct ompi_group_strided_data_t grp_strided;
94  struct ompi_group_bitmap_data_t grp_bitmap;
95  } sparse_data;
96 };
97 
98 typedef struct ompi_group_t ompi_group_t;
99 OMPI_DECLSPEC OBJ_CLASS_DECLARATION(ompi_group_t);
100 
101 /**
102  * Padded struct to maintain back compatibiltiy.
103  * See ompi/communicator/communicator.h comments with struct ompi_communicator_t
104  * for full explanation why we chose the following padding construct for predefines.
105  */
106 #define PREDEFINED_GROUP_PAD (sizeof(void*) * 32)
107 
109  struct ompi_group_t group;
110  char padding[PREDEFINED_GROUP_PAD - sizeof(ompi_group_t)];
111 };
112 
114 
115 /*
116  * The following include pulls in shared typedefs with debugger plugins.
117  * For more information on why we do this see the Notice to developers
118  * comment at the top of the ompi_msgq_dll.c file.
119  */
120 #include "group_dbg.h"
121 
122 #define OMPI_GROUP_IS_INTRINSIC(_group) ((_group)->grp_flags&OMPI_GROUP_INTRINSIC)
123 #define OMPI_GROUP_IS_DENSE(_group) ((_group)->grp_flags & OMPI_GROUP_DENSE)
124 #define OMPI_GROUP_IS_SPORADIC(_group) ((_group)->grp_flags & OMPI_GROUP_SPORADIC)
125 #define OMPI_GROUP_IS_STRIDED(_group) ((_group)->grp_flags & OMPI_GROUP_STRIDED)
126 #define OMPI_GROUP_IS_BITMAP(_group) ((_group)->grp_flags & OMPI_GROUP_BITMAP)
127 
128 #define OMPI_GROUP_SET_INTRINSIC(_group) ( (_group)->grp_flags |= OMPI_GROUP_INTRINSIC)
129 #define OMPI_GROUP_SET_DENSE(_group) ( (_group)->grp_flags |= OMPI_GROUP_DENSE)
130 #define OMPI_GROUP_SET_SPORADIC(_group) ( (_group)->grp_flags |= OMPI_GROUP_SPORADIC)
131 #define OMPI_GROUP_SET_STRIDED(_group) ( (_group)->grp_flags |= OMPI_GROUP_STRIDED)
132 #define OMPI_GROUP_SET_BITMAP(_group) ( (_group)->grp_flags |= OMPI_GROUP_BITMAP)
133 
134 /**
135  * Table for Fortran <-> C group handle conversion
136  */
137 OMPI_DECLSPEC extern struct opal_pointer_array_t ompi_group_f_to_c_table;
138 OMPI_DECLSPEC extern struct ompi_predefined_group_t ompi_mpi_group_null;
139 
140 #if OPAL_ENABLE_FT_MPI
141 /*
142  * Global list of failed processes
143  */
144 OMPI_DECLSPEC extern ompi_group_t *ompi_group_all_failed_procs;
145 #endif /* OPAL_ENABLE_FT_MPI */
146 
147 /*
148  * function prototypes
149  */
150 
151 /**
152  * Allocate a new group structure.
153  *
154  * @param group_size Number of MPI processes in the group
155  *
156  * @return Pointer to new group structure
157  */
158 OMPI_DECLSPEC ompi_group_t *ompi_group_allocate(int group_size);
159 ompi_group_t *ompi_group_allocate_sporadic(int group_size);
160 ompi_group_t *ompi_group_allocate_strided(void);
161 ompi_group_t *ompi_group_allocate_bmap(int orig_group_size, int group_size);
162 
163 /**
164  * Increment the reference count of the proc structures.
165  *
166  * @param group Pointer to ompi_group_t structute (IN)
167  *
168  */
169 OMPI_DECLSPEC void ompi_group_increment_proc_count(ompi_group_t *group);
170 
171 /**
172  * Decrement the reference count of the proc structures.
173  *
174  * @param group Pointer to ompi_group_t structute (IN)
175  *
176  */
177 OMPI_DECLSPEC void ompi_group_decrement_proc_count(ompi_group_t *group);
178 
179 
180 /**
181  * Initialize OMPI group infrastructure.
182  *
183  * @return Error code
184  */
185 int ompi_group_init(void);
186 
187 
188 /**
189  * Clean up OMPI group infrastructure.
190  *
191  * @return Error code
192  */
193 int ompi_group_finalize(void);
194 
195 /**
196  * Get group size.
197  *
198  * @param group Pointer to ompi_group_t structute (IN)
199  *
200  * @return Group size
201  */
202 static inline int ompi_group_size(ompi_group_t *group)
203 {
204  return group->grp_proc_count;
205 }
206 
207 
208 /**
209  * Get group rank
210  *
211  * @param group Pointer to ompi_group_t structure (IN)
212  *
213  * @return Group rank
214  */
215 static inline int ompi_group_rank(ompi_group_t *group)
216 {
217  return group->grp_my_rank;
218 }
219 
220 
221 
222 /**
223  * Set group rank in the input group structure
224  *
225  * @param group Group Pointer to ompi_group_t structure (INOUT)
226  * @param proc_pointer Pointer to ompi_proc_t structure for process.
227  * MPI_PROC_NULL may be used to indicate proc not
228  * in group
229  *
230  * @return Error code
231  */
232 void ompi_set_group_rank(ompi_group_t *group, struct ompi_proc_t *proc_pointer);
233 
234 /**
235  * Abstracting MPI_Group_translate_ranks to an ompi function for internal use
236  */
237 OMPI_DECLSPEC int ompi_group_translate_ranks ( ompi_group_t *group1,
238  int n_ranks, int *ranks1,
239  ompi_group_t *group2,
240  int *ranks2);
241 
242 /**
243  * Abstracting MPI_Group_compare to an ompi function for internal use
244  */
245 OMPI_DECLSPEC int ompi_group_compare(ompi_group_t *group1,
246  ompi_group_t *group2,
247  int *result);
248 
249 /**
250  * Abstracting MPI_Group_free, since it is required by some internal functions...
251  */
252 int ompi_group_free (ompi_group_t **group);
253 
254 /**
255  * Functions to handle process pointers for sparse group formats
256  */
257 OMPI_DECLSPEC ompi_proc_t* ompi_group_get_proc_ptr (ompi_group_t* group , int rank);
258 
259 int ompi_group_translate_ranks_sporadic ( ompi_group_t *group1,
260  int n_ranks, int *ranks1,
261  ompi_group_t *group2,
262  int *ranks2);
263 int ompi_group_translate_ranks_sporadic_reverse ( ompi_group_t *group1,
264  int n_ranks, int *ranks1,
265  ompi_group_t *group2,
266  int *ranks2);
267 int ompi_group_translate_ranks_strided ( ompi_group_t *group1,
268  int n_ranks, int *ranks1,
269  ompi_group_t *group2,
270  int *ranks2);
271 int ompi_group_translate_ranks_strided_reverse ( ompi_group_t *group1,
272  int n_ranks, int *ranks1,
273  ompi_group_t *group2,
274  int *ranks2);
275 int ompi_group_translate_ranks_bmap ( ompi_group_t *group1,
276  int n_ranks, int *ranks1,
277  ompi_group_t *group2,
278  int *ranks2);
279 int ompi_group_translate_ranks_bmap_reverse ( ompi_group_t *group1,
280  int n_ranks, int *ranks1,
281  ompi_group_t *group2,
282  int *ranks2);
283 
284 /**
285  * Prototypes for the group back-end functions. Argument lists
286  are similar to the according C MPI functions.
287  */
288 OMPI_DECLSPEC int ompi_group_incl(ompi_group_t* group, int n, int *ranks,
289  ompi_group_t **new_group);
290 int ompi_group_excl(ompi_group_t* group, int n, int *ranks,
291  ompi_group_t **new_group);
292 int ompi_group_range_incl(ompi_group_t* group, int n_triplets,
293  int ranges[][3],ompi_group_t **new_group);
294 int ompi_group_range_excl(ompi_group_t* group, int n_triplets,
295  int ranges[][3],ompi_group_t **new_group);
296 int ompi_group_union (ompi_group_t* group1, ompi_group_t* group2,
297  ompi_group_t **new_group);
298 int ompi_group_intersection(ompi_group_t* group1,ompi_group_t* group2,
299  ompi_group_t **new_group);
300 int ompi_group_difference(ompi_group_t* group1, ompi_group_t* group2,
301  ompi_group_t **new_group);
302 
303 
304 /**
305  * Include Functions to handle Sparse storage formats
306  */
307 int ompi_group_incl_plist(ompi_group_t* group, int n, int *ranks,
308  ompi_group_t **new_group);
309 int ompi_group_incl_spor(ompi_group_t* group, int n, int *ranks,
310  ompi_group_t **new_group);
311 int ompi_group_incl_strided(ompi_group_t* group, int n, int *ranks,
312  ompi_group_t **new_group);
313 int ompi_group_incl_bmap(ompi_group_t* group, int n, int *ranks,
314  ompi_group_t **new_group);
315 
316 /**
317  * Functions to calculate storage spaces
318  */
319 int ompi_group_calc_plist ( int n, int *ranks );
320 int ompi_group_calc_strided ( int n, int *ranks );
321 int ompi_group_calc_sporadic ( int n, int *ranks );
322 int ompi_group_calc_bmap ( int n, int orig_size , int *ranks );
323 
324 /**
325  * Function to return the minimum value in an array
326  */
327 int ompi_group_minloc (int list[], int length);
328 
329 /**
330  * Inline function to check if sparse groups are enabled and return the direct access
331  * to the proc pointer, otherwise the lookup function
332  */
333 static inline struct ompi_proc_t* ompi_group_peer_lookup(ompi_group_t *group, int peer_id)
334 {
335 #if OPAL_ENABLE_DEBUG
336  if (peer_id >= group->grp_proc_count) {
337  opal_output(0, "ompi_group_lookup_peer: invalid peer index (%d)", peer_id);
338  return (struct ompi_proc_t *) NULL;
339  }
340 #endif
341 #if OMPI_GROUP_SPARSE
342  return ompi_group_get_proc_ptr (group, peer_id);
343 #else
344  return group->grp_proc_pointers[peer_id];
345 #endif
346 }
347 
348 /**
349  * Determine the rank of the specified process in this group
350  */
351 OMPI_DECLSPEC int ompi_group_peer_lookup_id(ompi_group_t *group, ompi_proc_t *proc);
352 
353 /**
354  * Function to print the group info
355  */
356 int ompi_group_dump (ompi_group_t* group);
357 
358 /**
359  * Ceil Function so not to include the math.h lib
360  */
361 int ompi_group_div_ceil (int num, int den);
362 
363 END_C_DECLS
364 #endif /* OMPI_GROUP_H */
OMPI_DECLSPEC void ompi_group_increment_proc_count(ompi_group_t *group)
Increment the reference count of the proc structures.
Definition: group_init.c:210
int ompi_group_init(void)
Initialize OMPI group infrastructure.
Definition: group_init.c:309
opal_object_t super
base class
Definition: group.h:80
OPAL output stream facility.
dynamic pointer array
Definition: opal_pointer_array.h:45
int ompi_group_incl_plist(ompi_group_t *group, int n, int *ranks, ompi_group_t **new_group)
Include Functions to handle Sparse storage formats.
Definition: group_plist.c:35
struct ompi_group_t * grp_parent_group_ptr
pointer to the original group when using sparse storage
Definition: group.h:89
static int ompi_group_rank(ompi_group_t *group)
Get group rank.
Definition: group.h:215
Definition: group.h:48
int ompi_group_dump(ompi_group_t *group)
Function to print the group info.
Definition: group.c:118
int ompi_group_div_ceil(int num, int den)
Ceil Function so not to include the math.h lib.
Definition: group_bitmap.c:119
OMPI_DECLSPEC void ompi_group_decrement_proc_count(ompi_group_t *group)
Decrement the reference count of the proc structures.
Definition: group_init.c:224
Definition: group.h:108
int grp_proc_count
number of processes in group
Definition: group.h:81
See opal_bitmap.h for an explanation of why there is a split between OPAL and ORTE for this generic c...
Process identification structure interface.
Remote Open MPI process structure.
Definition: proc.h:56
OMPI_DECLSPEC int ompi_group_peer_lookup_id(ompi_group_t *group, ompi_proc_t *proc)
Determine the rank of the specified process in this group.
Definition: group_plist.c:305
Definition: group.h:60
int grp_f_to_c_index
index in Fortran <-> C translation array
Definition: group.h:83
int grp_sporadic_list_len
list to hold the sporadic struct
Definition: group.h:52
OMPI_DECLSPEC int ompi_group_translate_ranks(ompi_group_t *group1, int n_ranks, int *ranks1, ompi_group_t *group2, int *ranks2)
Abstracting MPI_Group_translate_ranks to an ompi function for internal use.
Definition: group.c:41
int grp_strided_last_element
stride for including or excluding
Definition: group.h:58
OPAL_DECLSPEC void opal_output(int output_id, const char *format,...) __opal_attribute_format__(__printf__
Main function to send output to a stream.
#define PREDEFINED_GROUP_PAD
Padded struct to maintain back compatibiltiy.
Definition: group.h:106
struct ompi_proc_t ** grp_proc_pointers
list of pointers to ompi_proc_t structures for each process in the group
Definition: group.h:84
int grp_strided_stride
offset to start from when including or excluding
Definition: group.h:57
OMPI_DECLSPEC int ompi_group_incl(ompi_group_t *group, int n, int *ranks, ompi_group_t **new_group)
Prototypes for the group back-end functions.
Definition: group.c:199
int ompi_group_free(ompi_group_t **group)
Abstracting MPI_Group_free, since it is required by some internal functions...
Definition: group.c:29
int grp_my_rank
rank in group
Definition: group.h:82
static struct ompi_proc_t * ompi_group_peer_lookup(ompi_group_t *group, int peer_id)
Inline function to check if sparse groups are enabled and return the direct access to the proc pointe...
Definition: group.h:333
OMPI_DECLSPEC struct opal_pointer_array_t ompi_group_f_to_c_table
Table for Fortran <-> C group handle conversion.
Definition: group_init.c:41
Group structure Currently we have four formats for storing the process pointers that are members of t...
Definition: group.h:79
uint32_t grp_flags
flags, e.g.
Definition: group.h:87
Base object.
Definition: opal_object.h:182
int ompi_group_minloc(int list[], int length)
Function to return the minimum value in an array.
Definition: group.c:184
int ompi_group_finalize(void)
Clean up OMPI group infrastructure.
Definition: group_init.c:351
static int ompi_group_size(ompi_group_t *group)
Get group size.
Definition: group.h:202
Definition: group.h:54
Definition: group.h:42
OMPI_DECLSPEC int ompi_group_compare(ompi_group_t *group1, ompi_group_t *group2, int *result)
Abstracting MPI_Group_compare to an ompi function for internal use.
Definition: group.c:511
OMPI_DECLSPEC ompi_group_t * ompi_group_allocate(int group_size)
Allocate a new group structure.
Definition: group_init.c:56
OMPI_DECLSPEC ompi_proc_t * ompi_group_get_proc_ptr(ompi_group_t *group, int rank)
Functions to handle process pointers for sparse group formats.
Definition: group.c:169
void ompi_set_group_rank(ompi_group_t *group, struct ompi_proc_t *proc_pointer)
Set group rank in the input group structure.
Definition: group_set_rank.c:27
int ompi_group_calc_plist(int n, int *ranks)
Functions to calculate storage spaces.
Definition: group_plist.c:31
#define OBJ_CLASS_DECLARATION(NAME)
Declaration for class descriptor.
Definition: opal_object.h:236