programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cs_all_to_all.h
Go to the documentation of this file.
1 #ifndef __CS_ALL_TO_ALL_H__
2 #define __CS_ALL_TO_ALL_H__
3 
4 /*============================================================================
5  * All-to-all parallel data exchange.
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2014 EDF S.A.
12 
13  This program is free software; you can redistribute it and/or modify it under
14  the terms of the GNU General Public License as published by the Free Software
15  Foundation; either version 2 of the License, or (at your option) any later
16  version.
17 
18  This program is distributed in the hope that it will be useful, but WITHOUT
19  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21  details.
22 
23  You should have received a copy of the GNU General Public License along with
24  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25  Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27 
28 /*----------------------------------------------------------------------------*/
29 
30 #if defined(HAVE_MPI)
31 #include <mpi.h>
32 #endif
33 
34 /*----------------------------------------------------------------------------
35  * Local headers
36  *----------------------------------------------------------------------------*/
37 
38 #include "cs_defs.h"
39 #include "cs_block_dist.h"
40 
41 /*----------------------------------------------------------------------------*/
42 
44 
45 /*=============================================================================
46  * Macro definitions
47  *============================================================================*/
48 
49 /*============================================================================
50  * Type definitions
51  *============================================================================*/
52 
53 /* All-to-all algorithm choice */
54 
55 typedef enum {
56 
59 
61 
62 /* Opaque all-to-all distribution structure */
63 
64 #if defined(HAVE_MPI)
65 
66 typedef struct _cs_all_to_all_t cs_all_to_all_t;
67 
68 #endif
69 
70 /*=============================================================================
71  * Public function prototypes
72  *============================================================================*/
73 
74 #if defined(HAVE_MPI)
75 
76 /*----------------------------------------------------------------------------
77  * Create an all-to-all distributor for strided data.
78  *
79  * parameters:
80  * n_elts <-- number of elements
81  * stride <-- number of values per entity (interlaced)
82  * datatype <-- type of data considered
83  * elt <-- element values
84  * dest_rank <-- destination rank for each element
85  * comm <-- associated MPI communicator
86  *
87  * returns:
88  * pointer to new all-to-all distributor
89  *---------------------------------------------------------------------------*/
90 
92 cs_all_to_all_create_s(size_t n_elts,
93  int stride,
94  cs_datatype_t datatype,
95  void *elt,
96  const int dest_rank[],
97  MPI_Comm comm);
98 
99 /*----------------------------------------------------------------------------
100  * Create an all-to-all distributor for strided data with additional metadata.
101  *
102  * This variant allows optional tracking of destination ids or global
103  * numbers associated with elements, as well as their source ids.
104  *
105  * In cases where those arrays are required and already available, this
106  * may avoid the need for a specific element values buffer mixing actual
107  * data values and numbering metadata. It also makes extraction of the
108  * metadata easier using cs_all_to_all_get_id_pointers().
109  *
110  * parameters:
111  * n_elts <-- number of elements
112  * stride <-- number of values per entity (interlaced)
113  * datatype <-- type of data considered
114  * dest_id_datatype <-- type of destination id (CS_GNUM_TYPE, CS_LNUM_TYPE
115  * or CS_DATATYPE_NULL depending on elt_id values)
116  * add_src_id <-- add source id metadata (id in elt array)
117  * elt <-- element values
118  * dest_id <-- element destination id, global number, or NULL
119  * dest_rank <-- destination rank for each element
120  * comm <-- associated MPI communicator
121  *
122  * returns:
123  * pointer to new all-to-all distributor
124  *---------------------------------------------------------------------------*/
125 
127 cs_all_to_all_create_with_ids_s(size_t n_elts,
128  int stride,
129  cs_datatype_t datatype,
130  cs_datatype_t dest_id_datatype,
131  bool add_src_id,
132  void *elt,
133  void *dest_id,
134  const int dest_rank[],
135  MPI_Comm comm);
136 
137 /*----------------------------------------------------------------------------
138  * Create an all-to-all distributor for strided data with additional metadata,
139  * with destination rank determined from global numbers and block distribution
140  * information.
141  *
142  * This variant allows optional tracking of destination ids or global
143  * numbers associated with elements, as well as their source ids.
144  *
145  * In cases where those arrays are required and already available, this
146  * may avoid the need for a specific element values buffer mixing actual
147  * data values and numbering metadata. It also makes extraction of the
148  * metadata easier using cs_all_to_all_get_id_pointers().
149  *
150  * parameters:
151  * n_elts <-- number of elements
152  * stride <-- number of values per entity (interlaced)
153  * datatype <-- type of data considered
154  * dest_id_datatype <-- type of destination id (CS_GNUM_TYPE, CS_LNUM_TYPE
155  * or CS_DATATYPE_NULL)
156  * add_src_id <-- add source id metadata (id in elt array)
157  * elt <-- element values
158  * elt_gnum <-- global element numbers
159  * bi <-- destination block distribution info
160  * comm <-- associated MPI communicator
161  *
162  * returns:
163  * pointer to new all-to-all distributor
164  *---------------------------------------------------------------------------*/
165 
168  int stride,
169  cs_datatype_t datatype,
170  cs_datatype_t dest_id_datatype,
171  bool add_src_id,
172  void *elt,
173  const cs_gnum_t *elt_gnum,
175  MPI_Comm comm);
176 
177 /*----------------------------------------------------------------------------
178  * Destroy an all-to-all distributor.
179  *
180  * parameters:
181  * d <-> pointer to associated all-to-all distributor
182  *---------------------------------------------------------------------------*/
183 
184 void
186 
187 /*----------------------------------------------------------------------------
188  * Exchange data with an all-to-all distributor.
189  *
190  * Order of data from a same source rank is preserved.
191  *
192  * parameters:
193  * d <-> pointer to associated all-to-all distributor
194  *---------------------------------------------------------------------------*/
195 
196 void
198 
199 /*----------------------------------------------------------------------------
200  * Sort stride crystal router data by source rank.
201  *
202  * parameters:
203  * d <-> pointer to associated all-to-all distributor
204  *---------------------------------------------------------------------------*/
205 
206 void
208 
209 /*----------------------------------------------------------------------------
210  * Get number of elements associated with all-to-all distributor.
211  *
212  * The number of elements is the number of elements received after exchange.
213  *
214  * parameters:
215  * d <-- pointer to associated all-to-all distributor
216  *---------------------------------------------------------------------------*/
217 
218 cs_lnum_t
220 
221 /*----------------------------------------------------------------------------
222  * Swap source and destination ranks of all-to-all distributor.
223  *
224  * parameters:
225  * d <-> associated all-to-all distributor pointer
226  *---------------------------------------------------------------------------*/
227 
228 void
230 
231 /*----------------------------------------------------------------------------
232  * Get pointer to data elements associated with an all-to-all distributor.
233  *
234  * This allows modification and/or extraction of those elements.
235  *
236  * Note that depending on the distributor type used, the rank metadata
237  * and data may be interleaved, so the corresponding pointers point
238  * to strided, interleaved data.
239  *
240  * parameters:
241  * d <-- pointer to associated all-to-all distributor
242  * data_stride --> stride (in bytes) between data items
243  * data_ptr --> pointer to data items
244  *---------------------------------------------------------------------------*/
245 
246 void
248  size_t *data_stride,
249  unsigned char **data);
250 
251 /*----------------------------------------------------------------------------
252  * Get pointer to ranks of elements associated with an all-to-all distributor.
253  *
254  * This allows modification and/or extraction of those ranks.
255  *
256  * Note that depending on the distributor type used, the rank metadata
257  * and data may be interleaved, so the corresponding pointers point
258  * to strided, interleaved data.
259  *
260  * parameters:
261  * d <-- pointer to associated all-to-all distributor
262  * rank_stride --> stride (in integers) between rank values
263  * src_rank --> pointer to source rank values (or NULL)
264  * dest_rank --> pointer to destination rank values (or NULL)
265  *---------------------------------------------------------------------------*/
266 
267 void
269  size_t *rank_stride,
270  int **src_rank,
271  int **dest_rank);
272 
273 /*----------------------------------------------------------------------------
274  * Get pointer to source or destination rank element ids associated with an
275  * all-to-all distributor.
276  *
277  * If a requested type of id is not available (depending on the all-to-all
278  * distributor creation function and options), the matching pointer will
279  * be set to NULL.
280  *
281  * This allows modification and/or extraction of those ids, though it is
282  * intended primarily for identification.
283  *
284  * Note that depending on the distributor type used, the rank metadata
285  * and data may be interleaved, so the corresponding pointers point
286  * to strided, interleaved data.
287  *
288  * parameters:
289  * d <-- pointer to associated all-to-all distributor
290  * id_stride --> stride (in integers) between id items
291  * dest_id --> pointer to destination ids (or NULL)
292  * dest_id --> pointer to source ids (or NULL)
293  *---------------------------------------------------------------------------*/
294 
295 void
297  size_t *id_stride,
298  cs_lnum_t **dest_id,
299  cs_lnum_t **src_id);
300 
301 /*----------------------------------------------------------------------------
302  * Get pointer to element global numbers associated with an all-to-all
303  * distributor.
304  *
305  * If this data is not available (depending on the all-to-all distributor
306  * creation function and options), the matching pointer will
307  * be set to NULL.
308  *
309  * This allows modification and/or extraction of those numbers.
310  *
311  * Note that depending on the distributor type used, the rank metadata
312  * and data may be interleaved, so the corresponding pointers point
313  * to strided, interleaved data.
314  *
315  * parameters:
316  * d <-- pointer to associated all-to-all distributor
317  * gnum_stride --> stride (in integers) between element global numbers
318  * gnum --> pointer to global numbers
319  *---------------------------------------------------------------------------*/
320 
321 void
323  size_t *gnum_stride,
324  cs_gnum_t **gnum);
325 
326 /*----------------------------------------------------------------------------
327  * Get current type of all-to-all distributor algorithm choice.
328  *
329  * returns:
330  * current type of all-to-all distributor algorithm choice
331  *---------------------------------------------------------------------------*/
332 
335 
336 /*----------------------------------------------------------------------------
337  * Set current type of all-to-all distributor algorithm choice.
338  *
339  * parameters:
340  * t <-- type of all-to-all distributor algorithm choice to select
341  *---------------------------------------------------------------------------*/
342 
343 void
345 
346 #endif /* defined(HAVE_MPI) */
347 
348 /*----------------------------------------------------------------------------
349  * Log performance information relative to instrumented all-to-all
350  * distribution.
351  *----------------------------------------------------------------------------*/
352 
353 void
355 
356 /*----------------------------------------------------------------------------*/
357 
359 
360 #endif /* __CS_ALL_TO_ALL_H__ */
cs_datatype_t
Definition: cs_defs.h:255
unsigned long cs_gnum_t
global mesh entity number
Definition: cs_defs.h:280
Definition: cs_all_to_all.h:57
void cs_all_to_all_set_type(cs_all_to_all_type_t t)
Set current type of all-to-all distributor algorithm choice.
Definition: cs_all_to_all.c:1982
cs_lnum_t cs_all_to_all_n_elts(const cs_all_to_all_t *d)
Get number of elements associated with all-to-all distributor.
Definition: cs_all_to_all.c:1591
Definition: cs_block_dist.h:50
cs_all_to_all_type_t cs_all_to_all_get_type(void)
Get current type of all-to-all distributor algorithm choice.
Definition: cs_all_to_all.c:1968
#define BEGIN_C_DECLS
Definition: cs_defs.h:405
cs_all_to_all_type_t
All-to-all algorithm selection.
Definition: cs_all_to_all.h:55
void cs_all_to_all_get_id_pointers(cs_all_to_all_t *d, size_t *id_stride, cs_lnum_t **dest_id, cs_lnum_t **src_id)
Get pointer to source or destination rank element ids associated with an all-to-all distributor...
Definition: cs_all_to_all.c:1838
void cs_all_to_all_log_finalize(void)
Log performance information relative to instrumented all-to-all distribution.
Definition: cs_all_to_all.c:1995
void cs_all_to_all_destroy(cs_all_to_all_t **d)
Destroy an all-to-all distributor.
Definition: cs_all_to_all.c:1495
Definition: cs_all_to_all.h:58
cs_all_to_all_t * cs_all_to_all_create_s(size_t n_elts, int stride, cs_datatype_t datatype, void *elt, const int dest_rank[], MPI_Comm comm)
Create an all-to-all distributor for strided data.
Definition: cs_all_to_all.c:1238
void cs_all_to_all_get_rank_pointers(cs_all_to_all_t *d, size_t *rank_stride, int **src_rank, int **dest_rank)
Get pointer to ranks of elements associated with an all-to-all distributor.
Definition: cs_all_to_all.c:1742
void cs_all_to_all_exchange(cs_all_to_all_t *d)
Exchange data with an all-to-all distributor.
Definition: cs_all_to_all.c:1530
void cs_all_to_all_get_gnum_pointer(cs_all_to_all_t *d, size_t *gnum_stride, cs_gnum_t **gnum)
Get pointer to element global numbers associated with an all-to-all distributor.
Definition: cs_all_to_all.c:1919
void cs_all_to_all_sort_by_source_rank(cs_all_to_all_t *d)
Sort stride crystal router data by source rank.
Definition: cs_all_to_all.c:1562
cs_all_to_all_t * cs_all_to_all_create_from_block_s(size_t n_elts, int stride, cs_datatype_t datatype, cs_datatype_t dest_id_datatype, bool add_src_id, void *elt, const cs_gnum_t *elt_gnum, cs_block_dist_info_t bi, MPI_Comm comm)
Create an all-to-all distributor for strided data with additional metadata, with destination rank det...
Definition: cs_all_to_all.c:1424
void cs_all_to_all_get_data_pointer(cs_all_to_all_t *d, size_t *data_stride, unsigned char **data)
Get pointer to data elements associated with an all-to-all distributor.
Definition: cs_all_to_all.c:1689
void cs_all_to_all_swap_src_dest(cs_all_to_all_t *d)
Swap source and destination ranks of all-to-all distributor.
Definition: cs_all_to_all.c:1614
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
#define END_C_DECLS
Definition: cs_defs.h:406
struct _cs_all_to_all_t cs_all_to_all_t
Definition: cs_all_to_all.h:66
cs_all_to_all_t * cs_all_to_all_create_with_ids_s(size_t n_elts, int stride, cs_datatype_t datatype, cs_datatype_t dest_id_datatype, bool add_src_id, void *elt, void *dest_id, const int dest_rank[], MPI_Comm comm)
Create an all-to-all distributor for strided data with additional metadata.
Definition: cs_all_to_all.c:1329