root/ompi/mca/topo/topo.h

INCLUDED FROM

   1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
   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-2013 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      Oak Ridge National Labs.  All rights reserved.
  14  * Copyright (c) 2012-2013 Inria.  All rights reserved.
  15  * Copyright (c) 2014-2015 Research Organization for Information Science
  16  *                         and Technology (RIST). All rights reserved.
  17  * Copyright (c) 2015      Los Alamos National Security, LLC. All rights
  18  *                         reserved.
  19  * Copyright (c) 2016-2017 IBM Corporation. All rights reserved.
  20  * $COPYRIGHT$
  21  *
  22  * Additional copyrights may follow
  23  *
  24  * $HEADER$
  25  */
  26 
  27 #ifndef MCA_TOPO_H
  28 #define MCA_TOPO_H
  29 
  30 #include "ompi_config.h"
  31 
  32 #include "ompi/mca/mca.h"
  33 #include "opal/mca/base/base.h"
  34 #include "ompi/communicator/communicator.h"
  35 
  36 /* Forward reference to ompi_proc_t */
  37 struct ompi_proc_t;
  38 typedef struct mca_topo_base_module_t mca_topo_base_module_t;
  39 
  40 /*
  41  * Initial component query, called during mca_topo_base_open.
  42  */
  43 typedef int (*mca_topo_base_component_init_query_2_2_0_fn_t)
  44     (bool enable_progress_threads,
  45      bool enable_mpi_threads);
  46 
  47 /*
  48  * Communicator query, called during cart and graph communicator
  49  * creation.
  50  */
  51 typedef struct mca_topo_base_module_t*
  52 (*mca_topo_base_component_comm_query_2_2_0_fn_t)
  53     (const ompi_communicator_t *comm, int *priority, uint32_t type);
  54 
  55 /*
  56  * Structure for topo v2.1.0 components.This is chained to MCA v2.0.0
  57  */
  58 typedef struct mca_topo_base_component_2_2_0_t {
  59     mca_base_component_t topoc_version;
  60     mca_base_component_data_t topoc_data;
  61 
  62     mca_topo_base_component_init_query_2_2_0_fn_t topoc_init_query;
  63     mca_topo_base_component_comm_query_2_2_0_fn_t topoc_comm_query;
  64 } mca_topo_base_component_2_2_0_t;
  65 typedef mca_topo_base_component_2_2_0_t mca_topo_base_component_t;
  66 
  67 /*
  68  * Struct for holding graph communicator information
  69  */
  70 typedef struct mca_topo_base_comm_graph_2_2_0_t {
  71     /* Make this structure be an object so that it has a constructor
  72        and destructor. */
  73     opal_object_t super;
  74     int nnodes;
  75     int *index;
  76     int *edges;
  77 } mca_topo_base_comm_graph_2_2_0_t;
  78 typedef mca_topo_base_comm_graph_2_2_0_t mca_topo_base_comm_graph_t;
  79 
  80 OMPI_DECLSPEC OBJ_CLASS_DECLARATION(mca_topo_base_comm_graph_2_2_0_t);
  81 
  82 /*
  83  * Struct for holding cartesian communicator information
  84  */
  85 typedef struct mca_topo_base_comm_cart_2_2_0_t {
  86     /* Make this structure be an object so that it has a constructor
  87        and destructor. */
  88     opal_object_t super;
  89     int ndims;
  90     int *dims;
  91     int *periods;
  92     int *coords;
  93 } mca_topo_base_comm_cart_2_2_0_t;
  94 typedef mca_topo_base_comm_cart_2_2_0_t mca_topo_base_comm_cart_t;
  95 
  96 OMPI_DECLSPEC OBJ_CLASS_DECLARATION(mca_topo_base_comm_cart_2_2_0_t);
  97 
  98 /*
  99  * Struct for holding distributed graph information
 100  */
 101 typedef struct mca_topo_base_comm_dist_graph_2_2_0_t {
 102     /* Make this structure be an object so that it has a constructor
 103        and destructor. */
 104     opal_object_t super;
 105     int *in;
 106     int *inw;
 107     int *out;
 108     int *outw;
 109     int indegree, outdegree;
 110     bool weighted;
 111 } mca_topo_base_comm_dist_graph_2_2_0_t;
 112 typedef mca_topo_base_comm_dist_graph_2_2_0_t mca_topo_base_comm_dist_graph_t;
 113 
 114 OMPI_DECLSPEC OBJ_CLASS_DECLARATION(mca_topo_base_comm_dist_graph_2_2_0_t);
 115 
 116 /*
 117  * This union must be declared (can't be anonymous in the struct where
 118  * it is used) because we need to be able to resolve it and find field
 119  * offsets in the ompi/debuggers/ stuff (i.e., so that debuggers can
 120  * parse/understand the individual fields on communicators).
 121  */
 122 typedef union mca_topo_base_comm_cgd_union_2_2_0_t {
 123     mca_topo_base_comm_graph_2_2_0_t*      graph;
 124     mca_topo_base_comm_cart_2_2_0_t*       cart;
 125     mca_topo_base_comm_dist_graph_2_2_0_t* dist_graph;
 126 } mca_topo_base_comm_cgd_union_2_2_0_t;
 127 typedef mca_topo_base_comm_cgd_union_2_2_0_t mca_topo_base_comm_cgd_union_t;
 128 
 129 /**
 130  * The logic for creating communicators with attached topologies is
 131  * the following. A new placeholder communicator is prepared before
 132  * the *_create function is called, and is initialized with minimal
 133  * information. As an example, this communicator is not safe neither
 134  * for point-to-point nor collective messages, it is provided only
 135  * as a placeholder. However, the original communicator where the
 136  * topology function was called upon is provided as well, in order to have
 137  * a valid medium for messaging. In return from the *_create functions,
 138  * a new group of processes is expected one containing all processes in
 139  * the local_group of the new communicator. Once this information
 140  * returned the new communicator will be fully initialized and activated.
 141  */
 142 
 143 /*
 144  * Module function typedefs
 145  */
 146 
 147 /* Back end for MPI_CART_COORDS */
 148 typedef int (*mca_topo_base_module_cart_coords_fn_t)
 149                     (struct ompi_communicator_t *comm,
 150                      int rank,
 151                      int maxdims,
 152                      int *coords);
 153 
 154 /* Back end for MPI_CART_CREATE */
 155 typedef int (*mca_topo_base_module_cart_create_fn_t)
 156                     (mca_topo_base_module_t *topo_module,
 157                      ompi_communicator_t* old_comm,
 158                      int ndims,
 159                      const int *dims,
 160                      const int *periods,
 161                      bool reorder,
 162                      ompi_communicator_t** comm_topo);
 163 
 164 /* Back end for MPI_CART_GET */
 165 typedef int (*mca_topo_base_module_cart_get_fn_t)
 166                     (struct ompi_communicator_t *comm,
 167                      int maxdims,
 168                      int *dims,
 169                      int *periods,
 170                      int *coords);
 171 
 172 /* Back end for MPI_CARTDIM_GET */
 173 typedef int (*mca_topo_base_module_cartdim_get_fn_t)
 174                     (struct ompi_communicator_t *comm,
 175                      int *ndims);
 176 
 177 /* Back end for MPI_CART_MAP */
 178 typedef int (*mca_topo_base_module_cart_map_fn_t)
 179                     (struct ompi_communicator_t *comm,
 180                      int ndims,
 181                      const int *dims,
 182                      const int *periods,
 183                      int *newrank);
 184 
 185 /* Back end for MPI_CART_RANK */
 186 typedef int (*mca_topo_base_module_cart_rank_fn_t)
 187                     (struct ompi_communicator_t *comm,
 188                      const int *coords,
 189                      int *rank);
 190 
 191 /* Back end for MPI_CART_SHIFT */
 192 typedef int (*mca_topo_base_module_cart_shift_fn_t)
 193                     (struct ompi_communicator_t *comm,
 194                      int direction,
 195                      int disp,
 196                      int *rank_source,
 197                      int *rank_dest);
 198 
 199 /* Back end for MPI_CART_SUB */
 200 typedef int (*mca_topo_base_module_cart_sub_fn_t)
 201                     (struct ompi_communicator_t *comm,
 202                      const int *remain_dims,
 203                      struct ompi_communicator_t ** new_comm);
 204 
 205 /* Back end for MPI_GRAPH_CREATE */
 206 typedef int (*mca_topo_base_module_graph_create_fn_t)
 207                     (mca_topo_base_module_t *topo_module,
 208                      ompi_communicator_t* old_comm,
 209                      int nnodes,
 210                      const int *index,
 211                      const int *edges,
 212                      bool reorder,
 213                      ompi_communicator_t** new_comm);
 214 
 215 /* Back end for MPI_GRAPH_GET */
 216 typedef int (*mca_topo_base_module_graph_get_fn_t)
 217                     (struct ompi_communicator_t *comm,
 218                      int maxindex,
 219                      int maxedges,
 220                      int *index,
 221                      int *edges);
 222 
 223 /* Back end for MPI_GRAPH_MAP */
 224 typedef int (*mca_topo_base_module_graph_map_fn_t)
 225                     (struct ompi_communicator_t *comm,
 226                      int nnodes,
 227                      const int *index,
 228                      const int *edges,
 229                      int *newrank);
 230 
 231 /* Back end for MPI_GRAPHDIMS_GET */
 232 typedef int (*mca_topo_base_module_graphdims_get_fn_t)
 233                     (struct ompi_communicator_t *comm,
 234                      int *nnodes,
 235                      int *nnedges);
 236 
 237 /* Back end for MPI_GRAPH_NEIGHBORS */
 238 typedef int (*mca_topo_base_module_graph_neighbors_fn_t)
 239                     (struct ompi_communicator_t *comm,
 240                      int rank,
 241                      int maxneighbors,
 242                      int *neighbors);
 243 
 244 /* Back end for MPI_GRAPH_NEIGHBORS_COUNT */
 245 typedef int (*mca_topo_base_module_graph_neighbors_count_fn_t)
 246                     (struct ompi_communicator_t *comm,
 247                      int rank,
 248                      int *nneighbors);
 249 
 250 /* Back end for MPI_DIST_GRAPH_CREATE */
 251 typedef int (*mca_topo_base_module_dist_graph_create_fn_t)
 252                     (struct mca_topo_base_module_t* module,
 253                      struct ompi_communicator_t *old_comm,
 254                      int n, const int nodes[],
 255                      const int degrees[], const int targets[], const int weights[],
 256                      struct opal_info_t *info, int reorder,
 257                      struct ompi_communicator_t **new_comm);
 258 
 259 /* Back end for MPI_DIST_GRAPH_CREATE_ADJACENT */
 260 typedef int (*mca_topo_base_module_dist_graph_create_adjacent_fn_t)
 261                     (struct mca_topo_base_module_t* module,
 262                      ompi_communicator_t *comm_old,
 263                      int indegree, const int sources[],
 264                      const int sourceweights[],
 265                      int outdegree,
 266                      const int destinations[],
 267                      const int destweights[],
 268                      struct opal_info_t *info, int reorder,
 269                      ompi_communicator_t **comm_dist_graph);
 270 
 271 /* Back end for MPI_DIST_GRAPH_NEIGHBORS */
 272 typedef int (*mca_topo_base_module_dist_graph_neighbors_fn_t)
 273                     (struct ompi_communicator_t *comm,
 274                      int maxindegree,
 275                      int sources[], int sourceweights[],
 276                      int maxoutdegree, int destinations[],
 277                      int destweights[]);
 278 
 279 /* Back end for MPI_DIST_GRAPH_NEIGHBORS_COUNT */
 280 typedef int (*mca_topo_base_module_dist_graph_neighbors_count_fn_t)
 281                     (struct ompi_communicator_t *comm,
 282                      int *inneighbors, int *outneighbors, int *weighted);
 283 
 284 /*
 285  * Topo module structure.  If a given topo module needs to cache more
 286  * information than what is contained in the mca_topo_base_module_t, it should
 287  * create its own module struct that uses mca_topo_base_module_t as a super.
 288  *
 289  * A module only needs to define two vital functions: the create and the map (or
 290  * equivalent). However, if no specialized functions are provided, they will be
 291  * automatically replaced by their default version. They will return the answers
 292  * based on the base information stored in the associated module extra data.
 293  */
 294 typedef struct mca_topo_base_cart_module_2_2_0_t {
 295     mca_topo_base_module_cart_coords_fn_t cart_coords;
 296     mca_topo_base_module_cart_create_fn_t cart_create;
 297     mca_topo_base_module_cart_get_fn_t    cart_get;
 298     mca_topo_base_module_cartdim_get_fn_t cartdim_get;
 299     mca_topo_base_module_cart_map_fn_t    cart_map;
 300     mca_topo_base_module_cart_rank_fn_t   cart_rank;
 301     mca_topo_base_module_cart_shift_fn_t  cart_shift;
 302     mca_topo_base_module_cart_sub_fn_t    cart_sub;
 303 } mca_topo_base_cart_module_2_2_0_t;
 304 
 305 typedef struct mca_topo_base_graph_module_2_2_0_t {
 306     mca_topo_base_module_graph_create_fn_t          graph_create;
 307     mca_topo_base_module_graph_get_fn_t             graph_get;
 308     mca_topo_base_module_graph_map_fn_t             graph_map;
 309     mca_topo_base_module_graphdims_get_fn_t         graphdims_get;
 310     mca_topo_base_module_graph_neighbors_fn_t       graph_neighbors;
 311     mca_topo_base_module_graph_neighbors_count_fn_t graph_neighbors_count;
 312 } mca_topo_base_graph_module_2_2_0_t;
 313 
 314 typedef struct mca_topo_base_dist_graph_module_2_2_0_t {
 315     mca_topo_base_module_dist_graph_create_fn_t          dist_graph_create;
 316     mca_topo_base_module_dist_graph_create_adjacent_fn_t dist_graph_create_adjacent;
 317     mca_topo_base_module_dist_graph_neighbors_fn_t       dist_graph_neighbors;
 318     mca_topo_base_module_dist_graph_neighbors_count_fn_t dist_graph_neighbors_count;
 319 } mca_topo_base_dist_graph_module_2_2_0_t;
 320 
 321 struct mca_topo_base_module_t {
 322     /* Make this structure be an object so that it has a constructor
 323        and destructor. */
 324     opal_object_t              super;
 325 
 326     uint32_t                   type;             /* type of topology */
 327     bool                       reorder;          /* reordering was required */
 328     mca_topo_base_component_t* topo_component;   /* Component of this topo module */
 329 
 330     /* Cart, graph or dist graph related functions */
 331     union {
 332         mca_topo_base_cart_module_2_2_0_t cart;
 333         mca_topo_base_graph_module_2_2_0_t graph;
 334         mca_topo_base_dist_graph_module_2_2_0_t dist_graph;
 335     } topo;
 336 
 337     /* This union caches the parameters passed when the communicator
 338        was created.  Look in comm->c_flags to figure out whether this
 339        is a cartesian, graph, or dist graph communicator. */
 340     mca_topo_base_comm_cgd_union_t mtc;
 341 };
 342 
 343 OMPI_DECLSPEC OBJ_CLASS_DECLARATION(mca_topo_base_module_t);
 344 
 345 /*
 346  * ******************************************************************
 347  * ********** Use in components that are of type topo v2.2.0 ********
 348  * ******************************************************************
 349  */
 350 #define MCA_TOPO_BASE_VERSION_2_2_0 \
 351     OMPI_MCA_BASE_VERSION_2_1_0("topo", 2, 2, 0)
 352 
 353 #endif /* MCA_TOPO_H */