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