// Copyright (C) 2007-2016 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 // // 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, 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 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU // Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public // License along with this library; if not, write to the Free Software // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA // // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com // #ifndef _SALOME_LAUNCHER_IDL_ #define _SALOME_LAUNCHER_IDL_ #include "SALOME_Exception.idl" #include "SALOME_ResourcesManager.idl" /*! \file SALOME_Launcher.idl \brief Interfaces for %SALOME Launcher service */ module Engines { //! files list typedef sequence FilesList; //! A generic parameter struct Parameter { string name; string value; }; //! Generic parameter list typedef sequence ParameterList; struct JobParameters { //! Name of the job. string job_name; //! Type of the job. /*! There are three supported types: - "command" : execute #job_file script without %SALOME environment - "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; //! 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 automaticaly 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 ressource 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 ressource 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 optionnal 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; //! 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; //! Specifies the rules to choose the ressource where to execute the job. /*! The additionnal 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 chosen - optional string queue; //! 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. */ Engines::ParameterList specific_parameters; //! %Parameter for COORM string launcher_file; //! %Parameter for COORM string launcher_args; }; struct JobDescription { long job_id; Engines::JobParameters job_parameters; }; typedef sequence JobsList; interface SalomeLauncherObserver { void notify(in string event_name, in string event_data); }; //! 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 - 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" 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 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); //! Retrieve one sigle 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); // 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); }; }; #endif