OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

session_dir.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
3 * University Research and Technology
4 * Corporation. All rights reserved.
5 * Copyright (c) 2004-2006 The University of Tennessee and The University
6 * of Tennessee Research Foundation. All rights
7 * reserved.
8 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9 * University of Stuttgart. All rights reserved.
10 * Copyright (c) 2004-2005 The Regents of the University of California.
11 * All rights reserved.
12 * $COPYRIGHT$
13 *
14 * Additional copyrights may follow
15 *
16 * $HEADER$
17 */
18 /** @file:
19 *
20 * Find and/or create Open MPI session directory.
21 *
22 * The orte_session_dir() function searches for a temporary directory
23 * that is used by the Open MPI system for storing system-critical
24 * information. For a given system and user, the function attempts to
25 * find (or create, if not found and create is requested) a directory
26 * that will be used to independently house information for multiple
27 * universes, as the user creates them. Thus, the function pursues a
28 * directory tree of the form:
29 *
30 * \par \em [prefix-dir] An absolute path that identifies a temporary
31 * directory that is read-write-execute accessible to everyone. The
32 * function first checks to see if the user has specified the [prefix]
33 * directory on the command line. If so, then the function will use
34 * that [prefix] if the access permissions are correct, or will return
35 * an error condition if not - the function will not search for
36 * alternative locations if the user provides the [prefix] name.
37 *
38 * \par If the [prefix] is not provided by the user, the function
39 * searches for a suitable directory in a specific order, taking the
40 * first option that meets the access permission requirement, using:
41 * (a) the "OMPI_PREFIX_ENV" environment variable; (b) the "TMPDIR"
42 * environment variable; and (c) the "TMP" environment variabley. If
43 * none of those environmental variables have been defined and/or the
44 * function was unable to create a suitable directory within any of
45 * them, then the function tries to use a default location of "/tmp",
46 * where the "/" represents the top-level directory of the local
47 * system. If none of these options are successful, the function
48 * returns an error code.
49 *
50 * \par \em [openmpi-sessions]-[user-id]@[host]:[batchid] This serves
51 * as a concentrator for all Open MPI session directories for this
52 * user on the local system. If it doesn't already exist, this
53 * directory is created with read-write-execute permissions
54 * exclusively restricted to the user. If it does exist, the access
55 * permissions are checked to ensure they are correct - if not, the
56 * program attempts to correct them. If they can't' be changed to the
57 * correct values, an error condition is returned. The [host] and
58 * [batchid] fields are included to provide uniqueness on shared file
59 * systems and batch schedulers, respectively.
60 *
61 * \par Note: The [prefix]/openmpi-sessions-[user-id]@[host]:[batchid]
62 * directory is left on the system upon termination of an application
63 * and/or an Open MPI universe for future use by the user. Thus, when
64 * checking a potential location for the directory, the
65 * orte_session_tree_init() function first checks to see if an
66 * appropriate directory already exists, and uses it if it does.
67 *
68 * \par \em [universe-name] A directory is created for the specified
69 * universe name. This is the directory that will be used to house all
70 * information relating to the specific universe. If the directory
71 * already exists (indicating that the user is joining an existing
72 * universe), then the function ensures that the user has exclusive
73 * read-write-execute permissions on the directory.
74 *
75 * \par \em [job] A directory is created for the specified job
76 * name. This will house all information relating to that specific
77 * job, including directories for each process within that job on this
78 * host.
79 *
80 * \par \em [process] A directory for the specific process, will house
81 * all information for that process.
82 *
83 * \par If \c create is \c true, the directory will be created and the
84 * proc_info structure will be updated. If proc_info is false,
85 */
86
87 #ifndef ORTE_SESSION_DIR_H_HAS_BEEN_INCLUDED
88 #define ORTE_SESSION_DIR_H_HAS_BEEN_INCLUDED
89
90 #include "orte_config.h"
91 #include "orte/types.h"
92
93 BEGIN_C_DECLS
94
95 /** @param create A boolean variable that indicates whether or not to
96 * create the specified directory. If set to "false",
97 * the function only checks to see if an existing
98 * directory can be found. This is typically used to
99 * locate an already existing universe for reconnection
100 * purposes. If set to "true", then the function
101 * creates the directory, if possible.
102 * @param prefix A string variable indicating where the user
103 * stipulated the directory should be found or
104 * placed. A value of "NULL" indicates that the user
105 * specified no location - hence, the function explores
106 * a range of "standard" locations.
107 * @param hostid Name of the host on which the session directory is
108 * being built. Used to build the name of the
109 * "openmpi-sessions-[user]@[host]:[batch]" branch of
110 * the directory tree. NULL indicates that the nodename
111 * found in orte_process_info is to be used.
112 * @param batchid Batch job name, used in batch scheduling
113 * systems. NULL indicates that the default of "0" is
114 * to be used.
115 * @param proc Pointer to a process name for which the session
116 * dir name is desired
117 *
118 * @retval ORTE_SUCCESS The directory was found and/or created with
119 * the proper permissions.
120 * @retval OMPI_ERROR The directory cannot be found (if create is
121 * "false") or created (if create is "true").
122 */
123 ORTE_DECLSPEC int orte_session_dir(bool create, char *prefix, char *hostid,
124 char *batchid, orte_process_name_t *proc);
125
126 /*
127 * Construct the session directory name from the input parameters.
128 * This function does no checking that the directory exists, or can be used
129 */
130 ORTE_DECLSPEC int orte_session_dir_get_name(char **fulldirpath,
131 char **prfx,
132 char **frontend,
133 char *hostid,
134 char *batchid,
135 orte_process_name_t *proc);
136
137 /** The orte_session_dir_finalize() function performs a cleanup of the
138 * session directory tree. It first removes the session directory for
139 * the calling process. It then checks to see if the job-level session
140 * directory is now empty - if so, it removes that level as
141 * well. Finally, it checks to see if the universe-level session
142 * directory is now empty - if so, it also removes that level. This
143 * three-part "last-one-out" procedure ensures that the directory tree
144 * is properly removed if all processes and applications within a
145 * universe have completed.
146 *
147 * @param None
148 * @retval ORTE_SUCCESS If the directory tree is properly cleaned up.
149 * @retval OMPI_ERROR If something prevents the tree from being
150 * properly cleaned up.
151 */
152 ORTE_DECLSPEC int orte_session_dir_finalize(orte_process_name_t *proc);
153
154 /** The orte_session_dir_cleanup() function performs a cleanup of the
155 * session directory tree when a job is aborted. It cleans up all
156 * process directories for a given job and then backs up the tree.
157 *
158 * @param jobid
159 * @retval OMPI_SUCCESS If the directory tree is properly cleaned up.
160 * @retval OMPI_ERROR If something prevents the tree from being
161 * properly cleaned up.
162 */
163 ORTE_DECLSPEC int orte_session_dir_cleanup(orte_jobid_t jobid);
164
165 END_C_DECLS
166
167 #endif /* ORTE_SESSION_DIR_H_HAS_BEEN_INCLUDED */
orte_jobid_t
uint32_t orte_jobid_t
Set the allowed range for ids in each space.
Definition: types.h:76
orte_process_name_t
Definition: types.h:146
types.h
orte_session_dir_finalize
ORTE_DECLSPEC int orte_session_dir_finalize(orte_process_name_t *proc)
The orte_session_dir_finalize() function performs a cleanup of the session directory tree...
Definition: session_dir.c:589
orte_session_dir
BEGIN_C_DECLS ORTE_DECLSPEC int orte_session_dir(bool create, char *prefix, char *hostid, char *batchid, orte_process_name_t *proc)
Definition: session_dir.c:370
orte_session_dir_cleanup
ORTE_DECLSPEC int orte_session_dir_cleanup(orte_jobid_t jobid)
The orte_session_dir_cleanup() function performs a cleanup of the session directory tree when a job i...
Definition: session_dir.c:519