1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2009 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2005 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2012-2015 Los Alamos National Security, LLC. All rights
14 * reserved
15 * $COPYRIGHT$
16 *
17 * Additional copyrights may follow
18 *
19 * $HEADER$
20 */
21 /**
22 * @file
23 *
24 * Remote File Management (FileM) Interface
25 *
26 */
27
28 #ifndef MCA_FILEM_H
29 #define MCA_FILEM_H
30
31 #include "orte_config.h"
32 #include "orte/constants.h"
33 #include "orte/types.h"
34
35 #include "orte/mca/mca.h"
36 #include "opal/mca/base/base.h"
37
38 #include "opal/class/opal_object.h"
39
40 #include "orte/runtime/orte_globals.h"
41 BEGIN_C_DECLS
42
43 /**
44 * A set of flags that determine the type of the file
45 * in question
46 */
47 #define ORTE_FILEM_TYPE_FILE 0
48 #define ORTE_FILEM_TYPE_DIR 1
49 #define ORTE_FILEM_TYPE_UNKNOWN 2
50 #define ORTE_FILEM_TYPE_TAR 3
51 #define ORTE_FILEM_TYPE_BZIP 4
52 #define ORTE_FILEM_TYPE_GZIP 5
53 #define ORTE_FILEM_TYPE_EXE 6
54
55 /**
56 * Type of movement
57 */
58 #define ORTE_FILEM_MOVE_TYPE_PUT 0
59 #define ORTE_FILEM_MOVE_TYPE_GET 1
60 #define ORTE_FILEM_MOVE_TYPE_RM 2
61 #define ORTE_FILEM_MOVE_TYPE_UNKNOWN 3
62
63 /**
64 * Hints that describe the local or remote file target for
65 * optimization purposes.
66 */
67 #define ORTE_FILEM_HINT_NONE 0
68 #define ORTE_FILEM_HINT_SHARED 1
69
70 /**
71 * Define a Process Set
72 *
73 * Source: A single source of the operation.
74 * Sink: Desitination of the operation.
75 */
76 struct orte_filem_base_process_set_1_0_0_t {
77 /** This is an object, so must have a super */
78 opal_list_item_t super;
79
80 /** Source Process */
81 orte_process_name_t source;
82
83 /** Sink Process */
84 orte_process_name_t sink;
85 };
86 typedef struct orte_filem_base_process_set_1_0_0_t orte_filem_base_process_set_1_0_0_t;
87 typedef struct orte_filem_base_process_set_1_0_0_t orte_filem_base_process_set_t;
88
89 ORTE_DECLSPEC OBJ_CLASS_DECLARATION(orte_filem_base_process_set_t);
90
91 /**
92 * Define a File Pair
93 *
94 * Local: Local file reference
95 * Remove: Remote file reference
96 *
97 * Note: If multiple process sinks are used it is assumed that the
98 * file reference is the same for each of the sinks. If this is not
99 * true then more than one filem request needs to be created.
100 */
101 struct orte_filem_base_file_set_1_0_0_t {
102 /** This is an object, so must have a super */
103 opal_list_item_t super;
104
105 /* the app_index this pertains to, if applicable */
106 orte_app_idx_t app_idx;
107
108 /* Local file reference */
109 char * local_target;
110
111 /* Local file reference hints */
112 int local_hint;
113
114 /* Remove file reference */
115 char * remote_target;
116
117 /* Remote file reference hints */
118 int remote_hint;
119
120 /* Type of file to move */
121 int target_flag;
122 };
123 typedef struct orte_filem_base_file_set_1_0_0_t orte_filem_base_file_set_1_0_0_t;
124 typedef struct orte_filem_base_file_set_1_0_0_t orte_filem_base_file_set_t;
125
126 ORTE_DECLSPEC OBJ_CLASS_DECLARATION(orte_filem_base_file_set_t);
127
128 /**
129 * Definition of a file movement request
130 * This will allow:
131 * - The movement of one or more files
132 * - to/from one or more processes
133 * in a single call of the API function. Allowing the implementation
134 * to optimize the sending/receiving of data.
135 * Used for the following:
136 *
137 */
138 struct orte_filem_base_request_1_0_0_t {
139 /** This is an object, so must have a super */
140 opal_list_item_t super;
141
142 /*
143 * A list of process sets - use WILDCARD to
144 * indicate all procs of a given vpid/jobid,
145 * INVALID to indicate not-applicable. For
146 * example, if you need to move a file at time
147 * of job start to each node that has a proc
148 * on it, then the process set would have a
149 * source proc with vpid=INVALID and a sink proc
150 * with vpid=WILDCARD, and a remote hint of "shared"
151 * in the file sets so we don't copy them over
152 * multiple times
153 */
154 opal_list_t process_sets;
155
156 /*
157 * A list of file pairings
158 */
159 opal_list_t file_sets;
160
161 /*
162 * Internal use:
163 * Number of movements
164 */
165 int num_mv;
166
167 /*
168 * Internal use:
169 * Boolean to indianate if transfer is complete
170 */
171 bool *is_done;
172
173 /*
174 * Internal use:
175 * Boolean to indianate if transfer is active
176 */
177 bool *is_active;
178
179 /*
180 * Internal use:
181 * Exit status of the copy command
182 */
183 int32_t *exit_status;
184
185 /*
186 * Internal use:
187 * Movement type
188 */
189 int movement_type;
190 };
191 typedef struct orte_filem_base_request_1_0_0_t orte_filem_base_request_1_0_0_t;
192 typedef struct orte_filem_base_request_1_0_0_t orte_filem_base_request_t;
193
194 ORTE_DECLSPEC OBJ_CLASS_DECLARATION(orte_filem_base_request_t);
195
196 /**
197 * Module initialization function.
198 * Returns ORTE_SUCCESS
199 */
200 typedef int (*orte_filem_base_module_init_fn_t)
201 (void);
202
203 /**
204 * Module finalization function.
205 * Returns ORTE_SUCCESS
206 */
207 typedef int (*orte_filem_base_module_finalize_fn_t)
208 (void);
209
210 /**
211 * Put a file or directory on the remote machine
212 *
213 * Note: By using a relative path for the remote file/directory, the filem
214 * component will negotiate the correct absolute path for that file/directory
215 * for the remote machine.
216 *
217 * @param request FileM request describing the files/directories to send,
218 * the remote files/directories to use, and the processes to see the change.
219 *
220 * @return ORTE_SUCCESS on successful file transer
221 * @return ORTE_ERROR on failed file transfer
222 */
223 typedef int (*orte_filem_base_put_fn_t)
224 (orte_filem_base_request_t *request);
225
226 /**
227 * Put a file or directory on the remote machine (Async)
228 *
229 * Note: By using a relative path for the remote file/directory, the filem
230 * component will negotiate the correct absolute path for that file/directory
231 * for the remote machine.
232 *
233 * @param request FileM request describing the files/directories to send,
234 * the remote files/directories to use, and the processes to see the change.
235 *
236 * @return ORTE_SUCCESS on successful file transer
237 * @return ORTE_ERROR on failed file transfer
238 */
239 typedef int (*orte_filem_base_put_nb_fn_t)
240 (orte_filem_base_request_t *request);
241
242 /**
243 * Get a file from the remote machine
244 *
245 * Note: By using a relative path for the remote file/directory, the filem
246 * component will negotiate the correct absolute path for that file/directory
247 * for the remote machine.
248 *
249 * @param request FileM request describing the files/directories to receive,
250 * the remote files/directories to use, and the processes to see the change.
251 *
252 * @return ORTE_SUCCESS on successful file transer
253 * @return ORTE_ERROR on failed file transfer
254 */
255 typedef int (*orte_filem_base_get_fn_t)
256 (orte_filem_base_request_t *request);
257
258 /**
259 * Get a file from the remote machine (Async)
260 *
261 * Note: By using a relative path for the remote file/directory, the filem
262 * component will negotiate the correct absolute path for that file/directory
263 * for the remote machine.
264 *
265 * @param request FileM request describing the files/directories to receive,
266 * the remote files/directories to use, and the processes to see the change.
267 *
268 * @return ORTE_SUCCESS on successful file transer
269 * @return ORTE_ERROR on failed file transfer
270 */
271 typedef int (*orte_filem_base_get_nb_fn_t)
272 (orte_filem_base_request_t *request);
273
274 /**
275 * Remove a file from the remote machine
276 *
277 * Note: By using a relative path for the remote file/directory, the filem
278 * component will negotiate the correct absolute path for that file/directory
279 * for the remote machine.
280 *
281 * @param request FileM request describing the remote files/directories to remove,
282 * the processes to see the change.
283 *
284 * @return ORTE_SUCCESS on success
285 * @return ORTE_ERROR on fail
286 */
287 typedef int (*orte_filem_base_rm_fn_t)
288 (orte_filem_base_request_t *request);
289
290 /**
291 * Remove a file from the remote machine (Async)
292 *
293 * Note: By using a relative path for the remote file/directory, the filem
294 * component will negotiate the correct absolute path for that file/directory
295 * for the remote machine.
296 *
297 * @param request FileM request describing the remote files/directories to remove,
298 * the processes to see the change.
299 *
300 * @return ORTE_SUCCESS on success
301 * @return ORTE_ERROR on fail
302 */
303 typedef int (*orte_filem_base_rm_nb_fn_t)
304 (orte_filem_base_request_t *request);
305
306 /**
307 * Wait for a single file movement request to finish
308 *
309 * @param request FileM request describing the remote files/directories.
310 *
311 * The request must have been passed through one of the non-blocking functions
312 * before calling wait or wait_all otherwise ORTE_ERROR will be returned.
313 *
314 * @return ORTE_SUCCESS on success
315 * @return ORTE_ERROR on fail
316 */
317 typedef int (*orte_filem_base_wait_fn_t)
318 (orte_filem_base_request_t *request);
319
320 /**
321 * Wait for a multiple file movement requests to finish
322 *
323 * @param request_list opal_list_t of FileM requests describing the remote files/directories.
324 *
325 * The request must have been passed through one of the non-blocking functions
326 * before calling wait or wait_all otherwise ORTE_ERROR will be returned.
327 *
328 * @return ORTE_SUCCESS on success
329 * @return ORTE_ERROR on fail
330 */
331 typedef int (*orte_filem_base_wait_all_fn_t)
332 (opal_list_t *request_list);
333
334 typedef void (*orte_filem_completion_cbfunc_t)(int status, void *cbdata);
335
336 /* Pre-position files
337 */
338 typedef int (*orte_filem_base_preposition_files_fn_t)(orte_job_t *jdata,
339 orte_filem_completion_cbfunc_t cbfunc,
340 void *cbdata);
341
342 /* link local files */
343 typedef int (*orte_filem_base_link_local_files_fn_t)(orte_job_t *jdata,
344 orte_app_context_t *app);
345
346 /**
347 * Structure for FILEM components.
348 */
349 struct orte_filem_base_component_2_0_0_t {
350 /** MCA base component */
351 mca_base_component_t base_version;
352 /** MCA base data */
353 mca_base_component_data_t base_data;
354 };
355 typedef struct orte_filem_base_component_2_0_0_t orte_filem_base_component_2_0_0_t;
356 typedef struct orte_filem_base_component_2_0_0_t orte_filem_base_component_t;
357
358 /**
359 * Structure for FILEM modules
360 */
361 struct orte_filem_base_module_1_0_0_t {
362 /** Initialization Function */
363 orte_filem_base_module_init_fn_t filem_init;
364 /** Finalization Function */
365 orte_filem_base_module_finalize_fn_t filem_finalize;
366
367 /** Put a file on the remote machine */
368 orte_filem_base_put_fn_t put;
369 orte_filem_base_put_nb_fn_t put_nb;
370 /** Get a file from the remote machine */
371 orte_filem_base_get_fn_t get;
372 orte_filem_base_get_nb_fn_t get_nb;
373
374 /** Remove a file on the remote machine */
375 orte_filem_base_rm_fn_t rm;
376 orte_filem_base_rm_nb_fn_t rm_nb;
377
378 /** Test functions for the non-blocking versions */
379 orte_filem_base_wait_fn_t wait;
380 orte_filem_base_wait_all_fn_t wait_all;
381
382 /* pre-position files to every node */
383 orte_filem_base_preposition_files_fn_t preposition_files;
384 /* create local links for all shared files */
385 orte_filem_base_link_local_files_fn_t link_local_files;
386
387 };
388 typedef struct orte_filem_base_module_1_0_0_t orte_filem_base_module_1_0_0_t;
389 typedef struct orte_filem_base_module_1_0_0_t orte_filem_base_module_t;
390
391 ORTE_DECLSPEC extern orte_filem_base_module_t orte_filem;
392
393 /**
394 * Macro for use in components that are of type FILEM
395 */
396 #define ORTE_FILEM_BASE_VERSION_2_0_0 \
397 ORTE_MCA_BASE_VERSION_2_1_0("filem", 2, 0, 0)
398
399 END_C_DECLS
400
401 #endif /* ORTE_FILEM_H */
402