1 // Copyright (C) 2007-2016 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.
96 If not specified (empty string), the launcher will use the working
97 directory of the chosen ressource and if this is also an empty string
98 the value used will be $HOME/Batch/workdir_"date" where $HOME is the
99 value of the environment variable on the remote ressource and "date" is
102 string work_directory;
104 //! Prefix to be applied to #in_files.
105 /*! It can be used to specify where to find the local input files.
106 It's optionnal if you specify the absolute path name of input files.
108 string local_directory;
110 //! Local directory where to get result files.
111 /*! It must be used to specify where to download the output files on the
113 If not specified (empty string), the value of $HOME environment variable
115 \see SalomeLauncher::getJobResults
117 string result_directory;
119 //! Maximum time for the batch execution (expected format : "hh:mm").
120 /*! Could be empty, in this case, default value of the selected resource
123 string maximum_duration;
125 //! Specifies the rules to choose the ressource where to execute the job.
126 /*! The additionnal two following parameters MUST be specified explicitly,
127 because they are not provided by the resource definition:
128 - mem_mb -> Memory expressed in megabytes.
129 - nb_proc -> Number of Processors.
131 ResourceParameters resource_required;
133 //! Name of the batch queue chosen - optional
136 //! Specifies if the job must run in exclusive mode (without sharing nodes with other jobs)
139 //! Specifies the memory limit per cpu (exclusive with resource_required.mem_mb)
140 unsigned long mem_per_cpu;
142 //! Workload Characterization Key - mandatory on some clusters
145 //! String that is added to the job submission file - optional
148 //! Specific parameters for each type of job - optional
149 /*! This is a list of parameters (key - value pairs of strings) useful in
150 some specific situations.
152 - EnableDumpYACS : value of the "dump" option of the "driver" command
153 when the job type is "yacs_file". It gives the number of seconds
154 between two updates of the state dump file. There will be no dump file
155 if this parameter is missing or if its value is less than 1.
156 - YACSDriverOptions : options of the driver command when the job type is
158 - LoalLevelerJobType : LL_JOBTYPE.
160 Engines::ParameterList specific_parameters;
162 //! %Parameter for COORM
163 string launcher_file;
164 //! %Parameter for COORM
165 string launcher_args;
168 struct JobDescription
171 Engines::JobParameters job_parameters;
173 typedef sequence<Engines::JobDescription> JobsList;
175 interface SalomeLauncherObserver
177 void notify(in string event_name, in string event_data);
180 //! Interface of the %salome launcher.
181 /*! This interface is used for interaction with the unique instance
183 The utilisation of this interface is explained in the YACS documentation,
184 article "Starting a SALOME application in a batch manager".
185 Other examples of use can be found in the modules JOBMANAGER, PARAMETRIC
186 and SMESH (PADDER tool).
188 interface SalomeLauncher
191 //! Create a job and set its parameters, without launching it.
192 /*! Its state becomes "CREATED".
195 long createJob (in Engines::JobParameters job_parameters) raises (SALOME::SALOME_Exception);
197 //! Launch an already created job (job's state should be "CREATED").
198 /*! Launching the job consists of:
199 - create the working directory on the remote file system
200 - copy the input files into the working directory
201 - submit the job to the batch manager
203 void launchJob (in long job_id) raises (SALOME::SALOME_Exception);
205 //! Get the execution state of the job.
206 /*! \return "CREATED", "IN_PROCESS", "QUEUED", "RUNNING", "PAUSED",
207 "FINISHED" or "FAILED"
208 \see LIBBATCH/src/core/Constants.hxx
210 string getJobState (in long job_id) raises (SALOME::SALOME_Exception);
212 //! Get names or ids of hosts assigned to the job
213 string getAssignedHostnames (in long job_id) raises (SALOME::SALOME_Exception);
215 //! Copy the result files from the work directory of the job
216 //! to a local directory.
217 /*! The list of result files is given by the JobParameters::out_files parameter.
218 If a result "file" is a directory, the copy is recursive.
219 The "logs" directory contains the standard and the error outputs of the job.
220 \param job_id Job id returned by createJob().
221 \param directory Local directory where to copy the results.
222 If this value is an empty string (""), files will be
223 copied to the directory given by
224 JobParameters::result_directory.
228 void getJobResults(in long job_id, in string directory) raises (SALOME::SALOME_Exception);
230 //! Try to copy the files named "dumpState*.xml" from the working directory.
231 /*! The file "dumpState_name.xml" can be produced by the execution of a YACS
232 schema and it contains the execution state of the schema.
233 You can activate the creation of this file by adding the parameter
234 "EnableDumpYACS" in JobParameters::specific_parameters when the job
236 \param job_id Job id returned by createJob().
237 \param directory Local directory where to copy the file.
238 If this value is an empty string (""), the file will be
239 copied to the directory given by
240 JobParameters::result_directory.
241 \return 1 if the copy succeeds.
242 \see JobParameters::specific_parameters
244 boolean getJobDumpState(in long job_id, in string directory) raises (SALOME::SALOME_Exception);
246 //! Retrieve one sigle file from the working directory.
247 /*! Use this method if you don't want to copy all the results of the job,
248 for instance if you want to obtain a file which contains the computing
249 progress while the job is running.
250 \param job_id Job id returned by createJob().
251 \param work_file Path to the file to be copied, relative to the
252 working directory of the job. If it is a directory,
253 it will be copied recursively.
254 \param directory Local directory where to copy the file.
255 If this value is an empty string (""), the file will be
256 copied to the directory given by
257 JobParameters::result_directory.
258 \return 1 if the copy succeeds.
260 boolean getJobWorkFile(in long job_id, in string work_file, in string directory) raises (SALOME::SALOME_Exception);
262 //! Kill the job and set its state to "FAILED"
263 void stopJob (in long job_id) raises (SALOME::SALOME_Exception);
264 //! Kill the job and remove it from the jobs list
265 void removeJob (in long job_id) raises (SALOME::SALOME_Exception);
268 long createJobWithFile(in string xmlJobFile, in string clusterName) raises (SALOME::SALOME_Exception);
269 boolean testBatch (in ResourceParameters params) raises (SALOME::SALOME_Exception);
271 // SALOME kernel service methods
272 //! Shutdow SalomeLauncher server.
274 //! Get the PID of the current process
277 // Observer and introspection methods
278 //! Add an observer to be notified of the jobs list modifications
279 void addObserver(in Engines::SalomeLauncherObserver observer);
280 void removeObserver(in Engines::SalomeLauncherObserver observer);
281 Engines::JobsList getJobsList();
282 Engines::JobParameters getJobParameters(in long job_id) raises (SALOME::SALOME_Exception);
284 // Save and load methods
285 //! Add to the current jobs list the jobs previously saved in an xml file.
286 void loadJobs(in string jobs_file) raises (SALOME::SALOME_Exception);
287 //! Save the current list of jobs in an xml file.
288 void saveJobs(in string jobs_file) raises (SALOME::SALOME_Exception);