oob/base/base.h

0001 /*
0002  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0003  *                         University Research and Technology
0004  *                         Corporation.  All rights reserved.
0005  * Copyright (c) 2004-2005 The University of Tennessee and The University
0006  *                         of Tennessee Research Foundation.  All rights
0007  *                         reserved.
0008  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0009  *                         University of Stuttgart.  All rights reserved.
0010  * Copyright (c) 2004-2005 The Regents of the University of California.
0011  *                         All rights reserved.
0012  * Copyright (c) 2012-2013 Los Alamos National Security, LLC. All rights
0013  *                         reserved.
0014  * Copyright (c) 2017-2019 Intel, Inc.  All rights reserved.
0015  * Copyright (c) 2019      Research Organization for Information Science
0016  *                         and Technology (RIST).  All rights reserved.
0017  * Copyright (c) 2020      Cisco Systems, Inc.  All rights reserved
0018  * Copyright (c) 2021-2023 Nanook Consulting.  All rights reserved.
0019  * $COPYRIGHT$
0020  *
0021  * Additional copyrights may follow
0022  *
0023  * $HEADER$
0024  */
0025 /** @file:
0026  *
0027  * the oob framework
0028  */
0029
0030 #ifndef _MCA_OOB_BASE_H_
0031 #define _MCA_OOB_BASE_H_
0032
0033 #include "prte_config.h"
0034
0035 #ifdef HAVE_UNISTD_H
0036 #    include <unistd.h>
0037 #endif
0038 #ifdef HAVE_SYS_UIO_H
0039 #    include <sys/uio.h>
0040 #endif
0041 #ifdef HAVE_NET_UIO_H
0042 #    include <net/uio.h>
0043 #endif
0044
0045 #include "src/class/pmix_bitmap.h"
0046 #include "src/class/pmix_hash_table.h"
0047 #include "src/class/pmix_list.h"
0048 #include "src/event/event-internal.h"
0049 #include "src/util/pmix_printf.h"
0050
0051 #include "src/mca/mca.h"
0052 #include "src/threads/pmix_threads.h"
0053
0054 #include "src/mca/oob/oob.h"
0055
0056 BEGIN_C_DECLS
0057
0058 /*
0059  * Convenience Typedef
0060  */
0061 typedef struct {
0062     char *include;
0063     char *exclude;
0064     pmix_list_t components;
0065     pmix_list_t actives;
0066     int max_uri_length;
0067     pmix_list_t peers;
0068 } prte_oob_base_t;
0069 PRTE_EXPORT extern prte_oob_base_t prte_oob_base;
0070
0071 typedef struct {
0072     pmix_list_item_t super;
0073     pmix_proc_t name;
0074     prte_oob_base_component_t *component;
0075     pmix_bitmap_t addressable;
0076 } prte_oob_base_peer_t;
0077 PRTE_EXPORT PMIX_CLASS_DECLARATION(prte_oob_base_peer_t);
0078
0079 /* MCA framework */
0080 PRTE_EXPORT extern pmix_mca_base_framework_t prte_oob_base_framework;
0081 PRTE_EXPORT int prte_oob_base_select(void);
0082
0083 /* Access the OOB internal functions via set of event-based macros
0084  * for inserting messages and other commands into the
0085  * OOB event base. This ensures that all OOB operations occur
0086  * asynchronously in a thread-safe environment.
0087  * Note that this doesn't mean that messages will be *sent*
0088  * in order as that depends on the specific transport being
0089  * used, when that module's event base indicates the transport
0090  * is available, etc.
0091  */
0092 typedef struct {
0093     pmix_object_t super;
0094     prte_event_t ev;
0095     prte_rml_send_t *msg;
0096 } prte_oob_send_t;
0097 PRTE_EXPORT PMIX_CLASS_DECLARATION(prte_oob_send_t);
0098
0099 /* All OOB sends are based on iovec's and are async as the RML
0100  * acts as the initial interface to prepare all communications.
0101  * The send_nb function will enter the message into the OOB
0102  * base, which will then check to see if a transport for the
0103  * intended target has already been assigned. If so, the message
0104  * is immediately placed into that module's event base for
0105  * transmission. If not, the function will loop across all available
0106  * components until one identifies that it has a module capable
0107  * of reaching the target.
0108  */
0109 typedef void (*mca_oob_send_callback_fn_t)(int status, struct iovec *iov, int count, void *cbdata);
0110
0111 PRTE_EXPORT void prte_oob_base_send_nb(int fd, short args, void *cbdata);
0112 #define PRTE_OOB_SEND(m)                                                                          \
0113     do {                                                                                          \
0114         prte_oob_send_t *prte_oob_send_cd;                                                        \
0115         pmix_output_verbose(1, prte_oob_base_framework.framework_output, "%s OOB_SEND: %s:%d",    \
0116                             PRTE_NAME_PRINT(PRTE_PROC_MY_NAME), __FILE__, __LINE__);              \
0117         prte_oob_send_cd = PMIX_NEW(prte_oob_send_t);                                             \
0118         prte_oob_send_cd->msg = (m);                                                              \
0119         PRTE_PMIX_THREADSHIFT(prte_oob_send_cd, prte_event_base, prte_oob_base_send_nb);          \
0120     } while (0)
0121
0122 PRTE_EXPORT prte_oob_base_peer_t *prte_oob_base_get_peer(const pmix_proc_t *pr);
0123
0124 /* During initial wireup, we can only transfer contact info on the daemon
0125  * command line. This limits what we can send to a string representation of
0126  * the actual contact info, which gets sent in a uri-like form. Not every
0127  * oob module can support this transaction, so this function will loop
0128  * across all oob components/modules, letting each add to the uri string if
0129  * it supports bootstrap operations. An error will be returned in the cbfunc
0130  * if NO component can successfully provide a contact.
0131  *
0132  * Note: since there is a limit to what an OS will allow on a cmd line, we
0133  * impose a limit on the length of the resulting uri via an MCA param. The
0134  * default value of -1 implies unlimited - however, users with large numbers
0135  * of interfaces on their nodes may wish to restrict the size.
0136  *
0137  * Since all components define their address info at component start,
0138  * it is unchanged and does not require acess via event
0139  */
0140 PRTE_EXPORT void prte_oob_base_get_addr(char **uri);
0141
0142 END_C_DECLS
0143 #endif