openpmix-src 0.1.0-rc.1

/* -*- Mode: C; c-basic-offset:4 ; -*- */
/*
 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
 *                         University Research and Technology
 *                         Corporation.  All rights reserved.
 * Copyright (c) 2004-2005 The University of Tennessee and The University
 *                         of Tennessee Research Foundation.  All rights
 *                         reserved.
 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
 *                         University of Stuttgart.  All rights reserved.
 * Copyright (c) 2004-2005 The Regents of the University of California.
 *                         All rights reserved.
 * Copyright (c) 2012      Los Alamos National Security, Inc. All rights reserved.
 * Copyright (c) 2013-2020 Intel, Inc.  All rights reserved.
 * Copyright (c) 2015      Research Organization for Information Science
 *                         and Technology (RIST). All rights reserved.
 * Copyright (c) 2016      Mellanox Technologies, Inc.
 *                         All rights reserved.
 * Copyright (c) 2021-2024 Nanook Consulting  All rights reserved.
 * $COPYRIGHT$
 *
 * Additional copyrights may follow
 *
 * $HEADER$
 */
/**
 * @file
 *
 * Data packing subsystem.
 */

#ifndef PMIX_PTL_H_
#define PMIX_PTL_H_

#include "src/include/pmix_config.h"

#include "src/include/pmix_types.h"

#include "src/mca/base/pmix_mca_base_framework.h"
#include "src/mca/base/pmix_mca_base_var.h"
#include "src/mca/bfrops/bfrops_types.h"
#include "src/mca/mca.h"

#include "ptl_types.h"

BEGIN_C_DECLS

/* forward declaration */
struct pmix_peer_t;

/* The overall objective of this framework is to provide transport
 * options by which a server can communicate with a client:
 *
 * (a) across different versions of the library - e.g., when the
 *     connection handshake changes.
 *
 * (b) using different transports as necessitated by different
 *     environments.
 *
 * This is a single-select framework - i.e., only one component
 * is selected and "active" at a time. The intent is
 * to have one component for each use-case, with the
 * expectation that the community will do its best not to revise
 * communications in manners that expand components to support (a).
 * Thus, new variations should be rare, and only a few components
 * will exist.
 */

/****    MODULE INTERFACE DEFINITION    ****/

/* initialize the active plugin */
typedef pmix_status_t (*pmix_ptl_init_fn_t)(void);

/* finalize the active plugin */
typedef void (*pmix_ptl_finalize_fn_t)(void);

/* (ONE-WAY) register a persistent recv */
typedef pmix_status_t (*pmix_ptl_recv_fn_t)(struct pmix_peer_t *peer, pmix_ptl_cbfunc_t cbfunc,
                                            pmix_ptl_tag_t tag);

/* Cancel a persistent recv */
typedef pmix_status_t (*pmix_ptl_cancel_fn_t)(struct pmix_peer_t *peer, pmix_ptl_tag_t tag);

/* connect to a peer - this is a blocking function
 * to establish a connection to a peer*/
typedef pmix_status_t (*pmix_ptl_connect_to_peer_fn_t)(struct pmix_peer_t *peer,
                                                       pmix_info_t info[],
                                                       size_t ninfo,
                                                       char **suri);

/* query available servers on the local node */
typedef void (*pmix_ptl_query_servers_fn_t)(char *dirname, pmix_list_t *servers);

/* define an API for establishing a
 * communication rendezvous point for local procs. The active component
 * is given an opportunity to register a listener with the
 * PTL base */
typedef pmix_status_t (*pmix_ptl_setup_listener_fn_t)(pmix_info_t info[], size_t ninfo);

/* define an API for obtaining any envars that are to
 * be passed to client procs upon fork */
typedef pmix_status_t (*pmix_ptl_setup_fork_fn_t)(const pmix_proc_t *proc, char ***env);

/**
 * Base structure for a PTL module
 */
struct pmix_ptl_module_t {
    char *name;
    pmix_ptl_init_fn_t init;
    pmix_ptl_finalize_fn_t finalize;
    pmix_ptl_recv_fn_t recv;
    pmix_ptl_cancel_fn_t cancel;
    pmix_ptl_connect_to_peer_fn_t connect_to_peer;
    pmix_ptl_query_servers_fn_t query_servers;
    pmix_ptl_setup_listener_fn_t setup_listener;
    pmix_ptl_setup_fork_fn_t setup_fork;
};
typedef struct pmix_ptl_module_t pmix_ptl_module_t;

/*****    MACROS FOR EXECUTING PTL FUNCTIONS    *****/

