mca/ptl/ptl.h

0001 /* -*- Mode: C; c-basic-offset:4 ; -*- */
0002 /*
0003  * Copyright (c) 2004-2005 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) 2012      Los Alamos National Security, Inc. All rights reserved.
0014  * Copyright (c) 2013-2020 Intel, Inc.  All rights reserved.
0015  * Copyright (c) 2015      Research Organization for Information Science
0016  *                         and Technology (RIST). All rights reserved.
0017  * Copyright (c) 2016      Mellanox Technologies, Inc.
0018  *                         All rights reserved.
0019  * Copyright (c) 2021-2024 Nanook Consulting  All rights reserved.
0020  * $COPYRIGHT$
0021  *
0022  * Additional copyrights may follow
0023  *
0024  * $HEADER$
0025  */
0026 /**
0027  * @file
0028  *
0029  * Data packing subsystem.
0030  */
0031
0032 #ifndef PMIX_PTL_H_
0033 #define PMIX_PTL_H_
0034
0035 #include "src/include/pmix_config.h"
0036
0037 #include "src/include/pmix_types.h"
0038
0039 #include "src/mca/base/pmix_mca_base_framework.h"
0040 #include "src/mca/base/pmix_mca_base_var.h"
0041 #include "src/mca/bfrops/bfrops_types.h"
0042 #include "src/mca/mca.h"
0043
0044 #include "ptl_types.h"
0045
0046 BEGIN_C_DECLS
0047
0048 /* forward declaration */
0049 struct pmix_peer_t;
0050
0051 /* The overall objective of this framework is to provide transport
0052  * options by which a server can communicate with a client:
0053  *
0054  * (a) across different versions of the library - e.g., when the
0055  *     connection handshake changes.
0056  *
0057  * (b) using different transports as necessitated by different
0058  *     environments.
0059  *
0060  * This is a single-select framework - i.e., only one component
0061  * is selected and "active" at a time. The intent is
0062  * to have one component for each use-case, with the
0063  * expectation that the community will do its best not to revise
0064  * communications in manners that expand components to support (a).
0065  * Thus, new variations should be rare, and only a few components
0066  * will exist.
0067  */
0068
0069 /****    MODULE INTERFACE DEFINITION    ****/
0070
0071 /* initialize the active plugin */
0072 typedef pmix_status_t (*pmix_ptl_init_fn_t)(void);
0073
0074 /* finalize the active plugin */
0075 typedef void (*pmix_ptl_finalize_fn_t)(void);
0076
0077 /* (ONE-WAY) register a persistent recv */
0078 typedef pmix_status_t (*pmix_ptl_recv_fn_t)(struct pmix_peer_t *peer, pmix_ptl_cbfunc_t cbfunc,
0079                                             pmix_ptl_tag_t tag);
0080
0081 /* Cancel a persistent recv */
0082 typedef pmix_status_t (*pmix_ptl_cancel_fn_t)(struct pmix_peer_t *peer, pmix_ptl_tag_t tag);
0083
0084 /* connect to a peer - this is a blocking function
0085  * to establish a connection to a peer*/
0086 typedef pmix_status_t (*pmix_ptl_connect_to_peer_fn_t)(struct pmix_peer_t *peer,
0087                                                        pmix_info_t info[],
0088                                                        size_t ninfo,
0089                                                        char **suri);
0090
0091 /* query available servers on the local node */
0092 typedef void (*pmix_ptl_query_servers_fn_t)(char *dirname, pmix_list_t *servers);
0093
0094 /* define an API for establishing a
0095  * communication rendezvous point for local procs. The active component
0096  * is given an opportunity to register a listener with the
0097  * PTL base */
0098 typedef pmix_status_t (*pmix_ptl_setup_listener_fn_t)(pmix_info_t info[], size_t ninfo);
0099
0100 /* define an API for obtaining any envars that are to
0101  * be passed to client procs upon fork */
0102 typedef pmix_status_t (*pmix_ptl_setup_fork_fn_t)(const pmix_proc_t *proc, char ***env);
0103
0104 /**
0105  * Base structure for a PTL module
0106  */
0107 struct pmix_ptl_module_t {
0108     char *name;
0109     pmix_ptl_init_fn_t init;
0110     pmix_ptl_finalize_fn_t finalize;
0111     pmix_ptl_recv_fn_t recv;
0112     pmix_ptl_cancel_fn_t cancel;
0113     pmix_ptl_connect_to_peer_fn_t connect_to_peer;
0114     pmix_ptl_query_servers_fn_t query_servers;
0115     pmix_ptl_setup_listener_fn_t setup_listener;
0116     pmix_ptl_setup_fork_fn_t setup_fork;
0117 };
0118 typedef struct pmix_ptl_module_t pmix_ptl_module_t;
0119
0120 /*****    MACROS FOR EXECUTING PTL FUNCTIONS    *****/
0121
0122 /* (TWO-WAY) send a message to the peer, and get a response delivered
0123  * to the specified callback function. The buffer will be free'd
0124  * at the completion of the send, and the cbfunc will be called
0125  * when the corresponding reply is received */
0126 #define PMIX_PTL_SEND_RECV(r, p, b, c, d)                  \
0127     do {                                                   \
0128         pmix_ptl_sr_t *ms;                                 \
0129         pmix_peer_t *pr = (pmix_peer_t *) (p);             \
0130         if ((p)->finalized) {                              \
0131             (r) = PMIX_ERR_UNREACH;                        \
0132         } else {                                           \
0133             ms = PMIX_NEW(pmix_ptl_sr_t);                  \
0134             PMIX_RETAIN(pr);                               \
0135             ms->peer = pr;                                 \
0136             ms->bfr = (b);                                 \
0137             ms->cbfunc = (c);                              \
0138             ms->cbdata = (d);                              \
0139             PMIX_THREADSHIFT(ms, pmix_ptl_base_send_recv); \
0140             (r) = PMIX_SUCCESS;                            \
0141         }                                                  \
0142     } while (0)
0143
0144 /* (ONE-WAY) send a message to the peer. The buffer will be free'd
0145  * at the completion of the send */
0146 #define PMIX_PTL_SEND_ONEWAY(r, p, b, t)             \
0147     do {                                             \
0148         pmix_ptl_queue_t *q;                         \
0149         pmix_peer_t *pr = (pmix_peer_t *) (p);       \
0150         if ((p)->finalized) {                        \
0151             (r) = PMIX_ERR_UNREACH;                  \
0152         } else {                                     \
0153             q = PMIX_NEW(pmix_ptl_queue_t);          \
0154             PMIX_RETAIN(pr);                         \
0155             q->peer = pr;                            \
0156             q->buf = (b);                            \
0157             q->tag = (t);                            \
0158             PMIX_THREADSHIFT(q, pmix_ptl_base_send); \
0159             (r) = PMIX_SUCCESS;                      \
0160         }                                            \
0161     } while (0)
0162
0163 #define PMIX_PTL_RECV(r, c, t)                                               \
0164     do {                                                                     \
0165         pmix_ptl_posted_recv_t *req;                                         \
0166         req = PMIX_NEW(pmix_ptl_posted_recv_t);                              \
0167         if (NULL == req) {                                                   \
0168             (r) = PMIX_ERR_NOMEM;                                            \
0169         } else {                                                             \
0170             req->tag = (t);                                                  \
0171             req->cbfunc = (c);                                               \
0172             pmix_event_assign(&(req->ev), pmix_globals.evbase, -1, EV_WRITE, \
0173                               pmix_ptl_base_post_recv, req);                 \
0174             pmix_event_active(&(req->ev), EV_WRITE, 1);                      \
0175             (r) = PMIX_SUCCESS;                                              \
0176         }                                                                    \
0177     } while (0)
0178
0179 #define PMIX_PTL_CANCEL(r, t)                                                \
0180     do {                                                                     \
0181         pmix_ptl_posted_recv_t *req;                                         \
0182         req = PMIX_NEW(pmix_ptl_posted_recv_t);                              \
0183         if (NULL == req) {                                                   \
0184             (r) = PMIX_ERR_NOMEM;                                            \
0185         } else {                                                             \
0186             req->tag = (t);                                                  \
0187             pmix_event_assign(&(req->ev), pmix_globals.evbase, -1, EV_WRITE, \
0188                               pmix_ptl_base_cancel_recv, req);               \
0189             pmix_event_active(&(req->ev), EV_WRITE, 1);                      \
0190             (r) = PMIX_SUCCESS;                                              \
0191         }                                                                    \
0192     } while (0)
0193
0194 /* expose functions used by the macros */
0195 PMIX_EXPORT extern void pmix_ptl_base_send(int sd, short args, void *cbdata);
0196 PMIX_EXPORT extern void pmix_ptl_base_send_recv(int sd, short args, void *cbdata);
0197 PMIX_EXPORT extern void pmix_ptl_base_register_recv(int sd, short args, void *cbdata);
0198 PMIX_EXPORT extern void pmix_ptl_base_cancel_recv(int sd, short args, void *cbdata);
0199
0200 /****    COMPONENT STRUCTURE DEFINITION    ****/
0201
0202 /*
0203  * the standard component data structure
0204  */
0205 struct pmix_ptl_base_component_t {
0206     pmix_mca_base_component_t base;
0207     int priority;
0208     char *uri;
0209 };
0210 typedef struct pmix_ptl_base_component_t pmix_ptl_base_component_t;
0211
0212 /* export the PTL module struct */
0213 PMIX_EXPORT extern pmix_ptl_module_t pmix_ptl;
0214
0215 /*
0216  * Macro for use in components that are of type ptl
0217  */
0218 #define PMIX_PTL_BASE_VERSION_2_0_0 PMIX_MCA_BASE_VERSION_1_0_0("ptl", 2, 0, 0)
0219
0220 END_C_DECLS
0221
0222 #endif /* PMIX_PTL_H */