mca/pnet/pnet.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2007-2008 Cisco Systems, Inc.  All rights reserved.
0004  *
0005  * Copyright (c) 2015-2018 Research Organization for Information Science
0006  *                         and Technology (RIST). All rights reserved.
0007  * Copyright (c) 2018-2020 Intel, Inc.  All rights reserved.
0008  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0009  * $COPYRIGHT$
0010  *
0011  * Additional copyrights may follow
0012  *
0013  * $HEADER$
0014  */
0015
0016 /**
0017  * @file
0018  *
0019  * This interface is for use by PMIx servers to obtain network-related info
0020  * such as security keys that need to be shared across applications, and to
0021  * setup network support for applications prior to launch
0022  *
0023  * Available plugins may be defined at runtime via the typical MCA parameter
0024  * syntax.
0025  */
0026
0027 #ifndef PMIX_PNET_H
0028 #define PMIX_PNET_H
0029
0030 #include "src/include/pmix_config.h"
0031 #include "include/pmix.h"
0032
0033 #include "src/class/pmix_list.h"
0034 #include "src/include/pmix_globals.h"
0035 #include "src/mca/base/pmix_mca_base_framework.h"
0036 #include "src/mca/base/pmix_mca_base_var.h"
0037 #include "src/mca/mca.h"
0038 #include "src/server/pmix_server_ops.h"
0039
0040 BEGIN_C_DECLS
0041
0042 /******    MODULE DEFINITION    ******/
0043
0044 /**
0045  * Initialize the module. Returns an error if the module cannot
0046  * run, success if it can and wants to be used.
0047  */
0048 typedef pmix_status_t (*pmix_pnet_base_module_init_fn_t)(void);
0049
0050 /**
0051  * Finalize the module. Tear down any allocated storage, disconnect
0052  * from any system support (e.g., LDAP server)
0053  */
0054 typedef void (*pmix_pnet_base_module_fini_fn_t)(void);
0055
0056 /**
0057  * Allocate network resources. This can be called either as a result
0058  * of a call to PMIx_Allocate_resources, or by the scheduler to
0059  * provide an opportunity for the network to define values that
0060  * are to be passed to an application. This can include security
0061  * tokens required for application processes to communicate with
0062  * each other, environmental variables picked up at the login node
0063  * for forwarding to compute nodes, or allocation of static endpts
0064  */
0065 typedef pmix_status_t (*pmix_pnet_base_module_allocate_fn_t)(pmix_namespace_t *nptr,
0066                                                              pmix_info_t info[], size_t ninfo,
0067                                                              pmix_list_t *ilist);
0068
0069 /**
0070  * Give the local network library an opportunity to setup address information
0071  * for the application by passing in the layout type and a regex describing
0072  * the layout */
0073 typedef pmix_status_t (*pmix_pnet_base_module_setup_local_net_fn_t)(pmix_nspace_env_cache_t *nptr,
0074                                                                     pmix_info_t info[],
0075                                                                     size_t ninfo);
0076
0077
0078 /**
0079  * Provide an opportunity for the local network library to cleanup when a
0080  * local application process terminates
0081  */
0082 typedef void (*pmix_pnet_base_module_child_finalized_fn_t)(pmix_proc_t *peer);
0083
0084 /**
0085  * Provide  an opportunity for the local network library to cleanup after
0086  * all local clients for a given application have terminated
0087  */
0088 typedef void (*pmix_pnet_base_module_local_app_finalized_fn_t)(pmix_namespace_t *nptr);
0089
0090 /**
0091  * Provide an opportunity for the fabric components to cleanup any
0092  * resource allocations (e.g., static ports) they may have assigned
0093  */
0094 typedef void (*pmix_pnet_base_module_dregister_nspace_fn_t)(pmix_namespace_t *nptr);
0095
0096 /**
0097  * Request that the module report local inventory for its network type.
0098  *
0099  * If the operation can be performed immediately, then the module should just
0100  * add the inventory (as pmix_kval_t's) to the provided object's list and
0101  * return PMIX_SUCCESS.
0102  *
0103  * If the module needs to perform some non-atomic operation
0104  * (e.g., query a fabric manager), then it should shift to its own internal
0105  * thread, return PMIX_OPERATION_IN_PROGRESS, and execute the provided
0106  * callback function when the operation is completed.
0107  *
0108  * If there is no inventory to report, then just return PMIX_SUCCESS.
0109  *
0110  * If the module should be providing inventory but encounters an error,
0111  * then immediately return an error code if the error is immediately detected,
0112  * or execute the callback function with an error code if it is detected later.
0113  */
0114 typedef pmix_status_t (*pmix_pnet_base_module_collect_inventory_fn_t)(
0115     pmix_info_t directives[], size_t ndirs, pmix_list_t *inventory);
0116
0117 /**
0118  * Deliver inventory for archiving by corresponding modules
0119  *
0120  * Modules are to search the provided inventory to identify
0121  * entries provided by their remote peers, and then store that
0122  * information in a manner that can be queried/retrieved by
0123  * the host RM and/or scheduler. If the operation can be
0124  * performed immediately (e.g., storing the information in
0125  * the local hash table), then the module should just perform
0126  * that operation and return the appropriate status.
0127  *
0128  * If the module needs to perform some non-atomic operation
0129  * (e.g., storing the information in a non-local DHT), then
0130  * it should shift to its own internal thread, return
0131  * PMIX_OPERATION_IN_PROGRESS, and execute the provided
0132  * callback function when the operation is completed.
0133  *
0134  * If there is no relevant inventory to archive, then the module
0135  * should just return PMIX_SUCCESS;
0136  */
0137 typedef pmix_status_t (*pmix_pnet_base_module_deliver_inventory_fn_t)(
0138     pmix_info_t info[], size_t ninfo, pmix_info_t directives[], size_t ndirs);
0139
0140 /* Register to provide cost information
0141  *
0142  * Scan the provided directives to identify if the module
0143  * should service this request - directives could include
0144  * ordered specification of fabric type or a direct request
0145  * for a specific component
0146  */
0147 typedef pmix_status_t (*pmix_pnet_base_module_register_fabric_fn_t)(pmix_fabric_t *fabric,
0148                                                                     const pmix_info_t directives[],
0149                                                                     size_t ndirs,
0150                                                                     pmix_op_cbfunc_t cbfunc,
0151                                                                     void *cbdata);
0152
0153 /* Update the fabric information */
0154 typedef pmix_status_t (*pmix_pnet_base_module_update_fabric_fn_t)(pmix_fabric_t *fabric);
0155
0156 /* Deregister the fabric, giving the associated module a chance to cleanup */
0157 typedef pmix_status_t (*pmix_pnet_base_module_deregister_fabric_fn_t)(pmix_fabric_t *fabric);
0158
0159 /**
0160  * Base structure for a PNET module. Each component should malloc a
0161  * copy of the module structure for each fabric plane they support.
0162  */
0163 typedef struct {
0164     char *name;
0165     /* provide a pointer to plane-specific metadata */
0166     void *plane;
0167     /* init/finalize */
0168     pmix_pnet_base_module_init_fn_t init;
0169     pmix_pnet_base_module_fini_fn_t finalize;
0170     pmix_pnet_base_module_allocate_fn_t allocate;
0171     pmix_pnet_base_module_setup_local_net_fn_t setup_local_network;
0172     pmix_pnet_base_module_child_finalized_fn_t child_finalized;
0173     pmix_pnet_base_module_local_app_finalized_fn_t local_app_finalized;
0174     pmix_pnet_base_module_dregister_nspace_fn_t deregister_nspace;
0175     pmix_pnet_base_module_collect_inventory_fn_t collect_inventory;
0176     pmix_pnet_base_module_deliver_inventory_fn_t deliver_inventory;
0177     pmix_pnet_base_module_register_fabric_fn_t register_fabric;
0178     pmix_pnet_base_module_update_fabric_fn_t update_fabric;
0179     pmix_pnet_base_module_deregister_fabric_fn_t deregister_fabric;
0180 } pmix_pnet_module_t;
0181
0182 /* define a few API versions of the functions - main difference is the
0183  * string nspace parameter instead of a pointer to pmix_namespace_t. This
0184  * is done as an optimization to avoid having every component look for
0185  * that pointer */
0186 typedef pmix_status_t (*pmix_pnet_base_API_allocate_fn_t)(char *nspace, pmix_info_t info[],
0187                                                           size_t ninfo, pmix_list_t *ilist);
0188 typedef pmix_status_t (*pmix_pnet_base_API_setup_local_net_fn_t)(char *nspace, pmix_info_t info[],
0189                                                                  size_t ninfo);
0190 /**
0191  * Give the network framework an opportunity to add any envars to the
0192  * environment of a local application process prior to fork/exec
0193  */
0194 typedef pmix_status_t (*pmix_pnet_base_API_setup_fork_fn_t)(const pmix_proc_t *peer, char ***env);
0195
0196 typedef void (*pmix_pnet_base_API_deregister_nspace_fn_t)(char *nspace);
0197
0198 /**
0199  * Base structure for a PNET API
0200  */
0201 typedef struct {
0202     char *name;
0203     /* init/finalize */
0204     pmix_pnet_base_module_init_fn_t init;
0205     pmix_pnet_base_module_fini_fn_t finalize;
0206     pmix_pnet_base_API_allocate_fn_t allocate;
0207     pmix_pnet_base_API_setup_local_net_fn_t setup_local_network;
0208     pmix_pnet_base_API_setup_fork_fn_t setup_fork;
0209     pmix_pnet_base_module_child_finalized_fn_t child_finalized;
0210     pmix_pnet_base_module_local_app_finalized_fn_t local_app_finalized;
0211     pmix_pnet_base_API_deregister_nspace_fn_t deregister_nspace;
0212     pmix_pnet_base_module_collect_inventory_fn_t collect_inventory;
0213     pmix_pnet_base_module_deliver_inventory_fn_t deliver_inventory;
0214     pmix_pnet_base_module_register_fabric_fn_t register_fabric;
0215     pmix_pnet_base_module_update_fabric_fn_t update_fabric;
0216     pmix_pnet_base_module_deregister_fabric_fn_t deregister_fabric;
0217 } pmix_pnet_API_module_t;
0218
0219 /* declare the global APIs */
0220 PMIX_EXPORT extern pmix_pnet_API_module_t pmix_pnet;
0221
0222 /*
0223  * the standard component data structure
0224  */
0225 typedef pmix_mca_base_component_t pmix_pnet_base_component_t;
0226
0227 /*
0228  * Macro for use in components that are of type pnet
0229  */
0230 #define PMIX_PNET_BASE_VERSION_1_0_0 PMIX_MCA_BASE_VERSION_1_0_0("pnet", 1, 0, 0)
0231
0232 END_C_DECLS
0233
0234 #endif