/* (TWO-WAY) send a message to the peer, and get a response delivered
 * to the specified callback function. The buffer will be free'd
 * at the completion of the send, and the cbfunc will be called
 * when the corresponding reply is received */
#define PMIX_PTL_SEND_RECV(r, p, b, c, d)                  \
    do {                                                   \
        pmix_ptl_sr_t *ms;                                 \
        pmix_peer_t *pr = (pmix_peer_t *) (p);             \
        if ((p)->finalized) {                              \
            (r) = PMIX_ERR_UNREACH;                        \
        } else {                                           \
            ms = PMIX_NEW(pmix_ptl_sr_t);                  \
            PMIX_RETAIN(pr);                               \
            ms->peer = pr;                                 \
            ms->bfr = (b);                                 \
            ms->cbfunc = (c);                              \
            ms->cbdata = (d);                              \
            PMIX_THREADSHIFT(ms, pmix_ptl_base_send_recv); \
            (r) = PMIX_SUCCESS;                            \
        }                                                  \
    } while (0)

/* (ONE-WAY) send a message to the peer. The buffer will be free'd
 * at the completion of the send */
#define PMIX_PTL_SEND_ONEWAY(r, p, b, t)             \
    do {                                             \
        pmix_ptl_queue_t *q;                         \
        pmix_peer_t *pr = (pmix_peer_t *) (p);       \
        if ((p)->finalized) {                        \
            (r) = PMIX_ERR_UNREACH;                  \
        } else {                                     \
            q = PMIX_NEW(pmix_ptl_queue_t);          \
            PMIX_RETAIN(pr);                         \
            q->peer = pr;                            \
            q->buf = (b);                            \
            q->tag = (t);                            \
            PMIX_THREADSHIFT(q, pmix_ptl_base_send); \
            (r) = PMIX_SUCCESS;                      \
        }                                            \
    } while (0)

#define PMIX_PTL_RECV(r, c, t)                                               \
    do {                                                                     \
        pmix_ptl_posted_recv_t *req;                                         \
        req = PMIX_NEW(pmix_ptl_posted_recv_t);                              \
        if (NULL == req) {                                                   \
            (r) = PMIX_ERR_NOMEM;                                            \
        } else {                                                             \
            req->tag = (t);                                                  \
            req->cbfunc = (c);                                               \
            pmix_event_assign(&(req->ev), pmix_globals.evbase, -1, EV_WRITE, \
                              pmix_ptl_base_post_recv, req);                 \
            pmix_event_active(&(req->ev), EV_WRITE, 1);                      \
            (r) = PMIX_SUCCESS;                                              \
        }                                                                    \
    } while (0)

#define PMIX_PTL_CANCEL(r, t)                                                \
    do {                                                                     \
        pmix_ptl_posted_recv_t *req;                                         \
        req = PMIX_NEW(pmix_ptl_posted_recv_t);                              \
        if (NULL == req) {                                                   \
            (r) = PMIX_ERR_NOMEM;                                            \
        } else {                                                             \
            req->tag = (t);                                                  \
            pmix_event_assign(&(req->ev), pmix_globals.evbase, -1, EV_WRITE, \
                              pmix_ptl_base_cancel_recv, req);               \
            pmix_event_active(&(req->ev), EV_WRITE, 1);                      \
            (r) = PMIX_SUCCESS;                                              \
        }                                                                    \
    } while (0)

/* expose functions used by the macros */
PMIX_EXPORT extern void pmix_ptl_base_send(int sd, short args, void *cbdata);
PMIX_EXPORT extern void pmix_ptl_base_send_recv(int sd, short args, void *cbdata);
PMIX_EXPORT extern void pmix_ptl_base_register_recv(int sd, short args, void *cbdata);
PMIX_EXPORT extern void pmix_ptl_base_cancel_recv(int sd, short args, void *cbdata);

/****    COMPONENT STRUCTURE DEFINITION    ****/

/*
 * the standard component data structure
 */
struct pmix_ptl_base_component_t {
    pmix_mca_base_component_t base;
    int priority;
    char *uri;
};
typedef struct pmix_ptl_base_component_t pmix_ptl_base_component_t;

/* export the PTL module struct */
PMIX_EXPORT extern pmix_ptl_module_t pmix_ptl;

/*
 * Macro for use in components that are of type ptl
 */
#define PMIX_PTL_BASE_VERSION_2_0_0 PMIX_MCA_BASE_VERSION_1_0_0("ptl", 2, 0, 0)

END_C_DECLS

#endif /* PMIX_PTL_H */