root/orte/mca/grpcomm/grpcomm.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
   2 /*
   3  * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
   4  *                         University Research and Technology
   5  *                         Corporation.  All rights reserved.
   6  * Copyright (c) 2004-2005 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) 2011-2016 Los Alamos National Security, LLC. All rights
  14  *                         reserved.
  15  * Copyright (c) 2016      Research Organization for Information Science
  16  *                         and Technology (RIST). All rights reserved.
  17  * Copyright (c) 2017-2018 Intel, Inc. All rights reserved.
  18  * $COPYRIGHT$
  19  *
  20  * Additional copyrights may follow
  21  *
  22  * $HEADER$
  23  */
  24 /** @file:
  25  *
  26  * The OpenRTE Group Communications
  27  *
  28  * The OpenRTE Group Comm framework provides communication services that
  29  * span entire jobs or collections of processes. It is not intended to be
  30  * used for point-to-point communications (the RML does that), nor should
  31  * it be viewed as a high-performance communication channel for large-scale
  32  * data transfers.
  33  */
  34 
  35 #ifndef MCA_GRPCOMM_H
  36 #define MCA_GRPCOMM_H
  37 
  38 /*
  39  * includes
  40  */
  41 
  42 #include "orte_config.h"
  43 #include "orte/constants.h"
  44 #include "orte/types.h"
  45 
  46 #include "orte/mca/mca.h"
  47 #include "opal/class/opal_list.h"
  48 #include "opal/class/opal_bitmap.h"
  49 #include "opal/dss/dss_types.h"
  50 
  51 #include "orte/mca/rml/rml_types.h"
  52 
  53 BEGIN_C_DECLS
  54 
  55 /* define a callback function to be invoked upon
  56  * collective completion */
  57 typedef void (*orte_grpcomm_cbfunc_t)(int status, opal_buffer_t *buf, void *cbdata);
  58 
  59 /* Define a collective signature so we don't need to
  60  * track global collective id's */
  61 typedef struct {
  62     opal_object_t super;
  63     orte_process_name_t *signature;
  64     size_t sz;
  65 } orte_grpcomm_signature_t;
  66 OBJ_CLASS_DECLARATION(orte_grpcomm_signature_t);
  67 
  68 /* Internal component object for tracking ongoing
  69  * allgather operations */
  70 typedef struct {
  71     opal_list_item_t super;
  72     /* collective's signature */
  73     orte_grpcomm_signature_t *sig;
  74     /* collection bucket */
  75     opal_buffer_t bucket;
  76     /* participating daemons */
  77     orte_vpid_t *dmns;
  78     /** number of participating daemons */
  79     size_t ndmns;
  80     /** my index in the dmns array */
  81     unsigned long my_rank;
  82     /* number of buckets expected */
  83     size_t nexpected;
  84     /* number reported in */
  85     size_t nreported;
  86     /* distance masks for receive */
  87     opal_bitmap_t distance_mask_recv;
  88     /* received buckets */
  89     opal_buffer_t ** buffers;
  90     /* callback function */
  91     orte_grpcomm_cbfunc_t cbfunc;
  92     /* user-provided callback data */
  93     void *cbdata;
  94 } orte_grpcomm_coll_t;
  95 OBJ_CLASS_DECLARATION(orte_grpcomm_coll_t);
  96 
  97 /*
  98  * Component functions - all MUST be provided!
  99  */
 100 
 101 
 102 /* initialize the selected module */
 103 typedef int (*orte_grpcomm_base_module_init_fn_t)(void);
 104 
 105 /* finalize the selected module */
 106 typedef void (*orte_grpcomm_base_module_finalize_fn_t)(void);
 107 
 108 /* Scalably send a message. Caller will provide an array
 109  * of daemon vpids that are to receive the message. A NULL
 110  * pointer indicates that all daemons are participating. */
 111 typedef int (*orte_grpcomm_base_module_xcast_fn_t)(orte_vpid_t *vpids,
 112                                                    size_t nprocs,
 113                                                    opal_buffer_t *msg);
 114 
 115 /* allgather - gather data from all specified daemons. Barrier operations
 116  * will provide a zero-byte buffer. Caller will provide an array
 117  * of daemon vpids that are participating in the allgather via the
 118  * orte_grpcomm_coll_t object. A NULL pointer indicates that all daemons
 119  * are participating.
 120  *
 121  * NOTE: this is a non-blocking call. The callback function cached in
 122  * the orte_grpcomm_coll_t will be invoked upon completion. */
 123 typedef int (*orte_grpcomm_base_module_allgather_fn_t)(orte_grpcomm_coll_t *coll,
 124                                                        opal_buffer_t *buf);
 125 
 126 /*
 127  * Ver 3.0 - internal modules
 128  */
 129 typedef struct {
 130     orte_grpcomm_base_module_init_fn_t           init;
 131     orte_grpcomm_base_module_finalize_fn_t       finalize;
 132     /* collective operations */
 133     orte_grpcomm_base_module_xcast_fn_t          xcast;
 134     orte_grpcomm_base_module_allgather_fn_t      allgather;
 135 } orte_grpcomm_base_module_t;
 136 
 137 /* the Public APIs */
 138 /* Scalably send a message. Caller will provide an array
 139  * of process names that are to receive the message. A NULL
 140  * pointer indicates that all known procs are to receive
 141  * the message. A pointer to a name that includes ORTE_VPID_WILDCARD
 142  * will send the message to all procs in the specified jobid.
 143  * The message will be sent to the daemons hosting the specified
 144  * procs for processing and relay. */
 145 typedef int (*orte_grpcomm_base_API_xcast_fn_t)(orte_grpcomm_signature_t *sig,
 146                                                 orte_rml_tag_t tag,
 147                                                 opal_buffer_t *msg);
 148 
 149 /* allgather - gather data from all specified procs. Barrier operations
 150  * will provide a zero-byte buffer. Caller will provide an array
 151  * of application proc vpids that are participating in the allgather. A NULL
 152  * pointer indicates that all known procs are participating. A pointer
 153  * to a name that includes ORTE_VPID_WILDCARD indicates that all procs
 154  * in the specified jobid are contributing.
 155  *
 156  * NOTE: this is a non-blocking call. The provided callback function
 157  * will be invoked upon completion. */
 158 typedef int (*orte_grpcomm_base_API_allgather_fn_t)(orte_grpcomm_signature_t *sig,
 159                                                     opal_buffer_t *buf,
 160                                                     orte_grpcomm_cbfunc_t cbfunc,
 161                                                     void *cbdata);
 162 typedef struct {
 163     /* collective operations */
 164     orte_grpcomm_base_API_xcast_fn_t             xcast;
 165     orte_grpcomm_base_API_allgather_fn_t         allgather;
 166 } orte_grpcomm_API_module_t;
 167 
 168 
 169 /*
 170  * the standard component data structure
 171  */
 172 struct orte_grpcomm_base_component_3_0_0_t {
 173     mca_base_component_t base_version;
 174     mca_base_component_data_t base_data;
 175 };
 176 typedef struct orte_grpcomm_base_component_3_0_0_t orte_grpcomm_base_component_3_0_0_t;
 177 typedef orte_grpcomm_base_component_3_0_0_t orte_grpcomm_base_component_t;
 178 
 179 
 180 
 181 /*
 182  * Macro for use in components that are of type grpcomm v3.0.0
 183  */
 184 #define ORTE_GRPCOMM_BASE_VERSION_3_0_0 \
 185     /* grpcomm v3.0 is chained to MCA v2.0 */ \
 186     ORTE_MCA_BASE_VERSION_2_1_0("grpcomm", 3, 0, 0)
 187 
 188 /* Global structure for accessing grpcomm functions */
 189 ORTE_DECLSPEC extern orte_grpcomm_API_module_t orte_grpcomm;
 190 
 191 END_C_DECLS
 192 
 193 #endif

/* [<][>][^][v][top][bottom][index][help] */