mca/grpcomm/grpcomm.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
0004  *                         University Research and Technology
0005  *                         Corporation.  All rights reserved.
0006  * Copyright (c) 2004-2005 The University of Tennessee and The University
0007  *                         of Tennessee Research Foundation.  All rights
0008  *                         reserved.
0009  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0010  *                         University of Stuttgart.  All rights reserved.
0011  * Copyright (c) 2004-2005 The Regents of the University of California.
0012  *                         All rights reserved.
0013  * Copyright (c) 2011-2016 Los Alamos National Security, LLC. All rights
0014  *                         reserved.
0015  * Copyright (c) 2016-2019 Research Organization for Information Science
0016  *                         and Technology (RIST).  All rights reserved.
0017  * Copyright (c) 2017-2020 Intel, Inc.  All rights reserved.
0018  * Copyright (c) 2020      Cisco Systems, Inc.  All rights reserved
0019  * Copyright (c) 2021-2023 Nanook Consulting  All rights reserved.
0020  * $COPYRIGHT$
0021  *
0022  * Additional copyrights may follow
0023  *
0024  * $HEADER$
0025  */
0026 /** @file:
0027  *
0028  * The PRTE Group Communications
0029  *
0030  * The PRTE Group Comm framework provides communication services that
0031  * span entire jobs or collections of processes. It is not intended to be
0032  * used for point-to-point communications (the RML does that), nor should
0033  * it be viewed as a high-performance communication channel for large-scale
0034  * data transfers.
0035  */
0036
0037 #ifndef MCA_GRPCOMM_H
0038 #define MCA_GRPCOMM_H
0039
0040 /*
0041  * includes
0042  */
0043
0044 #include "prte_config.h"
0045 #include "constants.h"
0046 #include "types.h"
0047
0048 #include "src/class/pmix_bitmap.h"
0049 #include "src/class/pmix_list.h"
0050 #include "src/pmix/pmix-internal.h"
0051 #include "src/mca/mca.h"
0052 #include "src/rml/rml_types.h"
0053
0054 BEGIN_C_DECLS
0055
0056 /* define a callback function to be invoked upon
0057  * collective completion */
0058 typedef void (*prte_grpcomm_cbfunc_t)(int status, pmix_data_buffer_t *buf, void *cbdata);
0059
0060 typedef int (*prte_grpcomm_rbcast_cb_t)(pmix_data_buffer_t *buffer);
0061
0062 /* Define a collective signature so we don't need to
0063  * track global collective id's */
0064 typedef struct {
0065     pmix_object_t super;
0066     pmix_proc_t *signature;
0067     size_t sz;
0068 } prte_grpcomm_signature_t;
0069 PRTE_EXPORT PMIX_CLASS_DECLARATION(prte_grpcomm_signature_t);
0070
0071 /* Internal component object for tracking ongoing
0072  * allgather operations */
0073 typedef struct {
0074     pmix_list_item_t super;
0075     /* collective's signature */
0076     prte_grpcomm_signature_t *sig;
0077     pmix_status_t status;
0078     /* collection bucket */
0079     pmix_data_buffer_t bucket;
0080     /* participating daemons */
0081     pmix_rank_t *dmns;
0082     /** number of participating daemons */
0083     size_t ndmns;
0084     /** my index in the dmns array */
0085     unsigned long my_rank;
0086     /* number of buckets expected */
0087     size_t nexpected;
0088     /* number reported in */
0089     size_t nreported;
0090     /* controls values */
0091     bool assignID;
0092     int timeout;
0093     size_t memsize;
0094     pmix_list_t addmembers;
0095     /* distance masks for receive */
0096     pmix_bitmap_t distance_mask_recv;
0097     /* received buckets */
0098     pmix_data_buffer_t **buffers;
0099     /* callback function */
0100     prte_grpcomm_cbfunc_t cbfunc;
0101     /* user-provided callback data */
0102     void *cbdata;
0103 } prte_grpcomm_coll_t;
0104 PMIX_CLASS_DECLARATION(prte_grpcomm_coll_t);
0105
0106 typedef struct {
0107     pmix_object_t super;
0108     prte_event_t ev;
0109     prte_grpcomm_signature_t *sig;
0110     pmix_group_operation_t op;
0111     char *grpid;
0112     pmix_data_buffer_t *buf;
0113     pmix_byte_object_t ctrls;
0114     pmix_proc_t *procs;
0115     size_t nprocs;
0116     pmix_info_t *info;
0117     size_t ninfo;
0118     prte_grpcomm_cbfunc_t grpcbfunc;
0119     pmix_modex_cbfunc_t mdxcbfunc;
0120     pmix_info_cbfunc_t infocbfunc;
0121     pmix_op_cbfunc_t opcbfunc;
0122     void *cbdata;
0123     void *relcbdata;
0124 } prte_pmix_mdx_caddy_t;
0125 PMIX_CLASS_DECLARATION(prte_pmix_mdx_caddy_t);
0126
0127 /*
0128  * Component functions - all MUST be provided!
0129  */
0130
0131 /* initialize the selected module */
0132 typedef int (*prte_grpcomm_base_module_init_fn_t)(void);
0133
0134 /* finalize the selected module */
0135 typedef void (*prte_grpcomm_base_module_finalize_fn_t)(void);
0136
0137 /* Scalably send a message. Caller will provide an array
0138  * of daemon vpids that are to receive the message. A NULL
0139  * pointer indicates that all daemons are participating. */
0140 typedef int (*prte_grpcomm_base_module_xcast_fn_t)(pmix_rank_t *vpids, size_t nprocs,
0141                                                    pmix_data_buffer_t *msg);
0142
0143 /* allgather - gather data from all specified daemons. Barrier operations
0144  * will provide a zero-byte buffer. Caller will provide an array
0145  * of daemon vpids that are participating in the allgather via the
0146  * prte_grpcomm_coll_t object. A NULL pointer indicates that all daemons
0147  * are participating.
0148  *
0149  * NOTE: this is a non-blocking call. The callback function cached in
0150  * the prte_grpcomm_coll_t will be invoked upon completion. */
0151 typedef int (*prte_grpcomm_base_module_allgather_fn_t)(prte_grpcomm_coll_t *coll,
0152                                                        prte_pmix_mdx_caddy_t *cd);
0153
0154 /* Reliable broadcast a message thru BMG.
0155  * only need to provide a message buffer, dont need create dmns
0156  */
0157 typedef int (*prte_grpcomm_base_module_rbcast_fn_t)(pmix_data_buffer_t *msg);
0158
0159 typedef int (*prte_grpcomm_base_module_rbcast_register_cb_fn_t)(prte_grpcomm_rbcast_cb_t callback);
0160
0161 typedef int (*prte_grpcomm_base_module_rbcast_unregister_cb_fn_t)(int type);
0162
0163 /*
0164  * Ver 3.0 - internal modules
0165  */
0166 typedef struct {
0167     prte_grpcomm_base_module_init_fn_t init;
0168     prte_grpcomm_base_module_finalize_fn_t finalize;
0169     /* collective operations */
0170     prte_grpcomm_base_module_xcast_fn_t xcast;
0171     prte_grpcomm_base_module_allgather_fn_t allgather;
0172     prte_grpcomm_base_module_rbcast_fn_t rbcast;
0173     prte_grpcomm_base_module_rbcast_register_cb_fn_t register_cb;
0174     prte_grpcomm_base_module_rbcast_unregister_cb_fn_t unregister_cb;
0175 } prte_grpcomm_base_module_t;
0176
0177 /* the Public APIs */
0178 /* Scalably send a message. Caller will provide an array
0179  * of process names that are to receive the message. A NULL
0180  * pointer indicates that all known procs are to receive
0181  * the message. A pointer to a name that includes PRTE_VPID_WILDCARD
0182  * will send the message to all procs in the specified jobid.
0183  * The message will be sent to the daemons hosting the specified
0184  * procs for processing and relay. */
0185 typedef int (*prte_grpcomm_base_API_xcast_fn_t)(prte_grpcomm_signature_t *sig, prte_rml_tag_t tag,
0186                                                 pmix_data_buffer_t *msg);
0187
0188 /* allgather - gather data from all specified procs. Barrier operations
0189  * will provide a zero-byte buffer. Caller will provide an array
0190  * of application proc vpids that are participating in the allgather. A NULL
0191  * pointer indicates that all known procs are participating. A pointer
0192  * to a name that includes PRTE_VPID_WILDCARD indicates that all procs
0193  * in the specified jobid are contributing.
0194  *
0195  * NOTE: this is a non-blocking call. The provided callback function
0196  * will be invoked upon completion. */
0197 typedef int (*prte_grpcomm_base_API_allgather_fn_t)(prte_pmix_mdx_caddy_t *cd);
0198
0199 /* Reliable broadcast a message. Caller will provide an array
0200  * of daemon. A NULL pointer indicates that all known daemons are in the BMG.
0201  * A pointer to a name that includes ORTE_VPID_WILDCARD
0202  * all daemons in the specified jobid.*/
0203 typedef int (*prte_grpcomm_base_API_rbcast_fn_t)(prte_grpcomm_signature_t *sig, prte_rml_tag_t tag,
0204                                                  pmix_data_buffer_t *msg);
0205
0206 typedef int (*prte_grpcomm_base_API_rbcast_register_cb_fn_t)(prte_grpcomm_rbcast_cb_t callback);
0207
0208 typedef int (*prte_grpcomm_base_API_rbcast_unregister_cb_fn_t)(int type);
0209
0210 typedef struct {
0211     /* collective operations */
0212     prte_grpcomm_base_API_xcast_fn_t xcast;
0213     prte_grpcomm_base_API_allgather_fn_t allgather;
0214     prte_grpcomm_base_API_rbcast_fn_t rbcast;
0215     prte_grpcomm_base_API_rbcast_register_cb_fn_t register_cb;
0216     prte_grpcomm_base_API_rbcast_unregister_cb_fn_t unregister_cb;
0217 } prte_grpcomm_API_module_t;
0218
0219 /*
0220  * the standard component data structure
0221  */
0222 typedef pmix_mca_base_component_t prte_grpcomm_base_component_t;
0223
0224 /*
0225  * Macro for use in components that are of type grpcomm v3.0.0
0226  */
0227 #define PRTE_GRPCOMM_BASE_VERSION_3_0_0       \
0228     /* grpcomm v3.0 is chained to MCA v2.0 */ \
0229     PRTE_MCA_BASE_VERSION_3_0_0("grpcomm", 3, 0, 0)
0230
0231 /* Global structure for accessing grpcomm functions */
0232 PRTE_EXPORT extern prte_grpcomm_API_module_t prte_grpcomm;
0233
0234 END_C_DECLS
0235
0236 #endif