mca/pmdl/pmdl.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-2023 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_PMDL_H
0028 #define PMIX_PMDL_H
0029
0030 #include "src/include/pmix_config.h"
0031
0032 #include "src/class/pmix_list.h"
0033 #include "src/mca/base/pmix_mca_base_framework.h"
0034 #include "src/mca/base/pmix_mca_base_var.h"
0035 #include "src/mca/mca.h"
0036 #include "src/server/pmix_server_ops.h"
0037
0038 BEGIN_C_DECLS
0039
0040 /******    MODULE DEFINITION    ******/
0041
0042 /**
0043  * Initialize the module. Returns an error if the module cannot
0044  * run, success if it can and wants to be used.
0045  */
0046 typedef pmix_status_t (*pmix_pmdl_base_module_init_fn_t)(void);
0047
0048 /**
0049  * Finalize the module. Tear down any allocated storage, disconnect
0050  * from any system support (e.g., LDAP server)
0051  */
0052 typedef void (*pmix_pmdl_base_module_fini_fn_t)(void);
0053
0054 /* Harvest envars for this programming model so they can be forwarded
0055  * to backend processes */
0056 typedef pmix_status_t (*pmix_pmdl_base_module_harvest_envars_fn_t)(pmix_namespace_t *nptr,
0057                                                                    const pmix_info_t info[],
0058                                                                    size_t ninfo, pmix_list_t *ilist,
0059                                                                    char ***priors);
0060
0061 /* Check a list of pmix_mca_base_var_file_value_t items that were
0062  * read from a file to see if any belong to this programming
0063  * model - if they do, then cache them for passing to any nspaces
0064  * during harvest_envars */
0065 typedef void (*pmix_pmdl_base_module_parse_file_envars_fn_t)(pmix_list_t *ilist);
0066
0067 /**
0068  * Setup any programming model specific support for the given nspace
0069  */
0070 typedef pmix_status_t (*pmix_pmdl_base_module_setup_ns_fn_t)(pmix_namespace_t *nptr,
0071                                                              pmix_info_t *info);
0072 typedef pmix_status_t (*pmix_pmdl_base_module_setup_ns_kv_fn_t)(pmix_namespace_t *nptr,
0073                                                                 pmix_kval_t *kv);
0074
0075 /* Allow programming models to add key-value pairs to the job-info - they
0076  * can directly cache them in the GDS */
0077 typedef pmix_status_t (*pmix_pmdl_base_module_reg_nspace_fn_t)(pmix_namespace_t *nptr);
0078
0079 /**
0080  * Setup any programming model specific support for the given client */
0081 typedef pmix_status_t (*pmix_pmdl_base_module_setup_client_fn_t)(pmix_namespace_t *nptr,
0082                                                                  pmix_rank_t rank,
0083                                                                  uint32_t apppnum);
0084
0085 /**
0086  * Give the plugins an opportunity to add any envars to the
0087  * environment of a local application process prior to fork/exec
0088  */
0089 typedef pmix_status_t (*pmix_pmdl_base_module_setup_fork_fn_t)(const pmix_proc_t *peer, char ***env,
0090                                                                char ***priors);
0091
0092 /**
0093  * Provide an opportunity for the fabric components to cleanup any
0094  * resources they may have created to track the nspace
0095  */
0096 typedef void (*pmix_pmdl_base_module_dregister_nspace_fn_t)(pmix_namespace_t *nptr);
0097
0098 /**
0099  * Base structure for a PMDL module. Each component should malloc a
0100  * copy of the module structure for each fabric plane they support.
0101  */
0102 typedef struct {
0103     char *name;
0104     pmix_pmdl_base_module_init_fn_t                 init;
0105     pmix_pmdl_base_module_fini_fn_t                 finalize;
0106     pmix_pmdl_base_module_harvest_envars_fn_t       harvest_envars;
0107     pmix_pmdl_base_module_parse_file_envars_fn_t    parse_file_envars;
0108     pmix_pmdl_base_module_setup_ns_fn_t             setup_nspace;
0109     pmix_pmdl_base_module_setup_ns_kv_fn_t          setup_nspace_kv;
0110     pmix_pmdl_base_module_reg_nspace_fn_t           register_nspace;
0111     pmix_pmdl_base_module_setup_client_fn_t         setup_client;
0112     pmix_pmdl_base_module_setup_fork_fn_t           setup_fork;
0113     pmix_pmdl_base_module_dregister_nspace_fn_t     deregister_nspace;
0114 } pmix_pmdl_module_t;
0115
0116 /* define a public API */
0117
0118 typedef pmix_status_t (*pmix_pmdl_base_API_harvest_envars_fn_t)(char *nspace,
0119                                                                 const pmix_info_t info[],
0120                                                                 size_t ninfo, pmix_list_t *ilist);
0121 typedef pmix_status_t (*pmix_pmdl_base_API_setup_fork_fn_t)(const pmix_proc_t *peer, char ***env);
0122 typedef void (*pmix_pmdl_base_API_dregister_nspace_fn_t)(const char *nptr);
0123 typedef struct {
0124     char *name;
0125     pmix_pmdl_base_module_init_fn_t                 init;
0126     pmix_pmdl_base_module_fini_fn_t                 finalize;
0127     pmix_pmdl_base_API_harvest_envars_fn_t          harvest_envars;
0128     pmix_pmdl_base_module_parse_file_envars_fn_t    parse_file_envars;
0129     pmix_pmdl_base_module_setup_ns_fn_t             setup_nspace;
0130     pmix_pmdl_base_module_setup_ns_kv_fn_t          setup_nspace_kv;
0131     pmix_pmdl_base_module_reg_nspace_fn_t           register_nspace;
0132     pmix_pmdl_base_module_setup_client_fn_t         setup_client;
0133     pmix_pmdl_base_API_setup_fork_fn_t              setup_fork;
0134     pmix_pmdl_base_API_dregister_nspace_fn_t        deregister_nspace;
0135 } pmix_pmdl_API_module_t;
0136
0137 /* declare the global APIs */
0138 PMIX_EXPORT extern pmix_pmdl_API_module_t pmix_pmdl;
0139
0140 /*
0141  * the standard component data structure
0142  */
0143 typedef pmix_mca_base_component_t pmix_pmdl_base_component_t;
0144
0145 /*
0146  * Macro for use in components that are of type pmdl
0147  */
0148 #define PMIX_PMDL_BASE_VERSION_1_0_0 PMIX_MCA_BASE_VERSION_1_0_0("pmdl", 1, 0, 0)
0149
0150 END_C_DECLS
0151
0152 #endif