1 // Copyright (C) 2007-2014 CEA/DEN, EDF R&D, OPEN CASCADE
3 // Copyright (C) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
4 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
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.
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.
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
20 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
23 #ifndef _SALOME_LAUNCHER_IDL_
24 #define _SALOME_LAUNCHER_IDL_
26 #include "SALOME_Exception.idl"
27 #include "SALOME_ResourcesManager.idl"
29 /*! \file SALOME_Launcher.idl \brief Interfaces for %SALOME Launcher service
36 typedef sequence<string> FilesList;
38 //! A generic parameter
44 //! Generic parameter list
45 typedef sequence<Engines::Parameter> ParameterList;
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
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,
69 //! Local path to a script to be sourced in the environment of the job.
70 /*! It may contain modifications of environment variables.
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.
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
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.
97 string work_directory;
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.
103 string local_directory;
105 //! Local directory where to get result files.
106 /*! It must be used to specify where to download the output files on the
108 \see SalomeLauncher::getJobResults
110 string result_directory;
112 //! Maximum time for the batch execution (expected format : "hh:mm").
113 /*! Could be empty, in this case, default value of the selected resource
116 string maximum_duration;
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.
124 ResourceParameters resource_required;
126 //! Name of the batch queue chosen - optional
129 //! Specifies if the job must run in exclusive mode (without sharing nodes with other jobs)
132 //! Specifies the memory limit per cpu (exclusive with resource_required.mem_mb)
133 unsigned long mem_per_cpu;
135 //! Workload Characterization Key - mandatory on some clusters
138 //! String that is added to the job submission file - optional
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.
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.
150 Engines::ParameterList specific_parameters;
152 //! %Parameter for COORM
153 string launcher_file;
154 //! %Parameter for COORM
155 string launcher_args;
158 struct JobDescription
161 Engines::JobParameters job_parameters;
163 typedef sequence<Engines::JobDescription> JobsList;
165 interface SalomeLauncherObserver
167 void notify(in string event_name, in string event_data);
170 //! Interface of the %salome launcher.
171 /*! This interface is used for interaction with the unique instance
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).
178 interface SalomeLauncher
181 //! Create a job and set its parameters, without launching it.
182 /*! Its state becomes "CREATED".
185 long createJob (in Engines::JobParameters job_parameters) raises (SALOME::SALOME_Exception);
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
194 void launchJob (in long job_id) raises (SALOME::SALOME_Exception);
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
201 string getJobState (in long job_id) raises (SALOME::SALOME_Exception);
203 //! Get names or ids of hosts assigned to the job
204 string getAssignedHostnames (in long job_id) raises (SALOME::SALOME_Exception);
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.
219 void getJobResults(in long job_id, in string directory) raises (SALOME::SALOME_Exception);
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
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
235 boolean getJobDumpState(in long job_id, in string directory) raises (SALOME::SALOME_Exception);
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);
243 long createJobWithFile(in string xmlJobFile, in string clusterName) raises (SALOME::SALOME_Exception);
244 boolean testBatch (in ResourceParameters params) raises (SALOME::SALOME_Exception);
246 // SALOME kernel service methods
247 //! Shutdow SalomeLauncher server.
249 //! Get the PID of the current process
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);
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);