idl/SALOME_Launcher.idl

   1 // Copyright (C) 2007-2014  CEA/DEN, EDF R&D, OPEN CASCADE
   2 //
   3 // Copyright (C) 2003-2007  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
   4 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
   5 //
   6 // This library is free software; you can redistribute it and/or
   7 // modify it under the terms of the GNU Lesser General Public
   8 // License as published by the Free Software Foundation; either
   9 // version 2.1 of the License, or (at your option) any later version.
  10 //
  11 // This library is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 // Lesser General Public License for more details.
  15 //
  16 // You should have received a copy of the GNU Lesser General Public
  17 // License along with this library; if not, write to the Free Software
  18 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19 //
  20 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21 //
  22
  23 #ifndef _SALOME_LAUNCHER_IDL_
  24 #define _SALOME_LAUNCHER_IDL_
  25
  26 #include "SALOME_Exception.idl"
  27 #include "SALOME_ResourcesManager.idl"
  28
  29 /*! \file SALOME_Launcher.idl \brief interfaces for %SALOME Launcher service
  30 */
  31
  32 module Engines
  33 {
  34
  35 //! files list
  36 typedef sequence<string> FilesList;
  37
  38 //! A generic parameter
  39 struct Parameter
  40 {
  41   string name;
  42   string value;
  43 };
  44 //! Generic parameter list
  45 typedef sequence<Engines::Parameter> ParameterList;
  46
  47 struct JobParameters
  48 {
  49   //! Name of the job.
  50   string job_name;
  51
  52   /*! \brief Type of the job.
  53       There are three supported types:
  54         - "command" : execute #job_file script without SALOME environment
  55         - "python_salome" : execute #job_file python script by SALOME
  56         - "yacs_file" : execute #job_file by YACS module as a xml YACS schema
  57   */
  58   string job_type;
  59
  60   // Common values
  61   /*! \brief Local path to the file to be executed by the job.
  62       The type of the file depends on #job_type.
  63   */
  64   string job_file;
  65
  66   /*! \brief Local path to a script to be sourced in the environment of the job.
  67       It may contain modifications of environment variables.
  68   */
  69   string env_file;
  70
  71   /*! List of local data files to be copied to #work_directory.
  72       #job_file and #env_file are automaticaly copied, without adding them
  73       to this list. The actual path of the files could be prefixed by
  74       #local_directory.
  75   */
  76   FilesList in_files;
  77
  78   /*! List of results to get back at the end of the job.
  79       These results can be names of files or directories, produced by the job
  80       in #work_directory. Directories will be copied recursively.
  81       It is also possible to use an absolute path instead of the simple name,
  82       (string beginning with '/') and this absolute path will be used instead
  83       of #result_directory when SalomeLauncher::getJobResults is called.
  84       \see SalomeLauncher::getJobResults
  85   */
  86   FilesList out_files;
  87
  88   //! Remote directory where the job will be executed.
  89   string work_directory;
  90
  91   //! Prefix to be applied to #in_files.
  92   string local_directory;
  93
  94   /*! Local directory where to get result files.
  95       \see SalomeLauncher::getJobResults
  96   */
  97   string result_directory;
  98
  99   /*! Time for the batch (has to be like this : hh:mm) - Could be empty, in
 100        this case, default value of the selected resource will be used.
 101   */
 102   string maximum_duration;
 103
 104   /*! Memory is expressed in megabytes -> mem_mb.
 105       Number of Processors -> nb_proc.
 106   */
 107   ResourceParameters resource_required;
 108
 109   /*!
 110     Name of the batch queue chosen - optional
 111   */
 112   string queue;
 113
 114   //! Specifies if the job must run in exclusive mode (without sharing nodes with other jobs)
 115   boolean exclusive;
 116
 117   //! Specifies the memory limit per cpu (exclusive with resource_required.mem_mb)
 118   unsigned long mem_per_cpu;
 119
 120   //! Workload Characterization Key - mandatory on some clusters
 121   string wckey;
 122
 123   //! String that is added to the job submission file - optional
 124   string extra_params;
 125
 126   /*!
 127     Specific parameters for each type of job - optional
 128   */
 129   Engines::ParameterList specific_parameters;
 130
 131   //! %Parameter for COORM
 132   string launcher_file;
 133   //! %Parameter for COORM
 134   string launcher_args;
 135 };
 136
 137 struct JobDescription
 138 {
 139   long job_id;
 140   Engines::JobParameters job_parameters;
 141 };
 142 typedef sequence<Engines::JobDescription> JobsList;
 143
 144 interface SalomeLauncherObserver
 145 {
 146   void notify(in string event_name, in string event_data);
 147 };
 148
 149 /*! \brief Interface of the %salomelauncher
 150     This interface is used for interaction with the unique instance
 151     of SalomeLauncher
 152 */
 153 interface SalomeLauncher
 154 {
 155   // Main methods
 156   /*! Create a job and set its parameters, without launching it.
 157       Its state becomes "CREATED".
 158       \return job id
 159   */
 160   long   createJob    (in Engines::JobParameters job_parameters) raises (SALOME::SALOME_Exception);
 161
 162   /*! Launch an already created job (job's state should be "CREATED").
 163       Its state changes to "QUEUED".
 164   */
 165   void   launchJob    (in long job_id)                           raises (SALOME::SALOME_Exception);
 166
 167   /*!
 168      \return "CREATED", "IN_PROCESS", "QUEUED", "RUNNING", "PAUSED",
 169              "FINISHED" or "FAILED"
 170      \see LIBBATCH/src/core/Constants.hxx
 171   */
 172   string getJobState  (in long job_id)                           raises (SALOME::SALOME_Exception);
 173
 174   //! Get names or ids of hosts assigned to the job
 175   string getAssignedHostnames  (in long job_id)                  raises (SALOME::SALOME_Exception);
 176
 177   /*!
 178      Copy the result files from the work directory of the job
 179      to a local directory.
 180      The list of result files is given by the "out_files" parameter.
 181      If a result "file" is a directory, the copy is recursive.
 182      The "logs" directory contains the standard and the error outputs of the job.
 183      \param job_id    Job id returned by createJob().
 184      \param directory Local directory where to copy the results.
 185                       If this value is an empty string (""), files will be
 186                       copied to the directory given by
 187                       JobParameters::result_directory.
 188      \see JobParameters
 189      \see createJob
 190   */
 191   void   getJobResults(in long job_id, in string directory)      raises (SALOME::SALOME_Exception);
 192   boolean getJobDumpState(in long job_id, in string directory)   raises (SALOME::SALOME_Exception);
 193   void   stopJob      (in long job_id)                           raises (SALOME::SALOME_Exception);
 194   void   removeJob    (in long job_id)                           raises (SALOME::SALOME_Exception);
 195
 196   // Useful methods
 197   long    createJobWithFile(in string xmlJobFile, in string clusterName) raises (SALOME::SALOME_Exception);
 198   boolean testBatch        (in ResourceParameters params)                raises (SALOME::SALOME_Exception);
 199
 200   // SALOME kernel service methods
 201   void Shutdown();
 202   long getPID();
 203
 204   // Observer and introspection methods
 205   void addObserver(in Engines::SalomeLauncherObserver observer);
 206   void removeObserver(in Engines::SalomeLauncherObserver observer);
 207   Engines::JobsList getJobsList();
 208   Engines::JobParameters getJobParameters(in long job_id) raises (SALOME::SALOME_Exception);
 209
 210   // Save and load methods
 211   void loadJobs(in string jobs_file) raises (SALOME::SALOME_Exception);
 212   void saveJobs(in string jobs_file) raises (SALOME::SALOME_Exception);
 213
 214 };
 215
 216 };
 217
 218 #endif