root/orte/util/session_dir.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


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

/* [<][>][^][v][top][bottom][index][help] */