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   //! 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   //! Local path to the file to be executed by the job.
  62   /*! The type of the file depends on #job_type.
  63       If #job_type is "command", the #job_file must be a single filename
  64       specifying a self-consistent script to be executed without any argument,
  65       on the remote host.
  66   */
  67   string job_file;
  68
  69   //! Local path to a script to be sourced in the environment of the job.
  70   /*! It may contain modifications of environment variables.
  71   */
  72   string env_file;
  73
  74   //! List of local data files to be copied to #work_directory.
  75   /*! #job_file and #env_file are automaticaly copied, without adding them
  76       to this list. If basenames are specified, then the files are supposed
  77       to be located in #local_directory.
  78   */
  79   FilesList in_files;
  80
  81   //! List of results to get back at the end of the job.
  82   /*! These results can be names of files or directories, produced by the job
  83       in #work_directory. Directories will be copied recursively.
  84       It is also possible to use an absolute path instead of the simple name,
  85       (string beginning with '/') and this absolute path will be used instead
  86       of #result_directory when SalomeLauncher::getJobResults is called.
  87       \see SalomeLauncher::getJobResults
  88   */
  89   FilesList out_files;
  90
  91   //! Remote directory where the job will be executed.
  92   /*! It must be used to specify the remote directory where to put all
  93       the stuff to run the job. Note that the job will be executed from within
  94       this directory. A change directory toward this working directory is done
  95       by the batch system before running the job.
  96   */
  97   string work_directory;
  98
  99   //! Prefix to be applied to #in_files.
 100   /*! It can be used to specify where to find the local input files.
 101       It's optionnal if you specify the absolute path name of input files.
 102   */
 103   string local_directory;
 104
 105   //! Local directory where to get result files.
 106   /*! It must be used to specify where to download the output files on the
 107       local file system.
 108       \see SalomeLauncher::getJobResults
 109   */
 110   string result_directory;
 111
 112   //! Maximum time for the batch execution (expected format : "hh:mm").
 113   /*! Could be empty, in this case, default value of the selected resource
 114       will be used.
 115   */
 116   string maximum_duration;
 117
 118   //! Specifies the rules to choose the ressource where to execute the job.
 119   /*! The additionnal two following parameters MUST be specified explicitly,
 120       because they are not provided by the resource definition:
 121       - mem_mb -> Memory expressed in megabytes.
 122       - nb_proc -> Number of Processors.
 123   */
 124   ResourceParameters resource_required;
 125
 126   //!  Name of the batch queue chosen - optional
 127   string queue;
 128
 129   //! Specifies if the job must run in exclusive mode (without sharing nodes with other jobs)
 130   boolean exclusive;
 131
 132   //! Specifies the memory limit per cpu (exclusive with resource_required.mem_mb)
 133   unsigned long mem_per_cpu;
 134
 135   //! Workload Characterization Key - mandatory on some clusters
 136   string wckey;
 137
 138   //! String that is added to the job submission file - optional
 139   string extra_params;
 140
 141   //! Specific parameters for each type of job - optional
 142   /*! This is a list of parameters (key - value pairs of strings) useful in
 143       some specific situations.
 144       Known parameters:
 145       - EnableDumpYACS : value of the "dump" option of the "driver" command
 146         when the job type is "yacs_file". It gives the number of seconds
 147         between two updates of the state dump file. There will be no dump file
 148         if this parameter is missing or if its value is less than 1.
 149   */
 150   Engines::ParameterList specific_parameters;
 151
 152   //! %Parameter for COORM
 153   string launcher_file;
 154   //! %Parameter for COORM
 155   string launcher_args;
 156 };
 157
 158 struct JobDescription
 159 {
 160   long job_id;
 161   Engines::JobParameters job_parameters;
 162 };
 163 typedef sequence<Engines::JobDescription> JobsList;
 164
 165 interface SalomeLauncherObserver
 166 {
 167   void notify(in string event_name, in string event_data);
 168 };
 169
 170 //! Interface of the %salome launcher.
 171 /*! This interface is used for interaction with the unique instance
 172     of SalomeLauncher.
 173     The utilisation of this interface is explained in the YACS documentation,
 174     article "Starting a SALOME application in a batch manager".
 175     Other examples of use can be found in the modules JOBMANAGER, PARAMETRIC
 176     and SMESH (PADDER tool).
 177 */
 178 interface SalomeLauncher
 179 {
 180   // Main methods
 181   //! Create a job and set its parameters, without launching it.
 182   /*! Its state becomes "CREATED".
 183       \return job id
 184   */
 185   long   createJob    (in Engines::JobParameters job_parameters) raises (SALOME::SALOME_Exception);
 186
 187   //! Launch an already created job (job's state should be "CREATED").
 188   /*! Launching the job consists of:
 189       - create the working directory on the remote file system
 190       - copy the input files into the working directory
 191       - source the environment file if defined
 192       - run the job
 193   */
 194   void   launchJob    (in long job_id)                           raises (SALOME::SALOME_Exception);
 195
 196   //! Get the execution state of the job.
 197   /*! \return "CREATED", "IN_PROCESS", "QUEUED", "RUNNING", "PAUSED",
 198              "FINISHED" or "FAILED"
 199       \see LIBBATCH/src/core/Constants.hxx
 200   */
 201   string getJobState  (in long job_id)                           raises (SALOME::SALOME_Exception);
 202
 203   //! Get names or ids of hosts assigned to the job
 204   string getAssignedHostnames  (in long job_id)                  raises (SALOME::SALOME_Exception);
 205
 206   //! Copy the result files from the work directory of the job
 207   //! to a local directory.
 208   /*! The list of result files is given by the JobParameters::out_files parameter.
 209      If a result "file" is a directory, the copy is recursive.
 210      The "logs" directory contains the standard and the error outputs of the job.
 211      \param job_id    Job id returned by createJob().
 212      \param directory Local directory where to copy the results.
 213                       If this value is an empty string (""), files will be
 214                       copied to the directory given by
 215                       JobParameters::result_directory.
 216      \see JobParameters
 217      \see createJob
 218   */
 219   void   getJobResults(in long job_id, in string directory)      raises (SALOME::SALOME_Exception);
 220
 221   //! Try to copy the files named "dumpState*.xml" from the working directory.
 222   /*! The file "dumpState_name.xml" can be produced by the execution of a YACS
 223       schema and it contains the execution state of the schema.
 224       You can activate the creation of this file by adding the parameter
 225       "EnableDumpYACS" in JobParameters::specific_parameters when the job
 226       is created.
 227      \param job_id    Job id returned by createJob().
 228      \param directory Local directory where to copy the file.
 229                       If this value is an empty string (""), the file will be
 230                       copied to the directory given by
 231                       JobParameters::result_directory.
 232      \return 1 if the copy succeeds.
 233      \see JobParameters::specific_parameters
 234   */
 235   boolean getJobDumpState(in long job_id, in string directory)   raises (SALOME::SALOME_Exception);
 236
 237   //! Kill the job and set its state to "FAILED"
 238   void   stopJob      (in long job_id)                           raises (SALOME::SALOME_Exception);
 239   //! Kill the job and remove it from the jobs list
 240   void   removeJob    (in long job_id)                           raises (SALOME::SALOME_Exception);
 241
 242   // Useful methods
 243   long    createJobWithFile(in string xmlJobFile, in string clusterName) raises (SALOME::SALOME_Exception);
 244   boolean testBatch        (in ResourceParameters params)                raises (SALOME::SALOME_Exception);
 245
 246   // SALOME kernel service methods
 247   //! Shutdow SalomeLauncher server.
 248   void Shutdown();
 249   //! Get the PID of the current process
 250   long getPID();
 251
 252   // Observer and introspection methods
 253   //! Add an observer to be notified of the jobs list modifications
 254   void addObserver(in Engines::SalomeLauncherObserver observer);
 255   void removeObserver(in Engines::SalomeLauncherObserver observer);
 256   Engines::JobsList getJobsList();
 257   Engines::JobParameters getJobParameters(in long job_id) raises (SALOME::SALOME_Exception);
 258
 259   // Save and load methods
 260   //! Add to the current jobs list the jobs previously saved in an xml file.
 261   void loadJobs(in string jobs_file) raises (SALOME::SALOME_Exception);
 262   //! Save the current list of jobs in an xml file.
 263   void saveJobs(in string jobs_file) raises (SALOME::SALOME_Exception);
 264
 265 };
 266
 267 };
 268
 269 #endif