1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2007-2008 Cisco Systems, Inc. All rights reserved.
4 *
5 * Copyright (c) 2015-2018 Research Organization for Information Science
6 * and Technology (RIST). All rights reserved.
7 * Copyright (c) 2018-2019 Intel, Inc. All rights reserved.
8 * $COPYRIGHT$
9 *
10 * Additional copyrights may follow
11 *
12 * $HEADER$
13 */
14
15 /**
16 * @file
17 *
18 * This interface is for use by PMIx servers to obtain network-related info
19 * such as security keys that need to be shared across applications, and to
20 * setup network support for applications prior to launch
21 *
22 * Available plugins may be defined at runtime via the typical MCA parameter
23 * syntax.
24 */
25
26 #ifndef PMIX_PNET_H
27 #define PMIX_PNET_H
28
29 #include <src/include/pmix_config.h>
30
31 #include "src/class/pmix_list.h"
32 #include "src/mca/mca.h"
33 #include "src/mca/base/pmix_mca_base_var.h"
34 #include "src/mca/base/pmix_mca_base_framework.h"
35 #include "src/include/pmix_globals.h"
36 #include "src/server/pmix_server_ops.h"
37
38 BEGIN_C_DECLS
39
40 /****** MODULE DEFINITION ******/
41
42 /**
43 * Initialize the module. Returns an error if the module cannot
44 * run, success if it can and wants to be used.
45 */
46 typedef pmix_status_t (*pmix_pnet_base_module_init_fn_t)(void);
47
48 /**
49 * Finalize the module. Tear down any allocated storage, disconnect
50 * from any system support (e.g., LDAP server)
51 */
52 typedef void (*pmix_pnet_base_module_fini_fn_t)(void);
53
54 /**
55 * Allocate network resources. This can be called either as a result
56 * of a call to PMIx_Allocate_resources, or by the scheduler to
57 * provide an opportunity for the network to define values that
58 * are to be passed to an application. This can include security
59 * tokens required for application processes to communicate with
60 * each other, environmental variables picked up at the login node
61 * for forwarding to compute nodes, or allocation of static endpts
62 */
63 typedef pmix_status_t (*pmix_pnet_base_module_allocate_fn_t)(pmix_namespace_t *nptr,
64 pmix_info_t info[], size_t ninfo,
65 pmix_list_t *ilist);
66
67 /**
68 * Give the local network library an opportunity to setup address information
69 * for the application by passing in the layout type and a regex describing
70 * the layout */
71 typedef pmix_status_t (*pmix_pnet_base_module_setup_local_net_fn_t)(pmix_namespace_t *nptr,
72 pmix_info_t info[],
73 size_t ninfo);
74
75 /**
76 * Give the local network library an opportunity to add any envars to the
77 * environment of a local application process prior to fork/exec
78 */
79 typedef pmix_status_t (*pmix_pnet_base_module_setup_fork_fn_t)(pmix_namespace_t *nptr,
80 const pmix_proc_t *proc,
81 char ***env);
82
83 /**
84 * Provide an opportunity for the local network library to cleanup when a
85 * local application process terminates
86 */
87 typedef void (*pmix_pnet_base_module_child_finalized_fn_t)(pmix_proc_t *peer);
88
89 /**
90 * Provide an opportunity for the local network library to cleanup after
91 * all local clients for a given application have terminated
92 */
93 typedef void (*pmix_pnet_base_module_local_app_finalized_fn_t)(pmix_namespace_t *nptr);
94
95 /**
96 * Provide an opportunity for the fabric components to cleanup any
97 * resource allocations (e.g., static ports) they may have assigned
98 */
99 typedef void (*pmix_pnet_base_module_dregister_nspace_fn_t)(pmix_namespace_t *nptr);
100
101
102 /**
103 * Request that the module report local inventory for its network type.
104 *
105 * If the operation can be performed immediately, then the module should just
106 * add the inventory (as pmix_kval_t's) to the provided object's list and
107 * return PMIX_SUCCESS.
108 *
109 * If the module needs to perform some non-atomic operation
110 * (e.g., query a fabric manager), then it should shift to its own internal
111 * thread, return PMIX_OPERATION_IN_PROGRESS, and execute the provided
112 * callback function when the operation is completed.
113 *
114 * If there is no inventory to report, then just return PMIX_SUCCESS.
115 *
116 * If the module should be providing inventory but encounters an error,
117 * then immediately return an error code if the error is immediately detected,
118 * or execute the callback function with an error code if it is detected later.
119 */
120 typedef pmix_status_t (*pmix_pnet_base_module_collect_inventory_fn_t)(pmix_info_t directives[], size_t ndirs,
121 pmix_inventory_cbfunc_t cbfunc,
122 void *cbdata);
123
124 /**
125 * Deliver inventory for archiving by corresponding modules
126 *
127 * Modules are to search the provided inventory to identify
128 * entries provided by their remote peers, and then store that
129 * information in a manner that can be queried/retrieved by
130 * the host RM and/or scheduler. If the operation can be
131 * performed immediately (e.g., storing the information in
132 * the local hash table), then the module should just perform
133 * that operation and return the appropriate status.
134 *
135 * If the module needs to perform some non-atomic operation
136 * (e.g., storing the information in a non-local DHT), then
137 * it should shift to its own internal thread, return
138 * PMIX_OPERATION_IN_PROGRESS, and execute the provided
139 * callback function when the operation is completed.
140 *
141 * If there is no relevant inventory to archive, then the module
142 * should just return PMIX_SUCCESS;
143 */
144 typedef pmix_status_t (*pmix_pnet_base_module_deliver_inventory_fn_t)(pmix_info_t info[], size_t ninfo,
145 pmix_info_t directives[], size_t ndirs,
146 pmix_op_cbfunc_t cbfunc, void *cbdata);
147
148
149 /**
150 * Base structure for a PNET module
151 */
152 typedef struct {
153 char *name;
154 /* init/finalize */
155 pmix_pnet_base_module_init_fn_t init;
156 pmix_pnet_base_module_fini_fn_t finalize;
157 pmix_pnet_base_module_allocate_fn_t allocate;
158 pmix_pnet_base_module_setup_local_net_fn_t setup_local_network;
159 pmix_pnet_base_module_setup_fork_fn_t setup_fork;
160 pmix_pnet_base_module_child_finalized_fn_t child_finalized;
161 pmix_pnet_base_module_local_app_finalized_fn_t local_app_finalized;
162 pmix_pnet_base_module_dregister_nspace_fn_t deregister_nspace;
163 pmix_pnet_base_module_collect_inventory_fn_t collect_inventory;
164 pmix_pnet_base_module_deliver_inventory_fn_t deliver_inventory;
165 } pmix_pnet_module_t;
166
167
168 /* define a few API versions of the functions - main difference is the
169 * string nspace parameter instead of a pointer to pmix_namespace_t. This
170 * is done as an optimization to avoid having every component look for
171 * that pointer */
172 typedef pmix_status_t (*pmix_pnet_base_API_allocate_fn_t)(char *nspace,
173 pmix_info_t info[], size_t ninfo,
174 pmix_list_t *ilist);
175 typedef pmix_status_t (*pmix_pnet_base_API_setup_local_net_fn_t)(char *nspace,
176 pmix_info_t info[],
177 size_t ninfo);
178 typedef pmix_status_t (*pmix_pnet_base_API_setup_fork_fn_t)(const pmix_proc_t *peer, char ***env);
179
180 typedef void (*pmix_pnet_base_API_deregister_nspace_fn_t)(char *nspace);
181 typedef void (*pmix_pnet_base_API_collect_inventory_fn_t)(pmix_info_t directives[], size_t ndirs,
182 pmix_inventory_cbfunc_t cbfunc,
183 void *cbdata);
184 typedef void (*pmix_pnet_base_API_deliver_inventory_fn_t)(pmix_info_t info[], size_t ninfo,
185 pmix_info_t directives[], size_t ndirs,
186 pmix_op_cbfunc_t cbfunc, void *cbdata);
187
188 /**
189 * Base structure for a PNET API
190 */
191 typedef struct {
192 char *name;
193 /* init/finalize */
194 pmix_pnet_base_module_init_fn_t init;
195 pmix_pnet_base_module_fini_fn_t finalize;
196 pmix_pnet_base_API_allocate_fn_t allocate;
197 pmix_pnet_base_API_setup_local_net_fn_t setup_local_network;
198 pmix_pnet_base_API_setup_fork_fn_t setup_fork;
199 pmix_pnet_base_module_child_finalized_fn_t child_finalized;
200 pmix_pnet_base_module_local_app_finalized_fn_t local_app_finalized;
201 pmix_pnet_base_API_deregister_nspace_fn_t deregister_nspace;
202 pmix_pnet_base_API_collect_inventory_fn_t collect_inventory;
203 pmix_pnet_base_API_deliver_inventory_fn_t deliver_inventory;
204 } pmix_pnet_API_module_t;
205
206
207 /* declare the global APIs */
208 PMIX_EXPORT extern pmix_pnet_API_module_t pmix_pnet;
209
210 /*
211 * the standard component data structure
212 */
213 struct pmix_pnet_base_component_t {
214 pmix_mca_base_component_t base;
215 pmix_mca_base_component_data_t data;
216 };
217 typedef struct pmix_pnet_base_component_t pmix_pnet_base_component_t;
218
219 /*
220 * Macro for use in components that are of type pnet
221 */
222 #define PMIX_PNET_BASE_VERSION_1_0_0 \
223 PMIX_MCA_BASE_VERSION_1_0_0("pnet", 1, 0, 0)
224
225 END_C_DECLS
226
227 #endif