X-Git-Url: http://git.salome-platform.org/gitweb/?a=blobdiff_plain;f=idl%2FSALOME_Launcher.idl;h=c9be320492dd75be0b4113c17af246a530af9527;hb=f9ce15cb3b95e2156c0b967ec70b69ba1d864a2f;hp=8b72b422c5a2a14e4f5ec2134d9a6dbdacc4f69c;hpb=b83f7739ffb0509786b791c57366a57a4cc7c3e2;p=modules%2Fkernel.git diff --git a/idl/SALOME_Launcher.idl b/idl/SALOME_Launcher.idl index 8b72b422c..c9be32049 100644 --- a/idl/SALOME_Launcher.idl +++ b/idl/SALOME_Launcher.idl @@ -1,4 +1,4 @@ -// Copyright (C) 2007-2012 CEA/DEN, EDF R&D, OPEN CASCADE +// Copyright (C) 2007-2021 CEA/DEN, EDF R&D, OPEN CASCADE // // Copyright (C) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS @@ -6,7 +6,7 @@ // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Lesser General Public // License as published by the Free Software Foundation; either -// version 2.1 of the License. +// version 2.1 of the License, or (at your option) any later version. // // This library is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of @@ -26,7 +26,7 @@ #include "SALOME_Exception.idl" #include "SALOME_ResourcesManager.idl" -/*! \file SALOME_Launcher.idl \brief interfaces for %SALOME Launcher service +/*! \file SALOME_Launcher.idl \brief Interfaces for %SALOME Launcher service */ module Engines @@ -46,37 +46,137 @@ typedef sequence ParameterList; struct JobParameters { + //! Name of the job. string job_name; - //! Job Type - Could be equal to "command" or "yacs_file" or "python_salome" + + //! Type of the job. + /*! There are three supported types: + - "command" : execute #job_file script without %SALOME environment + - "command_salome" : execute #job_file script within %SALOME environment + (salome shell) but the %SALOME application is not + launched + - "python_salome" : execute #job_file python script by %SALOME + - "yacs_file" : execute #job_file by YACS module as a xml YACS schema + */ string job_type; // Common values + //! Local path to the file to be executed by the job. + /*! The type of the file depends on #job_type. + If #job_type is "command", the #job_file must be a single filename + specifying a self-consistent script to be executed without any argument, + on the remote host. + */ string job_file; + + //! Pre processing script. + /*! This script is called on the remote resource, from #work_directory, after + the copy of #in_files and before submiting the job. + */ + string pre_command; + + //! Local path to a script to be sourced in the environment of the job. + /*! It may contain modifications of environment variables. + */ string env_file; + + //! List of local data files to be copied to #work_directory. + /*! #job_file and #env_file are automatically copied, without adding them + to this list. If basenames are specified, then the files are supposed + to be located in #local_directory. + */ FilesList in_files; + + //! List of results to get back at the end of the job. + /*! These results can be names of files or directories, produced by the job + in #work_directory. Directories will be copied recursively. + It is also possible to use an absolute path instead of the simple name, + (string beginning with '/') and this absolute path will be used instead + of #result_directory when SalomeLauncher::getJobResults is called. + \see SalomeLauncher::getJobResults + */ FilesList out_files; + + //! Remote directory where the job will be executed. + /*! It must be used to specify the remote directory where to put all + the stuff to run the job. Note that the job will be executed from within + this directory. A change directory toward this working directory is done + by the batch system before running the job. + If not specified (empty string), the launcher will use the working + directory of the chosen resource and if this is also an empty string + the value used will be $HOME/Batch/workdir_"date" where $HOME is the + value of the environment variable on the remote resource and "date" is + the current date. + */ string work_directory; + + //! Prefix to be applied to #in_files. + /*! It can be used to specify where to find the local input files. + It's optional if you specify the absolute path name of input files. + */ string local_directory; + + //! Local directory where to get result files. + /*! It must be used to specify where to download the output files on the + local file system. + If not specified (empty string), the value of $HOME environment variable + will be used. + \see SalomeLauncher::getJobResults + */ string result_directory; - /*! Time for the batch (has to be like this : hh:mm) - Could be empty, in - this case, default value of the selected resource will be used. + //! Maximum time for the batch execution (expected format : "hh:mm"). + /*! Could be empty, in this case, default value of the selected resource + will be used. */ string maximum_duration; - // Memory is expressed in megabytes -> mem_mb - // Number of Processors -> nb_proc + //! Specifies the rules to choose the resource where to execute the job. + /*! The additional two following parameters MUST be specified explicitly, + because they are not provided by the resource definition: + - mem_mb -> Memory expressed in megabytes. + - nb_proc -> Number of Processors. + */ ResourceParameters resource_required; - /*! - Name of the batch queue choosed - optional - */ + //! Name of the batch queue chosen - optional string queue; - /*! - Specific parameters for each type of job - optional + //! Name of the partition - optional + /*! It can be used only for slurm batch managers. + */ + string partition; + + //! Specifies if the job must run in exclusive mode (without sharing nodes with other jobs) + boolean exclusive; + + //! Specifies the memory limit per cpu (exclusive with resource_required.mem_mb) + unsigned long mem_per_cpu; + + //! Workload Characterization Key - mandatory on some clusters + string wckey; + + //! String that is added to the job submission file - optional + string extra_params; + + //! Specific parameters for each type of job - optional + /*! This is a list of parameters (key - value pairs of strings) useful in + some specific situations. + Known parameters: + - EnableDumpYACS : value of the "dump" option of the "driver" command + when the job type is "yacs_file". It gives the number of seconds + between two updates of the state dump file. There will be no dump file + if this parameter is missing or if its value is less than 1. + - YACSDriverOptions : options of the driver command when the job type is + "yacs_file". + - LoalLevelerJobType : LL_JOBTYPE. */ Engines::ParameterList specific_parameters; + + //! %Parameter for COORM + string launcher_file; + //! %Parameter for COORM + string launcher_args; }; struct JobDescription @@ -91,39 +191,133 @@ interface SalomeLauncherObserver void notify(in string event_name, in string event_data); }; -/*! \brief Interface of the %salomelauncher - This interface is used for interaction with the unique instance - of SalomeLauncher +//! Interface of the %salome launcher. +/*! This interface is used for interaction with the unique instance + of SalomeLauncher. + The utilisation of this interface is explained in the YACS documentation, + article "Starting a SALOME application in a batch manager". + Other examples of use can be found in the modules JOBMANAGER, PARAMETRIC + and SMESH (PADDER tool). */ interface SalomeLauncher { // Main methods + //! Create a job and set its parameters, without launching it. + /*! Its state becomes "CREATED". + \return job id + */ long createJob (in Engines::JobParameters job_parameters) raises (SALOME::SALOME_Exception); + + //! Launch an already created job (job's state should be "CREATED"). + /*! Launching the job consists of: + - create the working directory on the remote file system + - copy the input files into the working directory + - launch the pre processing command if one is defined + - submit the job to the batch manager + */ void launchJob (in long job_id) raises (SALOME::SALOME_Exception); + + //! Get the execution state of the job. + /*! \return "CREATED", "IN_PROCESS", "QUEUED", "RUNNING", "PAUSED", + "FINISHED", "ERROR" or "FAILED" + \see LIBBATCH/src/core/Constants.hxx + */ string getJobState (in long job_id) raises (SALOME::SALOME_Exception); + + //! Get names or ids of hosts assigned to the job + string getAssignedHostnames (in long job_id) raises (SALOME::SALOME_Exception); + + //! Copy all the in_files of the job to the work_directory. + void exportInputFiles(in long job_id) raises (SALOME::SALOME_Exception); + + //! Copy the result files from the work directory of the job + //! to a local directory. + /*! The list of result files is given by the JobParameters::out_files parameter. + If a result "file" is a directory, the copy is recursive. + The "logs" directory contains the standard and the error outputs of the job. + \param job_id Job id returned by createJob(). + \param directory Local directory where to copy the results. + If this value is an empty string (""), files will be + copied to the directory given by + JobParameters::result_directory. + \see JobParameters + \see createJob + */ void getJobResults(in long job_id, in string directory) raises (SALOME::SALOME_Exception); + + //! Try to copy the files named "dumpState*.xml" from the working directory. + /*! The file "dumpState_name.xml" can be produced by the execution of a YACS + schema and it contains the execution state of the schema. + You can activate the creation of this file by adding the parameter + "EnableDumpYACS" in JobParameters::specific_parameters when the job + is created. + \param job_id Job id returned by createJob(). + \param directory Local directory where to copy the file. + If this value is an empty string (""), the file will be + copied to the directory given by + JobParameters::result_directory. + \return 1 if the copy succeeds. + \see JobParameters::specific_parameters + */ boolean getJobDumpState(in long job_id, in string directory) raises (SALOME::SALOME_Exception); + + //! Remove the working directory on the remote file system. + /*! + \param job_id Job id returned by createJob(). + */ + void clearJobWorkingDir(in long job_id) raises (SALOME::SALOME_Exception); + + //! Retrieve one single file from the working directory. + /*! Use this method if you don't want to copy all the results of the job, + for instance if you want to obtain a file which contains the computing + progress while the job is running. + \param job_id Job id returned by createJob(). + \param work_file Path to the file to be copied, relative to the + working directory of the job. If it is a directory, + it will be copied recursively. + \param directory Local directory where to copy the file. + If this value is an empty string (""), the file will be + copied to the directory given by + JobParameters::result_directory. + \return 1 if the copy succeeds. + */ + boolean getJobWorkFile(in long job_id, in string work_file, in string directory) raises (SALOME::SALOME_Exception); + + //! Kill the job and set its state to "FAILED" void stopJob (in long job_id) raises (SALOME::SALOME_Exception); + //! Kill the job and remove it from the jobs list void removeJob (in long job_id) raises (SALOME::SALOME_Exception); + //! Get the job's serialization string + string dumpJob(in long job_id) raises (SALOME::SALOME_Exception); + //! Create a job from its serialization string + /*! \param dumpedJob Serialization string returned by dumpJob. + \return Job id + */ + long restoreJob(in string dumpedJob) raises (SALOME::SALOME_Exception); + // Useful methods long createJobWithFile(in string xmlJobFile, in string clusterName) raises (SALOME::SALOME_Exception); boolean testBatch (in ResourceParameters params) raises (SALOME::SALOME_Exception); // SALOME kernel service methods + //! Shutdow SalomeLauncher server. void Shutdown(); + //! Get the PID of the current process long getPID(); // Observer and introspection methods + //! Add an observer to be notified of the jobs list modifications void addObserver(in Engines::SalomeLauncherObserver observer); void removeObserver(in Engines::SalomeLauncherObserver observer); Engines::JobsList getJobsList(); Engines::JobParameters getJobParameters(in long job_id) raises (SALOME::SALOME_Exception); // Save and load methods + //! Add to the current jobs list the jobs previously saved in an xml file. void loadJobs(in string jobs_file) raises (SALOME::SALOME_Exception); + //! Save the current list of jobs in an xml file. void saveJobs(in string jobs_file) raises (SALOME::SALOME_Exception); - }; };