1 \input texinfo @c -*-texinfo-*-
3 @setfilename Batch.info
4 @settitle Documentation de Batch
12 @dircategory Bibliotheque de classes Batch
14 * Batch: (Batch); Documentation de la bibliotheque de classes Batch.
23 @comment The title is printed in a large font.
24 @title Bibliotheque de classes Batch
25 @subtitle Documentation - version @value{VERSION}
26 @subtitle @value{UPDATED}
27 @author Ivan DUTKA-MALEN - EDF R&D
29 @c The following two commands start the copyright page.
31 @vskip 0pt plus 1filll
32 Copyright @copyright{} 2003-2004 EDF R&D sous licence GPL
38 @c ----------------------
39 @c ----------------------
40 @c ----------------------
42 @node Top, Description, Index , (dir)
43 @comment node-name, next, previous, up
45 Copyright @copyright{} 2003-2004 EDF R&D sous licence GPL
48 @unnumbered Introduction
50 Ceci est la documentation de la bibliotheque de classes Batch version
53 Ce manuel est normalement disponible sous la forme de fichiers
54 @file{.info}, PostScript @file{.ps}, PDF @file{.pdf} et HTML
55 @file{.html}. Merci a Texinfo.
59 * Description:: Le batch, c'est quoi ? Ca sert a quoi ?
60 * Classes:: Une description des classes internes.
61 * Utilisation:: Comment on s'en sert ? Quelques exemples.
62 * Installation de la bibliotheque:: Comment ca s'installe ?
63 * Divers:: D'autres petits details.
64 * Index:: Index generaux.
74 @c ----------------------
75 @c ----------------------
76 @c ----------------------
78 @node Description, Classes, Top, Top
79 @comment node-name, next, previous, up
80 @chapter Description Generale
83 Dans le domaine du batch, nombreux sont les gestionnaires qui sont
84 apparus et se sont popularises en fonction des plates-formes et des
85 constructeurs. On peut notamment citer NQS, le premier de tous, LSF,
86 LoadLeveler, PBS (et ses derives OpenPBS et PBS Pro), etc. qui se
87 prevalent tous d'une compatibilite avec NQS.
89 Si l'ensemble de ces produits offrent les fonctionnalites de base de
90 NQS, a savoir soumission, controle, destruction, modification, etc. de
91 travaux batch, ils se distinguent tous par leur incompatibilite mutuelle
92 et par les syntaxes de fichiers et les appels de fonction specifiques
93 qu'ils ont developpes.
95 Or il est interessant de pouvoir acceder d'une facon homogene et
96 generique aux fonctionnalites de ces gestionnaires quitte a se
97 restreindre a un sous-ensemble minimal mais essentiel de leurs
100 La bibliotheque de classes Batch fournit ce moyen de soumettre et
101 controler des travaux batch depuis une machine cliente sans s'occuper du
102 type de gestionnaire present sur le serveur sur lequel se deroule
103 l'execution du travail. Seul doit etre precise le nom du serveur sur
104 lequel sera soumis le travail batch et le type de gestionnaire qui s'y
105 trouve. Tout le reste est generique et ne depend plus de l'implementation.
113 @c ----------------------
114 @c ----------------------
115 @c ----------------------
117 @node Classes, Terminologie, Description, Top
118 @comment node-name, next, previous, up
119 @chapter Classes Internes
122 Les classes de la bibliotheque reposent sur des concepts issus du monde
123 de la gestion de batch, qui meritent d'etre reprecises pour ne pas
124 introduire d'ambiguite semantique dans le discours.
127 * Terminologie:: Description des termes employes.
128 * Classes generiques:: Les classes communes a tous les gestionnaires.
129 * Classes specifiques:: Les classes d'implementation.
135 @c ----------------------
136 @c ----------------------
137 @c ----------------------
139 @node Terminologie, Batch, Classes, Classes
140 @comment node-name, next, previous, up
141 @section Terminologie
144 Pour les non-inities aux mysteres de la gestion de batch, un petit
145 glossaire des termes employes dans cette documentation, assaisonne a la
146 sauce de la bibliotheque de classes Batch.
149 * Batch:: Gestion par lots, execution differee.
150 * BatchManager:: Gestionnaire de batch.
152 * Parametre:: Configuration de l'execution.
153 * Environnement:: Environnement d'execution.
154 * JobId:: Identifiant de travail.
155 * JobInfo:: Informations sur le travail.
159 @c ----------------------
160 @c ----------------------
161 @c ----------------------
163 @node Batch, BatchManager, Terminologie, Terminologie
164 @comment node-name, next, previous, up
168 Le traitement batch (batch processing en anglais), ou traitement par
169 lot, fait reference au mode de sequencage et d'utilisation des
170 ressources d'un calculateur tel qu'il a ete premierement employe dans
171 les debuts de l'ere informatique. Mais il faut preciser que cette
172 anteriorite ne condamne pas le traitement batch aux oubliettes au motif
173 d'une quelconque obsolescence. Si le traitement par lot a vu le jour et
174 existe encore aujourd'hui, c'est parce qu'il repond de maniere
175 satisfaisante a une certaine utilisation des ressources d'un
176 calculateur, et que cette utilisation est encore d'actualite. Present
177 depuis plus de quarante ans, le batch est encore largement utilise sur
178 les grands serveurs, et le sera vraisemblablement pour quelques annees
181 Le traitement par lot se distingue de l'execution interactive par le
182 fait que les travaux a effectuer sont places dans une file d'attente
183 avec une indication pour chaque lot des ressources dont il doit disposer
184 pour aboutir correctement. Une fois les travaux inscrits dans la file,
185 c'est au systeme de traitement batch (@xref{BatchManager}.) de veiller a
186 leur bonne execution en leur fournissant les ressources demandees. Tout
187 travail qui ne disposerait pas des ressources adequates ne peut pas etre
191 @c ----------------------
192 @c ----------------------
193 @c ----------------------
195 @node BatchManager, Job, Batch, Terminologie
196 @comment node-name, next, previous, up
197 @subsection Batch Manager
198 @cindex batch manager
201 Le role du gestionnaire de batch, ou batch manager en anglais, est
202 d'executer et eventuellement d'ordonner les travaux places en file
203 d'attente en leur allouant exclusivement les ressources necessaires a
204 leur execution. Son objectif est d'optimiser les ressources du systeme
205 dont il a la charge de maniere a ecouler le maximum de travaux en un
206 minimum de temps et un minimum de ressources materielles.
208 @c ----------------------
209 @c ----------------------
210 @c ----------------------
212 @node Job, Parametre, BatchManager, Terminologie
213 @comment node-name, next, previous, up
218 Le travail, ou job en anglais, est l'unite elementaire de traitement qui
219 peut etre soumis au gestionnaire de batch. Il peut s'agir d'une simple
220 commande systeme, comme d'une application ou bien meme de l'enchainement
221 complexe mais indivisible de plusieurs applications ou commandes.
223 Pour s'executer correctement, c'est-a-dire sans erreur, le job doit
224 disposer de certaines ressources --- de la memoire, du temps, de
225 l'espace disque @dots{} --- pendant toute la duree de son
226 execution. C'est au gestionnaire de batch (@xref{BatchManager}.) de
227 garantir au job la presence et la persistence de ces ressources pendant
230 Par contre c'est a l'utilisateur qui soumet le job d'informer le
231 gestionnaire de batch des ressources necessaires au job. Pour des
232 raisons evidentes de bonne gestion des ressources, le job ne peut
233 consommer plus de ressources que celles qu'il a demande et obtenu du
234 gestionnaire de batch sans etre arrete ou reclasse.
236 @c ----------------------
237 @c ----------------------
238 @c ----------------------
240 @node Parametre, Environnement, Job, Terminologie
241 @comment node-name, next, previous, up
242 @subsection Parametre
245 Le premier type de ressource necessaire a un job concerne les elements
246 materiels ou temporels, en un mot, physiques. Parmi ces ressources, on
247 trouve le temps de calcul, le temps de presence en machine, l'espace
248 disque, la quantite de memoire vive, l'architecture du calculateur, etc.
250 Dans la terminologie de la bibliotheque de classes Batch, tous ces
251 elements ont ete regroupes sous le terme de @emph{Parametre}.
253 @c ----------------------
254 @c ----------------------
255 @c ----------------------
257 @node Environnement, JobId, Parametre, Terminologie
258 @comment node-name, next, previous, up
259 @subsection Environnement
260 @cindex environnement
262 Le second type de ressource necessaire a un job concerne les elements
263 logiciels. Cela se traduit le plus souvent, et particulierement, dans
264 les systemes Unix par la notion de variable d'environnement. Lorsque le
265 job s'execute, il doit pouvoir trouver l'ensemble des commandes et des
266 applications auquel il souhaite faire appel. Les variables
267 d'environnement decrivent donc les localisations des ces
268 programmes. Elles peuvent egalement contenir des informations influant
269 sur le comportement des programmes.
271 Dans la terminologie de la bibliotheque de classes Batch, tous ces
272 elements on ete regroupes sous le terme de @emph{Environnement}.
274 @c ----------------------
275 @c ----------------------
276 @c ----------------------
278 @node JobId, JobInfo, Environnement, Terminologie
279 @comment node-name, next, previous, up
284 Si un job (@xref{Job}.) decrit les actions qui doivent etre effectues
285 par le systeme sous le controle du gestionnaire de batch, il est clair
286 qu'il est possible de soumettre plusieurs fois de suite le meme job, et
287 par la-meme d'executer plusieurs fois (et parfois simultanement) ces
288 memes actions. On a donc plusieurs instances du meme job qui sont
289 presentes en machine. Chaque instance peut etre distinguee des autres
290 par un identifiant unique qui lui est propre : c'est le @emph{jobId}.
292 Le JobId est determine par le gestionnaire de batch au moment de la
295 @c ----------------------
296 @c ----------------------
297 @c ----------------------
299 @node JobInfo, Classes generiques, JobId, Terminologie
300 @comment node-name, next, previous, up
305 Des qu'un job (@xref{Job}.) est soumis donc des qu'il dispose d'un
306 JobId (@xref{JobId}.), il est possible d'interroger le gestionnaire de
307 batch pour etre informe de son comportement, de son evolution au sein du
308 systeme pendant son execution.
310 On peut ainsi connaitre les parametres reellement consommes par rapport
311 aux parametres alloues, ainsi que l'environnement d'execution du job.
313 Le JobInfo est une structure qui collecte ses informations sur l'etat du
320 @c ----------------------
321 @c ----------------------
322 @c ----------------------
324 @node Classes generiques, Namespace, JobInfo, Classes
325 @comment node-name, next, previous, up
326 @section Classes generiques
327 @cindex classes generiques
329 Schematiquement, les classes composant la bibliotheque sont regroupees
330 en trois categories. Celles appartenant au groupe @emph{Types de base}
331 ne servent que de support au fonctionnement des classes de plus haut
332 niveau, egalement appellees @emph{Classes utilisateur}. Seules ces
333 dernieres sont vraiment interessantes pour l'utilisateur de la
334 bibliotheque. Les exceptions sont regroupees dans une categorie qui leur
338 * Namespace:: Espace de noms pour la bibliotheque.
339 * Types de base:: Les classes elementaires.
340 * Classes utilisateur:: Les classes de haut-niveau.
341 * Exceptions:: Les exceptions de la bibliotheque.
344 @c ----------------------
345 @c ----------------------
346 @c ----------------------
348 @node Namespace, Types de base, Classes generiques, Classes generiques
349 @comment node-name, next, previous, up
350 @subsection Namespace
353 Toutes les classes de la bibliotheque sont regroupees dans un unique
354 namespace nomme @emph{Batch} afin de ne pas introduire de conflit avec
355 d'autres classes de meme nom.
357 Ainsi lorsque par exemple on cite la classe @emph{BatchManager}, il
358 faudra declarer un objet @emph{Batch::BatchManager} ou bien faire appel
359 au namespace @emph{Batch} en C++. En Python, les objets sont regroupes
360 dans un module nomme @emph{libBatch_Swig}.
363 @c ----------------------
364 @c ----------------------
365 @c ----------------------
367 @node Types de base, Classe Couple, Namespace, Classes generiques
368 @comment node-name, next, previous, up
369 @subsection Types de base
370 @cindex types de base
372 Les classes decrites ici sont toutes utilisees ou utilisables par les
373 classes utilisateur de la bibliotheque, et en particulier par la classe
374 Versatile. @xref{Classe Versatile}.
376 Ces classes implementent sous forme d'objet les types de base du langage
377 C++. Ainsi la classe @emph{Booltype} implemente le type de base
378 @emph{bool}. Certains types de base n'existant pas dans le langage ont
379 ete crees et encapsules dans une classe : c'est le cas notamment du type
380 de base @emph{Date} et de la classe @emph{DateType}, et du type de base
381 @emph{Couple} et de la classe @emph{CoupleType}.
383 Tous les classes heritent de la classe generique @emph{GenericType}.
388 * Classe Couple:: Association de fichiers.
389 * Classe Date:: Type elementaire de date.
391 -- Classes d'implementation des types de base --
393 * Classe GenericType:: Classe-mere de tous les types.
394 * Classe BoolType:: Encapsulation du type bool.
395 * Classe CharType:: Encapsulation du type char.
396 * Classe CoupleType:: Encapsulation du type Couple.
397 * Classe DateType:: Encapsulation du type Date.
398 * Classe IntType:: Encapsulation du type int.
399 * Classe LongType:: Encapsulation du type long.
400 * Classe StringType:: Encapsulation du type string.
404 @c ----------------------
405 @c ----------------------
406 @c ----------------------
408 @node Classe Couple, Classe Date, Types de base, Types de base
409 @comment node-name, next, previous, up
411 @subsubsection Couple
414 La classe @emph{Couple} implemente le comportement d'un couple de deux
415 chaines de type @emph{string} qui sont respectivement nommees
416 @emph{local} et @emph{remote}.
418 Cette classe est utilisee essentiellement pour la designation des
419 fichiers a transferer lors des soumissions de travaux, d'ou les noms
423 Il faut toutefois faire attention a designer correctement ce qui est
424 local ou distant. Ainsi dans la bibliotheque de classes Batch, on a
425 adopte la convention qu'un fichier dit @emph{local} est celui present
426 sur la machine qui execute la bibliotheque de classes Batch, alors qu'un
427 fichier dit @emph{remote} (ou distant) est celui present sur le serveur
428 du gestionnaire de batch.
429 L'approche est donc clairement orientee utilisateur plutot que serveur.
439 // Constructeur standard
440 Couple(const string & local, const string & remote);
442 // Constructeur par recopie
443 Couple(const Couple & C);
445 // Operateur pour l'affichage sur un stream
446 friend ostream & operator << (ostream & os, const Couple & cp);
448 // Operateur d'affectation
449 virtual Couple & operator =(const Couple &);
451 // Conversion en chaine
452 virtual string str() const;
455 virtual string getLocal() const;
456 virtual string getRemote() const;
459 string _local; // chemin d'acces au fichier local
460 string _remote; // chemin d'acees au fichier distant
469 @c ----------------------
470 @c ----------------------
471 @c ----------------------
473 @node Classe Date, Classe GenericType, Classe Couple, Types de base
474 @comment node-name, next, previous, up
479 La classe @emph{Date} sert a stocker n'importe quelle information de
480 temps et peut la representer sous une forme plus lisible a l'utilisateur
481 que le traditionnel appel a la fonction @emph{ctime}. @xref{(*manpages*)ctime}.
490 // Constructeur standard (a partir d'une valeur epoch)
491 Date(const long l=0);
493 // Constructeur a partir d'une chaine hh:mm:ss
494 Date(const string s);
496 // Operateurs portant sur les Dates
497 virtual Date & operator =(long l);
498 virtual Date & operator +(long l);
499 virtual Date & operator -(long l);
500 virtual Date & operator +=(long l);
501 virtual Date & operator -=(long l);
502 virtual Date & operator =(const string & s);
504 // Conversions en types standards
505 virtual string str() const;
506 virtual long epoch() const;
509 int _day, _month, _year;
510 int _hour, _min, _sec;
520 @c ----------------------
521 @c ----------------------
522 @c ----------------------
524 @node Classe GenericType, Classe BoolType, Classe Date, Types de base
525 @comment node-name, next, previous, up
527 @subsubsection GenericType
530 La classe @emph{GenericType} est la classe-mere de toutes les classes
531 utilisees par la classe @emph{Versatile}. @xref{Classe Versatile}.
533 Elle definit une interface que @emph{Versatile} utilise pour controler
534 les objets : constructeur simple et destructeur, operateur sur
535 @emph{ostream}, conversion en chaine et surtout methode @emph{clone}.
537 La methode @emph{clone} permet de recuperer un nouvel objet identique au
538 premier qui sera automatiquement alloue sur le tas par un appel a
539 @emph{new}. Il est important de noter ici que le nouvel objet @strong{DEVRA}
540 etre desalloue par un appel a @emph{delete}. Cette desallocation est a
541 la charge de l'utilisateur de l'objet sans quoi une fuite memoire en
551 // Constructeur et destructeur
553 virtual ~GenericType();
555 // Operateur pour l'affichage sur un stream
556 friend ostream & operator << (ostream & os,
557 const GenericType & obj);
559 // Conversion en chaine
560 virtual string affiche() const;
562 // Clone duplique l'objet et en fabrique un nouveau a l'aide de new
563 // qu'il faudra detruire ensuite manuellement
564 virtual GenericType * clone() const;
566 // Retourne le nombre d'objets GenericType et al.
572 static int _nb; // nombre total d'objets GenericType et al.
579 @c ----------------------
580 @c ----------------------
581 @c ----------------------
583 @node Classe BoolType, Classe CharType, Classe GenericType, Types de base
584 @comment node-name, next, previous, up
586 @subsubsection BoolType
589 Cette classe encapsule le type C++ @emph{bool} dans un objet herite de
590 @emph{GenericType} de maniere a pouvoir le stocker aisement dans un
591 objet de classe @emph{Versatile}.
597 class BoolType : public GenericType
601 BoolType(const bool b=false);
603 // Conversion en chaine
604 virtual string affiche() const;
606 // Operateur d'affectation
607 virtual BoolType & operator =(bool);
609 // Conversion en bool
610 virtual operator bool() const;
612 // Clone duplique l'objet et en fabrique un nouveau a l'aide de new
613 // qu'il faudra detruire ensuite manuellement
614 virtual GenericType * clone() const;
626 @c ----------------------
627 @c ----------------------
628 @c ----------------------
630 @node Classe CharType, Classe CoupleType, Classe BoolType, Types de base
631 @comment node-name, next, previous, up
633 @subsubsection CharType
636 Cette classe encapsule le type C++ @emph{char} dans un objet herite de
637 @emph{GenericType} de maniere a pouvoir le stocker aisement dans un
638 objet de classe @emph{Versatile}.
645 class CharType : public GenericType
649 CharType(const char c=0);
651 // Conversion en chaine
652 virtual string affiche() const;
654 // Operateur d'affectation
655 virtual CharType & operator =(char);
657 // Conversion en char
658 virtual operator char() const;
660 // Clone duplique l'objet et en fabrique un nouveau a l'aide de new
661 // qu'il faudra detruire ensuite manuellement
662 virtual GenericType * clone() const;
674 @c ----------------------
675 @c ----------------------
676 @c ----------------------
678 @node Classe CoupleType, Classe DateType, Classe CharType, Types de base
679 @comment node-name, next, previous, up
681 @subsubsection CoupleType
684 Cette classe encapsule le type interne @emph{Couple} dans un objet herite de
685 @emph{GenericType} de maniere a pouvoir le stocker aisement dans un
686 objet de classe @emph{Versatile}.
693 class CoupleType : public GenericType
697 CoupleType(const Couple & C);
699 // Conversion en chaine
700 virtual string affiche() const;
701 virtual operator string() const;
703 // Operateur d'affectation
704 virtual CoupleType & operator =(const Couple & C);
706 // Conversion en char
707 virtual operator Couple() const;
709 // Clone duplique l'objet et en fabrique un nouveau a l'aide de new
710 // qu'il faudra detruire ensuite manuellement
711 virtual GenericType * clone() const;
723 @c ----------------------
724 @c ----------------------
725 @c ----------------------
727 @node Classe DateType, Classe IntType, Classe CoupleType, Types de base
728 @comment node-name, next, previous, up
730 @subsubsection DateType
733 Cette classe encapsule le type interne @emph{Date} dans un objet herite de
734 @emph{GenericType} de maniere a pouvoir le stocker aisement dans un
735 objet de classe @emph{Versatile}.
742 class DateType : public GenericType
746 DateType(const Date & d);
748 // Conversion en chaine
749 virtual string affiche() const;
751 // Operateur d'affectation
752 virtual DateType & operator =(const Date &);
754 // Conversion en Date
755 virtual operator Date() const;
757 // Conversion en long
758 virtual operator long() const;
760 // Clone duplique l'objet et en fabrique un nouveau a l'aide de new
761 // qu'il faudra detruire ensuite manuellement
762 virtual GenericType * clone() const;
773 @c ----------------------
774 @c ----------------------
775 @c ----------------------
777 @node Classe IntType, Classe LongType, Classe DateType, Types de base
778 @comment node-name, next, previous, up
780 @subsubsection IntType
783 Cette classe encapsule le type C++ @emph{int} dans un objet herite de
784 @emph{GenericType} de maniere a pouvoir le stocker aisement dans un
785 objet de classe @emph{Versatile}.
792 class IntType : public GenericType
796 IntType(const int i=0);
798 // Conversion en chaine
799 virtual string affiche() const;
801 // Operateur d'affectation
802 virtual IntType & operator =(int);
805 virtual operator int() const;
807 // Clone duplique l'objet et en fabrique un nouveau a l'aide de new
808 // qu'il faudra detruire ensuite manuellement
809 virtual GenericType * clone() const;
821 @c ----------------------
822 @c ----------------------
823 @c ----------------------
825 @node Classe LongType, Classe StringType, Classe IntType, Types de base
826 @comment node-name, next, previous, up
828 @subsubsection LongType
831 Cette classe encapsule le type C++ @emph{long} dans un objet herite de
832 @emph{GenericType} de maniere a pouvoir le stocker aisement dans un
833 objet de classe @emph{Versatile}.
839 class LongType : public GenericType
843 LongType(const long l=0L);
845 // Conversion en chaine
846 virtual string affiche() const;
848 // Operateur d'affectation
849 virtual LongType & operator =(long);
851 // Conversion en long
852 virtual operator long() const;
854 // Clone duplique l'objet et en fabrique un nouveau a l'aide de new
855 // qu'il faudra detruire ensuite manuellement
856 virtual GenericType * clone() const;
868 @c ----------------------
869 @c ----------------------
870 @c ----------------------
872 @node Classe StringType, Classes utilisateur, Classe LongType, Types de base
873 @comment node-name, next, previous, up
875 @subsubsection StringType
878 Cette classe encapsule le type C++ @emph{string} de la STL dans un objet
879 herite de @emph{GenericType} de maniere a pouvoir le stocker aisement
880 dans un objet de classe @emph{Versatile}.
886 class StringType : public GenericType
890 StringType(const string & s="");
892 // Conversion en chaine
893 virtual string affiche() const;
894 virtual operator string() const;
896 // Operateur d'affectation
897 virtual StringType & operator =(string);
899 // Clone duplique l'objet et en fabrique un nouveau a l'aide de new
900 // qu'il faudra detruire ensuite manuellement
901 virtual GenericType * clone() const;
915 @c ----------------------
916 @c ----------------------
917 @c ----------------------
919 @node Classes utilisateur, Exemple, Classe StringType, Classes generiques
920 @comment node-name, next, previous, up
922 @subsection Classes utilisateur
923 @cindex classes utilisateur
925 Les classes dites classes utilisateur sont en realite les classes de
926 plus haut niveau de la biliotheque de classes Batch. Ces classes
927 remplissent les unes avec les autres l'ensemble des fonctionnalites
928 proposees par la bibliotheque. L'utilisateur trouvera donc dans cette
929 section la description des possibilites de la bibliotheque et le moyen
930 de les mettre en oeuvre.
932 La premiere section montre un exemple complet de soumission et de
933 controle d'un job soumis a travers les classes de la biliotheque. Les
934 sections suivantes reprennent les elements de l'exemple pour le
935 detailler et le completer.
938 * Exemple:: Exemple simple mais complet d'utilisation.
939 * Classe BatchManagerCatalog:: Description de la classe BatchManagerCatalog.
940 * Classe FactBatchManager:: Description de la classe FactBatchManager.
941 * Classe BatchManager:: Description de la classe BatchManager.
942 * Classe Environnement:: Description de la classe Environnement.
943 * Classe Job:: Description de la classe Job.
944 * Classe JobId:: Description de la classe JobId.
945 * Classe JobInfo:: Description de la classe JobInfo.
946 * Classe Parametre:: Description de la classe Parametre.
947 * Classe Versatile:: Description de la classe Versatile.
951 @c ----------------------
952 @c ----------------------
953 @c ----------------------
955 @node Exemple, Classe BatchManagerCatalog, Classes utilisateur, Classes utilisateur
956 @comment node-name, next, previous, up
958 @subsubsection Exemple
961 Cet exemple decrit le processus type de creation et de soumission d'un
962 job a travers les classes de la bibliotheque.
964 Il faut toutefois penser que les appels aux methodes peuvent lever des
965 exceptions qu'il faudra intercepter et gerer. @xref{Exceptions}.
970 // On recupere l'instance du catalogue de gestionnaires de batch
971 Batch::BatchManagerCatalog cata = Batch::BatchManagerCatalog::getInstance();
973 // On cree un BatchManager qui se connecte au veritable gestionnaire
975 Batch::BatchManager & bm = (* cata("PBS"))("monserver.mondomaine.fr");
977 // Pour fabriquer un Job, on doit d'abord creer un objet Parametre et
978 // un objet Environnement qui contiennent respectivement la liste des
979 // parametres du job au sein du gestionnaire de batch et la liste des
980 // variables d'environnement necessaires au fonctionnement du job
981 Batch::Parametre param;
983 param[EXECUTABLE] = "/home/user/mon_application/executable";
984 param[NAME] = "MonJob";
985 param[ACCOUNT] = "MonProjet"; // code d'imputation/facturation
986 param[MAXCPUTIME] = 360L; // 6min
987 param[MAXWALLTIME] = 480L; // 8min
988 param[INFILE] = Batch::Couple("/tmp/infich1", rempath+"/infich1");
989 param[OUTFILE] = Batch::Couple("/tmp/outfich1", rempath+"/outfich1");
990 param[OUTFILE] += Batch::Couple("stderr", path + "/STDERR");
991 param[OUTFILE] += Batch::Couple("stdout", path + "/STDOUT");
992 param[MAIL] = "user@@domaine.fr";
993 param[USER] = "user";
995 Batch::Environnement env;
996 env["DEBUG"] = "3"; // un niveau de debug exige par l'application
997 env["MYAPP_FILE"] = "/home/user/mon_application/data/mydatafile";
1000 Batch::Job job(param, env);
1002 // On soumet le Job au BatchManager qui le relaie jusqu'au veritable
1003 // gestionnaire de batch sur le serveur. En retour on obtient un
1004 // identifiant unique de notre job (JobId).
1005 const Batch::JobId jobid = bm.submitJob(job);
1007 // On interroge le BatchManager pour connaitre l'etat du Job
1008 const Batch::JobInfo jinfo = jobid.queryJob();
1009 cout << jinfo << endl;
1011 // On detruit l'objet BatchManager
1018 @c ----------------------
1019 @c ----------------------
1020 @c ----------------------
1022 @node Classe BatchManagerCatalog, Classe FactBatchManager, Exemple, Classes utilisateur
1023 @comment node-name, next, previous, up
1025 @subsubsection BatchManagerCatalog
1026 @findex BatchManagerCatalog
1028 La classe @emph{BatchManagerCatalog} definit une interface d'acces au
1029 catalogue de fabriques de BatchManager. @xref{Classe FactBatchManager}.
1031 Pourquoi utiliser une fabrique et ne pas instancier directement un objet
1032 @emph{BatchManager} en fonction de sa classe ? C'est l'option qui avait ete
1033 choisie dans la premiere version de la bibliotheque de classes
1034 Batch. Cette facon de proceder est simple, aussi bien pour le
1035 developpeur de la classe que pour l'utilisateur, mais elle se revele a
1036 terme penalisante dans la souplesse d'utilisation des classes. Elle
1037 permet aussi moins facilement de mettre en place une strategie de
1038 singleton pour les objets @emph{BatchManager}, ce qui peut se reveler utile non
1039 pas en termes de performance mais plutot en termes de genericite et
1040 toujours de souplesse.
1042 En resume, l'utilisation de fabiques permet d'acceder a la genericite,
1043 qui rappelons-le est l'objet de cette biliotheque, a la souplesse et a
1044 la performance au prix d'une legere complication pour le developpeur
1045 mais pas pour l'utilisateur.
1047 Le catalogue de fabriques est une @emph{map}, ou tableau associatif,
1048 auquel on passe le nom d'une fabrique et qui retourne un pointeur sur
1049 une instance de cette fabrique.
1051 Le catalogue est renseigne statiquement par les fabriques declarees
1052 elles-memes statiquement dans la biliotheque. Il est donc precharge avec
1053 les fabriques correspondant a chacune des API disponibles. Comme le
1054 catalogue n'est pas declare constant, il est possible de rajouter ou de
1055 supprimer des fabriques dans le catalogue dynamiquement.
1061 class BatchManagerCatalog
1064 // Methode permettant de recuperer l'instance unique de catalogue
1065 static BatchManagerCatalog& getInstance();
1068 void addFactBatchManager(const char * type, Batch::FactBatchManager * pFBM);
1069 Batch::FactBatchManager * operator() (const char * type);
1072 virtual std::map<std::string, FactBatchManager *> * dict();
1073 virtual std::string __repr__() const;
1077 BatchManagerCatalog();
1079 virtual ~BatchManagerCatalog();
1081 // Le catalogue proprement dit
1082 std::map<std::string, FactBatchManager *> _catalog;
1083 // Mutex permettant d'assurer des acces "thread-safe" au catalogue
1084 pthread_mutex_t _mutex;
1087 // On interdit la copie de l'instance unique du catalogue (singleton)
1088 BatchManagerCatalog(const BatchManagerCatalog & orig);
1089 BatchManagerCatalog& operator=(const BatchManagerCatalog & orig);
1099 // On recupere l'instance du catalogue de gestionnaires de batch
1100 Batch::BatchManagerCatalog cata = Batch::BatchManagerCatalog::getInstance();
1108 @b{static BatchManagerCatalog& getInstance()}
1110 Cette methode retourne l'instance unique du catalogue qui peut ensuite
1111 etre utilisee pour ajouter ou recuperer des fabriques.
1114 @b{void addFactBatchManager(const char * type, FactBatchManager * pFBM)}
1116 Cet accesseur enregistre dans le catalogue un pointeur sur un objet de type
1117 @emph{FactBatchManager} sous le nom (le type) passe en argument.
1120 @b{FactBatchManager * operator() (const char * type)}
1122 Cet accesseur retourne un pointeur sur un objet de type
1123 @emph{FactBatchManager} en fonction du nom (le type) sous lequel il
1124 s'est enregistre dans le catalogue.
1127 @b{map<string, FactBatchManager *> * dict()}
1129 Cette methode utilisable depuis Python permet de recuperer un
1130 dictionnaire decrivant le contenu du catalogue.
1133 @b{string __repr__() const}
1135 Cette methode utilisable depuis Python retourne une description de
1136 l'objet @emph{BatchManagerCatalog}.
1139 @b{BatchManagerCatalog()}
1141 Le constructeur par defaut est declare "protected" et ne peut donc pas
1142 etre utilise pour creer une nouvelle instance de @emph{BatchManagerCatalog}.
1143 En effet, le catalogue est un singleton, ce qui signifie qu'une seule
1144 instance du catalogue existe. Pour recuperer cette instance, il faut
1145 utiliser la methode @emph{BatchManagerCatalog::getInstance()}.
1148 @b{~BatchManagerCatalog()}
1150 De la meme maniere, le destructeur est declare "protected" et ne peut pas
1151 etre utilise pour detruire l'instance de catalogue. Le singleton est detruit
1152 automatiquement a la fin du programme.
1160 @c ----------------------
1161 @c ----------------------
1162 @c ----------------------
1164 @node Classe FactBatchManager, Classe BatchManager, Classe BatchManagerCatalog, Classes utilisateur
1165 @comment node-name, next, previous, up
1167 @subsubsection FactBatchManager
1168 @findex FactBatchManager
1170 La classe @emph{FactBatchManager} est abstraite. Elle definit une interface
1171 qui doit etre implementee par des classes specialisees en fonction du
1172 gestionnaire de batch et de son API de communication. @xref{Classes specifiques}.
1174 Les objets repondant a l'interface de @emph{FactBatchManager} sont
1175 automatiquement inseres dans le catalogue des fabriques de
1176 @emph{BatchManager} a la construction de l'objet. Il est ainsi possible
1177 de definir statiquement des objets de ce type qui enrichiront le
1178 catalogue des la compilation. @xref{Classe
1179 BatchManagerCatalog}. @xref{Classe BatchManager}.
1181 Les objets de la classe @emph{FactBatchManager} ou de ses derivees sont
1182 des functors et renvoient au moment de l'appel un pointeur sur un objet
1183 gestionnaire de batch @emph{BatchManager} associe a un
1184 serveur. L'allocation de l'objet est faite sur le tas et celui-ci doit
1185 donc etre desalloue manuellement par l'utilisateur de la bibliotheque au
1192 class FactBatchManager
1196 FactBatchManager(const string & type);
1199 virtual ~FactBatchManager();
1202 virtual BatchManager * operator() (const char * hostname) const = 0;
1204 // Accesseur au type interne
1205 string getType() const;
1208 string __repr__() const;
1211 string type; // Le type interne
1223 // On recupere l'instance du catalogue de gestionnaires de batch
1224 Batch::BatchManagerCatalog cata = Batch::BatchManagerCatalog::getInstance();
1226 // On cree une fabrique de BatchManager de type PBS
1227 Batch::FactBatchManager & fbm = * cata("PBS");
1236 @b{FactBatchManager(const string & type)}
1238 Le constructeur de la classe prend un type qui doit identifer de maniere
1239 unique la fabrique au sein du catalogue de fabrique. Ce type sert de cle au
1240 catalogue. @xref{Classe BatchManagerCatalog}.
1243 @b{~FactBatchManager()}
1245 Le destructeur de la classe n'a pas d'action particuliere.
1248 @b{BatchManager * operator() (const char * hostname) const}
1250 Cette methode est virtuelle pure. Elle doit etre surchargee dans les
1251 classes derivees et doit retourner un pointeur sur un objet de type
1252 @emph{BatchManager} correpondant au type de la classe et oeuvrant sur la
1253 machine passee en argument. Le @emph{hostname} est soit alphabetique
1254 soit numerique et doit etre soit un nom de machine valide soit une
1255 adresse IP valide. Aucun controle n'est a priori realise et cet argument
1256 est passe tel quel a l'API du gestionnaire de batch.
1258 Cet objet agit comme @emph{parent} vis-a-vis de l'objet
1259 @emph{BatchManager} qu'il retourne.
1262 @b{string getType() const}
1264 Cette methode renvoie le type interne de l'objet, c'est-a-dire la cle
1265 sous lequel il est enregistre dans le catalogue.
1268 @b{string __repr__() const}
1270 Cette methode utilisable depuis Python retourne une description de
1271 l'objet @emph{FactBatchManager}.
1279 @c ----------------------
1280 @c ----------------------
1281 @c ----------------------
1283 @node Classe BatchManager, Classe Environnement, Classe FactBatchManager, Classes utilisateur
1284 @comment node-name, next, previous, up
1286 @subsubsection BatchManager
1287 @findex BatchManager
1289 La classe @emph{BatchManager} est abstraite. Elle definit une interface
1290 qui doit etre implementee par des classes specialisees en fonction du
1291 gestionnaire de batch et de son API de communication. @xref{Classes
1294 Toute action a destination du gestionnaire de batch doit etre precedee
1295 de l'instanciation d'un objet derivant de la classe @emph{BatchManager}
1296 puisque c'est a travers cet objet que l'on aura acces a l'interface du
1299 Cette instanciation est realisee par une fabrique de gestionnaire de
1300 batch, instance elle-meme derivee de la classe abstraite
1301 FactBatchManager. @xref{Classe FactBatchManager}.
1310 // Constructeur et destructeur
1311 BatchManager(const FactBatchManager * parent,
1312 const char * host="localhost")
1313 throw(InvalidArgumentException);
1314 virtual ~BatchManager();
1316 // Recupere l'identifiant d'un job deja soumis au BatchManager
1317 virtual const JobId getJobIdByReference(const string & ref);
1319 // Methodes pour le controle des jobs : virtuelles pures
1320 // soumet un job au gestionnaire
1321 virtual const JobId submitJob(const Job & job) = 0;
1323 // retire un job du gestionnaire
1324 virtual void deleteJob(const JobId & jobid) = 0;
1326 // suspend un job en file d'attente
1327 virtual void holdJob(const JobId & jobid) = 0;
1329 // relache un job suspendu
1330 virtual void releaseJob(const JobId & jobid) = 0;
1332 // modifie un job en file d'attente
1333 virtual void alterJob(const JobId & jobid,
1334 const Parametre & param,
1335 const Environnement & env) = 0;
1336 virtual void alterJob(const JobId & jobid,
1337 const Parametre & param) = 0;
1338 virtual void alterJob(const JobId & jobid,
1339 const Environnement & env) = 0;
1341 // renvoie l'etat du job
1342 virtual JobInfo queryJob(const JobId & jobid) = 0;
1345 virtual string __repr__() const;
1348 string _hostname; // serveur ou tourne le BatchManager
1349 const FactBatchManager * _parent; // fabrique qui a produit l'instance
1361 // On recupere l'instance du catalogue de gestionnaires de batch
1362 Batch::BatchManagerCatalog cata = Batch::BatchManagerCatalog::getInstance();
1364 // On cree un BatchManager qui se connecte au veritable gestionnaire
1366 Batch::BatchManager & bm = (* cata("PBS"))("monserver.mondomaine.fr");
1368 // Maintenant, on peut utiliser toutes les fonctionnalites du
1369 // gestionnaire de batch a travers le variable myBM
1371 // On detruit l'objet BatchManager
1380 @b{BatchManager(const FactBatchManager * parent,$*
1381 const char * host="localhost") throw(InvalidArgumentException)}
1383 Excepte un pointeur sur la fabrique qui a produit l'objet, @xref{Classe FactBatchManager},
1384 le constructeur accepte zero ou un argument de type
1385 @emph{string} decrivant soit le nom de domaine completement qualifie
1386 (FQDN, @i{fully qualified domain name}) du serveur de batch, soit son
1387 adresse IP dans un format decimal "aaa.bbb.ccc.ddd".
1389 Une resolution du nom ou de l'adresse peut etre realisee en fonction des
1390 capacites de la plate-forme pour s'assurer que le serveur est connu et
1391 joignable. En cas d'echec, une exception InvalidArgumentException est
1392 levee. @xref{Classe InvalidArgumentException}. A priori, aucune
1393 verification n'est faite par defaut.
1395 Ceci fait, une connexion est etablie avec le gestionnaire de batch qui
1396 est maintenue jusqu'a destruction de l'objet, si le gestionnaire le permet.
1401 Le destructeur supprime la connexion precedemment etablie par le
1402 constructeur lorsque celle-ci a reussi.
1405 @b{const JobId submitJob(const Job & job)}
1407 Cette methode soumet le job passe en argument au gestionnaire de
1408 batch. Etant donne que le job ne peut pas etre envoye tel quel puisqu'il
1409 a un format generique au sein de la bibliotheque de classes Batch, cette
1410 methode est chargee de le convertir dans un format adapte au
1411 gestionnaire de batch sous-jacent.
1413 Ce n'est que lorsque cette conversion est realisee que le job est soumis
1414 au gestionnaire a travers son API. L'identifiant propose par le
1415 gestionnaire est alors renvoye a l'appelant. Si la soumission echoue
1416 pour une raison ou une autre, une exception APIInternalFailureException est
1417 levee. @xref{Classe APIInternalFailureException}.
1420 @b{void deleteJob(const JobId & jobid)}
1422 Cette methode retire le job dont l'identifiant est passe en argument de
1423 la file d'attente du gestionnaire, ou bien l'arrete s'il est en cours
1424 d'execution. Cette methode est inoperante sur des travaux deja termines,
1425 auquel cas une exception APIInternalFailureException est
1426 levee. @xref{Classe APIInternalFailureException}.
1430 @b{void holdJob(const JobId & jobid)}
1432 Cette methode suspend le job dont l'identifiant est passe en argument au
1433 sein de la file d'attente du gestionnaire. Cette methode est inoperante
1434 sur des travaux en cours d'execution ou deja termines, ainsi que sur des
1435 travaux deja suspendus.
1436 En cas de probleme, une exception APIInternalFailureException est
1437 levee. @xref{Classe APIInternalFailureException}.
1440 @b{void releaseJob(const JobId & jobid)}
1442 Cette methode relache un job precedemment suspendu en file
1443 d'attente dont l'identifiant est passe en argument. Elle est inoperante
1444 sur des travaux deja relaches, en cours d'execution ou termines.
1445 En cas de probleme, une exception APIInternalFailureException est
1446 levee. @xref{Classe APIInternalFailureException}.
1450 @b{void alterJob(const JobId & jobid, const Parametre & param, const Environnement & env)@*
1451 void alterJob(const JobId & jobid, const Parametre & param)@*
1452 void alterJob(const JobId & jobid, const Environnement & env)}
1454 Ces methodes permettent de modifier les parametres d'execution et
1455 d'environnement d'un job dont l'identifiant est passe en
1456 argument. @xref{Classe Parametre}. @xref{Classe Environnement}. Il
1457 est important de noter que le job doit etre encore place en file
1458 d'attente sinon la methode est inoperante.
1459 En cas de probleme, une exception APIInternalFailureException est
1460 levee. @xref{Classe APIInternalFailureException}.
1463 @b{JobInfo queryJob(const JobId & jobid)}
1465 Cette methode permet de recuperer les informations concernant le job
1466 dont l'identifiant est passe en argument dans un objet de classe
1467 @emph{JobInfo}. @xref{Classe JobInfo}. On y retrouve les parametres
1468 d'execution et d'environnement du job tels qu'ils ont ete passes au
1469 gestionnaire au moment de la soumission, ainsi que des informations
1470 concernant l'execution du job comme par exemple la machine d'execution,
1471 le temps consomme, la memoire consommee, etc.
1473 Il n'est pas toujours possible d'interroger un job deja termine.
1474 En cas de probleme, une exception APIInternalFailureException est
1475 levee. @xref{Classe APIInternalFailureException}.
1479 @b{const JobId getJobIdByReference(const string & ref)}
1481 Cette methode permet de recuperer au sein de la classe un identifiant de
1482 job a partir d'une chaine de caracteres obtenue par un biais
1483 externe. Cet identifiant pourra etre utilise par la suite au sein de la
1484 biliotheque de classes pour controler le job comme s'il avait ete cree
1485 et soumis depuis la biliotheque-meme.
1493 @c ----------------------
1494 @c ----------------------
1495 @c ----------------------
1497 @node Classe Environnement, Classe Job, Classe BatchManager, Classes utilisateur
1498 @comment node-name, next, previous, up
1500 @subsubsection Environnement
1501 @findex Environnement
1503 La classe @emph{Environnement} permet de definir les variables
1504 d'environnement necessaires a l'execution d'un job. Ces variables seront
1505 creees automatiquement dans l'environnement du job lorsque celui-ci
1506 debutera son execution sur la machine.
1508 Une variable d'environnement est traditionnellement composee d'un nom et
1509 d'une valeur qui peut etre vide ou absente. L'ensemble des variables
1510 d'environnement peut ainsi etre represente sous la forme d'une table
1511 associative dans laquelle le nom de la variable correspond a la clef de la
1512 table, et la valeur de la variable correspond a la valeur de la table
1513 pour la clef donnee.
1515 Chaque objet de la classe @emph{Environnement} se comporte comme une
1516 table associative telle que decrite auparavant.
1522 typedef map < string, string > Environnement;
1531 env["MYAPP_ROOTDIR"] = "/home/user/myapplication";
1532 env["MYAPP_LICENSEFILE"] = env["MYAPP_ROOTDIR"] + "/license.dat";
1534 env["CXXFLAGS"] = "-g -O2";
1541 Compte tenu de la definition actuelle de la classe @emph{Environnement}
1542 en tant que map STL, elle beneficie de toutes les fonctionnalites
1543 classiques des maps STL.
1548 @c ----------------------
1549 @c ----------------------
1550 @c ----------------------
1552 @node Classe Job, Classe JobId, Classe Environnement, Classes utilisateur
1553 @comment node-name, next, previous, up
1558 La classe @emph{Job} represente la notion de travail, ou job, dans la
1559 bibliotheque de classes Batch. Elle se comporte essentiellement comme
1560 une collection de parametres et de variables necessaires a la
1561 description des actions qui doivent etre realisees dans des conditions
1564 Elle se repose sur deux autres classes qui distinguent la notion de
1565 parametre d'execution et celle de variable d'environnement : les classes
1566 @emph{Parametre} et @emph{Environnement}. @xref{Classe
1567 Parametre}. @xref{Classe Environnement}.
1569 Son role est de preparer la soumission qui aura lieu et qui concretisera
1570 l'incarnation du job dans le gestionnaire de batch. Tant que le job n'a
1571 pas ete soumis, on ne peut pas vraiment considerer son existence et de
1572 fait les interactions qu'on peut avoir avec l'objet sont tres limitees.
1581 // Constructeurs et destructeur
1583 Job(Parametre param);
1584 Job(Environnement env);
1585 Job(Parametre param, Environnement env);
1588 // Operateur pour l'affichage sur un stream
1589 friend ostream & operator <<(ostream & os, const Job & job);
1592 Parametre getParametre() const;
1593 void setParametre(const Parametre &);
1596 Environnement getEnvironnement() const;
1597 void setEnvironnement(const Environnement &);
1599 // Methodes pour l'interfacage avec Python (SWIG)
1600 string __repr__() const;
1603 Parametre _param; // table des parametres batch du job
1604 Environnement _env; // table des variables d'environnement
1616 @dots{} (ici on cree un BatchManager bm)
1620 @dots{} (ici on cree les parametres du job)
1622 Job job(param, env);
1623 JobId jobid = bm.sumbitJob(job);
1633 Job(Parametre param)$*
1634 Job(Environnement env)$*
1635 Job(Parametre param, Environnement env)}
1637 Le constructeur, en plus de creer l'objet, peut faire des verifications
1638 sur la coherence des objets passes en argument s'il y en a.
1643 Le destructeur libere simplement les espaces alloues.
1646 @b{ostream & operator <<(ostream & os, const Job & job)}
1648 Cette methode permet a l'utilisateur d'afficher sur un stream le contenu
1649 d'un objet de classe @emph{Job}.
1652 @b{Parametre getParametre() const}
1654 Un accesseur pour recuperer l'objet Parametre passe en argument du
1658 @b{void setParametre(const Parametre &)}
1660 Cette methode permet de positionner @i{a posteriori} l'objet
1661 @emph{Parametre}. Des tests complementaires peuvent etre faits pour
1662 verifier la coherence de l'objet.
1665 @b{Environnement getEnvironnement() const}
1667 Un accesseur pour recuperer l'objet Environnement passe en argument du constructeur.
1670 @b{void setEnvironnement(const Environnement &)}
1672 Cette methode permet de positionner @i{a posteriori} l'objet
1673 @emph{Environnement}. Des tests complementaires peuvent etre faits pour
1674 verifier la coherence de l'objet.
1677 @b{string __repr__() const}
1679 Cette methode sert dans l'interfacage Python de l'objet et permet d'en
1680 realiser l'affichage a travers l'interpreteur Python.
1685 @c ----------------------
1686 @c ----------------------
1687 @c ----------------------
1689 @node Classe JobId, Classe JobInfo, Classe Job, Classes utilisateur
1690 @comment node-name, next, previous, up
1692 @subsubsection JobId
1695 La classe @emph{JobId} represente l'incarnation d'un objet de classe
1696 @emph{Job} une fois soumis au travers du gestionnaire de batch. A chaque
1697 objet @emph{JobId} correspond une et une seule soumission d'un objet
1698 @emph{Job}. Ainsi un meme objet @emph{Job} peut etre soumis plusieurs
1699 fois de suite a un ou plusieurs gestionnaires de batch et produira
1700 autant d'objets @emph{JobId}.
1702 L'objet @emph{JobId} assure le controle et la gestion du job au travers
1703 du gestionnaire de batch. Chaque objet @emph{JobId} est associe a un
1704 gestionnaire particulier aupres duquel il relaie les actions qu'on lui
1714 friend class BatchManager;
1717 // Constructeur standard et destructeur
1721 // Constructeur avec le pointeur sur le BatchManager associe
1722 // et avec une reference
1723 JobId(BatchManager *, string ref);
1725 // Operateur d'affectation entre objets
1726 virtual JobId & operator =(const JobId &);
1728 // Constructeur par recopie
1729 JobId(const JobId &);
1731 // Accesseur pour la reference interne
1732 virtual string getReference() const;
1734 // Methodes pour le controle du job
1735 // retire un job du gestionnaire
1736 virtual void deleteJob() const;
1738 // suspend un job en file d'attente
1739 virtual void holdJob() const;
1741 // relache un job suspendu
1742 virtual void releaseJob() const;
1744 // modifie un job en file d'attente
1745 virtual void alterJob(const Parametre & param,
1746 const Environnement & env) const;
1747 virtual void alterJob(const Parametre & param) const;
1748 virtual void alterJob(const Environnement & env) const;
1750 // modifie un job en file d'attente
1751 virtual void setParametre(const Parametre & param);
1752 virtual void setEnvironnement(const Environnement & env);
1754 // renvoie l'etat du job
1755 virtual Batch::JobInfo queryJob() const;
1757 // Methodes pour l'interfacage avec Python (SWIG)
1758 string __str__() const; // SWIG : affichage en Python
1759 string __repr__() const; // SWIG : affichage en Python
1762 BatchManager * _p_batchmanager; // pointeur sur le BatchManager
1763 // qui controle le job
1764 string _reference; // reference du job au sein du BatchManager
1774 @dots{} (ici on cree un BatchManager bm et un Job job)
1776 // On soumet le job et on recupere un identifiant
1777 JobId jobid = bm.submitJob(job);
1779 // Ce qui permet d'interroger l'etat du job en cours
1780 JobInfo jinfo = jobid.queryJob();
1790 JobId(BatchManager *, string ref)}
1792 Le constructeur par defaut cree un @emph{JobId} qui devra etre complete
1793 par la suite. Ceci n'est pas directement realisable par l'utilisateur
1794 mais sert pour certaines classes amies de la classe @emph{JobId}.
1796 D'un point de vue utilisateur la construction d'un objet @emph{JobId}
1797 necessite un pointeur sur un gestionnaire de batch existant et une
1798 chaine de caractere representant une reference au sein de ce
1799 gestionnaire de batch.
1801 Ces parametres sont en general issus de la
1802 communication avec l'API du gestionnaire de batch et ne peuvent etre
1803 aisement deduits. C'est pourquoi il est recommande de passer par une
1804 classe d'implementation pour fabriquer un objet @emph{JobId}.
1810 Le destructeur libere l'espace occupe par l'objet.
1813 @b{JobId & operator =(const JobId &)}
1815 L'affectation d'un objet @emph{JobId} duplique les donnees internes de
1816 l'objet passe en argument. Les deux objets sont totalement independants
1817 a l'issue de l'affectation et designent chacun la meme instance du job
1818 dans le meme gestionnaire de batch. Le controle du job peut etre realise
1819 avec l'un ou l'autre des objets.
1822 @b{JobId(const JobId &)}
1824 De meme que l'affectation le constructeur par recopie produit un objet
1825 @emph{JobId} totalement independant de l'objet passe en argument et qui
1826 designe le meme job dans le meme gestionnaire de batch. Le controle du
1827 job peut etre realise avec l'un ou l'autre des objets.
1830 @b{string getReference() const}
1832 Cet accesseur retourne la reference du job pour le gestionnaire de batch
1833 qui a produit l'objet.
1836 @b{void deleteJob() const}
1838 Cette methode relaie aupres au gestionnaire de batch qui a produit
1839 l'objet la demande d'arret du job.
1842 @b{void holdJob() const}
1844 Cette methode relaie aupres au gestionnaire de batch qui a produit
1845 l'objet la demande de suspension du job.
1848 @b{void releaseJob() const}
1850 Cette methode relaie aupres au gestionnaire de batch qui a produit
1851 l'objet la demande de liberation du job.
1854 @b{void alterJob(const Parametre & param, const Environnement & env) const@*
1855 void alterJob(const Parametre & param) const@*
1856 void alterJob(const Environnement & env) const}
1858 Ces methodes relaient aupres du gestionnaire de batch qui a produit
1859 l'objet la demande de modification des parametres et/ou des variables
1860 d'environnement du job.
1863 @b{void setParametre(const Parametre & param)}
1865 Cette methode n'est utile que pour l'interfacage avec Python, car Python
1866 ne sait pas gerer la surcharge de methode, et de fait leve des
1867 exceptions lors d'appels a de telles methodes.
1869 Elle est equivalente a la methode @samp{void alterJob(const Parametre & param) const}.
1873 @b{void setEnvironnement(const Environnement & env)}
1875 Cette methode n'est utile que pour l'interfacage avec Python, car Python
1876 ne sait pas gerer la surcharge de methode, et de fait leve des
1877 exceptions lors d'appels a de telles methodes.
1879 Elle est equivalente a la methode @samp{void alterJob(const Environnement & env) const}.
1882 @b{Batch::JobInfo queryJob() const}
1884 Cette methode relaie aupres du gestionnaire de batch qui a produit
1885 l'objet la demande d'interrogation de l'etat du job.
1888 @b{string __str__() const}
1890 Cette methode n'est utile que pour l'interfacage avec Python. Elle
1891 permet d'afficher l'etat de l'objet @emph{JobId}.
1894 @b{string __repr__() const}
1896 Cette methode n'est utile que pour l'interfacage avec Python. Elle
1897 permet d'afficher l'etat de l'objet @emph{JobId}.
1902 @c ----------------------
1903 @c ----------------------
1904 @c ----------------------
1906 @node Classe JobInfo, Classe Parametre, Classe JobId, Classes utilisateur
1907 @comment node-name, next, previous, up
1909 @subsubsection JobInfo
1912 Un objet de classe @emph{JobInfo} represente l'ensemble des informations
1913 disponibles sur un travail actif, c'est-a-dire soumis au gestionnaire de
1914 batch, a un instant donne.
1916 Cet objet reprend des informations issues du job tel qu'il a ete soumis,
1917 @xref{Classe Job}, mais aussi des informations produites par le
1918 gestionnaire de batch a partir de la soumission et du transit du job en
1919 son sein : nom de la queue dans laquelle le job est inscrit, duree
1920 d'execution, date de soumission, etc.
1922 Ces informations sont disponibles aupres de l'utilisateur de la classe a
1923 travers les objets @emph{Parametre} et @emph{Environnement} que l'objet
1924 @emph{JobInfo} peut fournir.
1933 // Constructeur standard et destructeur
1937 // Constructeur par recopie
1938 JobInfo(const JobInfo & jinfo);
1940 // Operateur pour l'affichage sur un stream
1941 friend ostream & operator <<(ostream & os, const JobInfo & ji);
1944 virtual Parametre getParametre() const;
1945 virtual Environnement getEnvironnement() const;
1947 // Methodes pour l'interfacage avec Python (SWIG)
1948 string __str__() const; // SWIG : affichage en Python
1949 string __repr__() const; // SWIG : affichage en Python
1952 Parametre _param; // parametres du job
1953 Environnement _env; // variables d'environnement du job
1962 @dots{} (ici on cree un BatchManager bm et un Job job)
1964 // On soumet le job et on recupere un identifiant
1965 JobId jobid = bm.submitJob(job);
1967 // Ce qui permet d'interroger l'etat du job en cours
1968 JobInfo jinfo = jobid.queryJob();
1970 // On recupere l'objet Parametre interne modifie
1971 // par le gestionnaire de batch
1972 Parametre param = jinfo.getParametre();
1974 // On recupere l'objet Environnement interne modifie
1975 // par le gestionnaire de batch
1976 Environnement env = jinfo.getEnvironnement();
1986 Ce constructeur cree un objet @emph{JobInfo} vide.
1991 Le destructeur libere l'espace memoire alloue par l'objet.
1994 @b{JobInfo(const JobInfo & jinfo)}
1996 Le constructeur par recopie produit un objet identique a celui passe en
1997 argument. Les deux objets sont totalement independants l'un de l'autre.
2000 @b{ostream & operator <<(ostream & os, const JobInfo & ji)}
2002 Cet operateur permet de voir le contenu de l'objet sur un flot de sortie.
2005 @b{Parametre getParametre() const}
2007 Cet accesseur retourne l'objet interne @emph{Parametre} modifie par le
2008 gestionnaire de batch. En particulier on y retrouve toutes les clefs et
2009 les valeurs correspondant aux informations produites dynamiquement par
2010 le gestionnaire (duree d'execution, machine d'execution, etc.).
2011 Il n'est pas garanti que les valeurs passees au moment de la soumission
2012 soient inchangees car des modifications ont pu etre apportees a ces
2013 valeurs pendant le traitement du job par le gestionnaire.
2016 @b{Environnement getEnvironnement() const}
2018 Cet accesseur retourne l'objet interne @emph{Environnement} modifie par le
2019 gestionnaire de batch. En particulier on y retrouve toutes les clefs et
2020 les valeurs correspondant aux informations produites dynamiquement par
2021 le gestionnaire (chemin d'acces, variables d'environnement specifiques a
2022 la machine d'execution, etc.).
2023 Il n'est pas garanti que les valeurs passees au moment de la soumission
2024 soient inchangees car des modifications ont pu etre apportees a ces
2025 valeurs pendant le traitement du job par le gestionnaire.
2028 @b{string __str__() const}
2030 Cette methode n'est utile que pour l'interfacage avec Python. Elle
2031 permet d'afficher l'etat de l'objet @emph{JobInfo}.
2034 @b{string __repr__() const}
2036 Cette methode n'est utile que pour l'interfacage avec Python. Elle
2037 permet d'afficher l'etat de l'objet @emph{JobInfo}.
2043 @c ----------------------
2044 @c ----------------------
2045 @c ----------------------
2047 @node Classe Parametre, Classe Versatile, Classe JobInfo, Classes utilisateur
2048 @comment node-name, next, previous, up
2050 @subsubsection Parametre
2053 Les objets de la classe @emph{Parametre} se comportent comme des maps
2054 STL, dont ils ont les fonctionnalites, decrivant les parametres
2057 Contrairement aux variables d'environnement qui sont decrites par les
2058 objets de la classe @emph{Environnement}, les parametres d'execution
2059 servent a preciser les contraintes qui pesent sur le job, comme par
2060 exemple la duree maximale d'execution autorisee, la quantite maximale de
2061 memoire utilisable ou la queue de soumission, ou bien a renseigner le
2062 job avec des informations specifiques a l'utilisateur, comme son
2063 username, son adresse email, le code d'imputation du job, etc.
2065 En raison du caractere tres specifique et precis des informations qui
2066 doivent etre fournies au gestionnaire de batch, une nomenclature est
2067 proposee par la classe @emph{Parametre} qu'il est vivement conseille de
2068 suivre. De plus tout a ete fait pour rendre cette ecriture naturelle et
2069 facile, donc il ne devrait pas y avoir de probleme pour l'utiliser.
2071 Ainsi, a titre d'exemple, pour preciser le temps maximal autorise pour
2072 un job, il faut creer une clef de nom @var{maxcputime} dans un objet de
2073 classe @emph{Parametre} qui sera ensuite passe au job. Et pour preciser
2074 le code d'imputation du job, il faut creer une clef de nom @var{account}.
2076 Mais cet exemple simple montre que la valeur associee a la clef
2077 @var{maxcputime} est semantiquement une duree, et que la valeur associee a
2078 la clef @var{account} est semantiquement un nom. On a donc un probleme de
2079 type puisque dans la definition d'une map STL le type de la valeur doit
2080 etre le meme, et ce meme si les valeurs doivent par la suite avoir des
2081 types semantiques differents. C'est pourquoi on a definit une classe
2082 @emph{Versatile} qui encapsule des types differents. @xref{Classe
2085 Quoiqu'il en soit toute la mecanique est cachee et seul importe pour
2086 l'utilisateur de savoir que les valeurs associees aux clefs sont typees
2087 et que ces types sont definis dans l'enumeration @emph{DiscriminatorType}.
2088 @xref{Classe Versatile}.
2095 class Parametre : public map< string, Versatile >
2098 // Constructeur standard
2101 // Constructeur par recopie
2102 Parametre(const Parametre & PM);
2104 // Operateur de recherche dans la map
2105 Versatile & operator [] (const string &);
2106 const Versatile & operator [] (const string &) const;
2108 // Operateur d'affectation
2109 Parametre & operator =(const Parametre & PM);
2111 // Declarations statique des clefs de la map
2112 static const string ACCOUNT;
2113 static const string CHECKPOINT;
2114 static const string CKPTINTERVAL;
2115 static const string CREATIONTIME;
2116 static const string EGROUP;
2117 static const string ELIGIBLETIME;
2118 static const string EUSER;
2119 static const string EXECUTABLE;
2120 static const string EXECUTIONHOST;
2121 static const string HOLD;
2122 static const string ID;
2123 static const string INFILE;
2124 static const string MAIL;
2125 static const string MAXCPUTIME;
2126 static const string MAXDISKSIZE;
2127 static const string MAXRAMSIZE;
2128 static const string MAXWALLTIME;
2129 static const string MODIFICATIONTIME;
2130 static const string NAME;
2131 static const string OUTFILE;
2132 static const string PID;
2133 static const string QUEUE;
2134 static const string QUEUEDTIME;
2135 static const string SERVER;
2136 static const string STARTDATE;
2137 static const string STATE;
2138 static const string TEXT;
2139 static const string TMPDIR;
2140 static const string USEDCPUTIME;
2141 static const string USEDDISKSIZE;
2142 static const string USEDRAMSIZE;
2143 static const string USEDWALLTIME;
2144 static const string USER;
2147 // map interne servant a controler le type
2148 // de la valeur associee a chaque clef
2149 map< string, TypeParam > TypeMap;
2163 param[EXECUTABLE] = "/home/user/mon_application/executable";
2164 param[NAME] = "MonJob";
2165 param[ACCOUNT] = "MonProjet"; // code d'imputation/facturation
2166 param[MAXCPUTIME] = 360L; // 6min
2167 param[MAXWALLTIME] = 480L; // 8min
2168 param[INFILE] = Couple("/tmp/infich1", rempath + "/infich1");
2169 param[OUTFILE] = Couple("/tmp/outfich1", rempath + "/outfich1");
2170 param[OUTFILE] += Couple("stderr", path + "/STDERR");
2171 param[OUTFILE] += Couple("stdout", path + "/STDOUT");
2172 param[MAIL] = "user@@domaine.fr";
2173 param[USER] = "user";
2184 Le constructeur par defaut initialise l'objet @emph{Parametre} et cree
2185 la table des types internes. Par contre l'objet ne contient aucune valeur.
2188 @b{Parametre(const Parametre & PM)}
2190 Le constructeur par recopie cree un objet @emph{Parametre} a l'image de
2191 celui qui lui est passe en argument. La table des types internes est
2192 dupliquee ainsi que tous les objets correspondant a chacune des clefs.
2195 @b{Versatile & operator [] (const string &)}
2197 Cet operateur permet de recuperer la valeur designee par la clef passee
2198 en argument. Cette valeur est de classe @emph{Versatile} qui encapsule
2199 tous les types de base utilisables dans la bibliotheque en tant que
2200 parametre. @xref{Classe Versatile}.
2204 @b{const Versatile & operator [] (const string &) const}
2206 A l'image de l'operateur precedent, cet operateur permet de recuperer la
2207 valeur designee par la clef passee en argument mais uniquement pour des
2211 @b{Parametre & operator =(const Parametre & PM)}
2213 L'operateur d'affectation remplace l'ensemble du contenu de l'objet
2214 @emph{Parametre} par le contenu de l'objet passe en argument. Les
2215 valeurs sont dupliquees par rapport a l'objet @var{pm}.
2219 @item Description des clefs
2221 Selon les gestionnaires de batch utilises, certaines clefs sont actives
2222 ou inactives. Une definition superflue ne pose pas de probleme et se
2223 trouve ignoree au moment de la soumission. Par contre l'absence d'un
2224 clef peut empecher la soumission d'aboutir et lever une exception.
2227 @item ACCOUNT : type STRING
2229 Le code de facturation sur lequel le job doit s'imputer.
2231 @item CHECKPOINT : type LONG
2233 Une valeur non nulle indique au gestionnaire de batch que le job est
2234 @dfn{checkpointable}, c'est-a-dire interruptible pour une reprise
2237 @item CKPTINTERVAL : type LONG
2239 En liaison avec la clef @var{CHECKPOINT}, la clef @var{CKPTINTERVAL}
2240 indique l'intervalle en secondes entre deux interruptions du code
2243 @item CREATIONTIME : type LONG
2245 La date a laquelle le job a ete cree (soumis) dans le gestionnaire de batch.
2247 @item EGROUP : type STRING
2249 Le groupe effectif au sens Unix du terme dans lequel le job s'execute.
2251 @item ELIGIBLETIME : type LONG
2253 La date a laquelle le job a pu disposer des ressources necessaires a son
2256 @item EUSER : type STRING
2258 L'utilisateur effectif au sens Unix du terme pour lequel le job s'execute.
2260 @item EXECUTABLE : type STRING
2262 Le chemin d'acces absolu a l'executable sur la machine qui soumet le job.
2264 @item EXECUTIONHOST : type STRING
2266 Le nom de la machine qui execute le job.
2268 @item HOLD : type LONG
2270 Une valeur non nulle indique au gestionnaire de batch que le job doit
2271 etre place dans l'etat suspendu. Une valeur nulle libere le job.
2273 @item ID : type STRING
2275 L'identifiant unique du job pour le gestionnaire de batch.
2277 @item INFILE : type liste de COUPLE
2279 La clef @var{infile} liste les fichiers qui seront envoyes au job avant
2280 son execution. Chaque fichier peut avoir un nom different sur la machine
2281 cliente --- qui soumet le job --- et sur le serveur. C'est pourquoi
2282 chaque fichier a envoyer est represente par un couple dont le nom @var{local}
2283 est le chemin absolu du fichier sur la machine cliente et le nom
2284 @var{remote} est le chemin absolu du fichier sur le
2285 serveur. @xref{Classe Couple}.
2287 Si le nom @var{remote} vaut @samp{stdin}, alors le contenu du fichier
2288 designe par le nom @var{local} est envoye sur l'entree standard du job
2289 au moment de son execution.
2291 @item MAIL : type STRING
2293 L'adresse email de l'utilisateur ou lui seront envoyes les eventuels
2294 messages d'information et d'alerte du gestionnaire de batch.
2296 @item MAXCPUTIME : type LONG
2298 Le temps de calcul (@i{CPU time}) en secondes que ne devra pas depasser le job.
2300 @item MAXDISKSIZE : type LONG
2302 L'espace disque en octets que ne devra pas depasser le job.
2304 @item MAXRAMSIZE : type LONG
2306 La quantite de memoire vive en octets que ne devra pas depasser le job.
2308 @item MAXWALLTIME : type LONG
2310 Le temps reel (@i{elapsed time}) en secondes que ne devra pas depasser le job.
2312 @item MODIFICATIONTIME : type LONG
2314 La date a laquelle le job a ete modifie pour la derniere fois dans le
2315 gestionnaire de batch. Cette date correspond le plus souvent a la
2316 derniere operation realisee par le gestionnaire dans la gestion du job :
2317 routage au sein des files, suspension ou reprise, etc.
2319 @item NAME : type STRING
2321 Le nom du job tel qu'il apparait a l'utilisateur dans son dialogue avec
2322 le gestionnaire de batch. Ce nom n'a pas besoin d'etre unique et ne
2323 remplace pas l'identifiant (ID). Il n'est la que pour informer
2324 l'utilisateur de la nature de son job.
2326 @item OUTFILE : type liste de COUPLE
2328 La clef @var{outfile} liste les fichiers qui sont produits par le job et
2329 qui seront recuperes sur la machine locale de l'utilisateur apres
2330 son execution. Chaque fichier peut avoir un nom different sur la machine
2331 cliente --- qui soumet le job --- et sur le serveur. C'est pourquoi
2332 chaque fichier a recuperer est represente par un couple dont le nom @var{local}
2333 est le chemin absolu du fichier sur la machine cliente et le nom
2334 @var{remote} est le chemin absolu du fichier sur le
2335 serveur. @xref{Classe Couple}.
2337 Si le nom @var{local} vaut @samp{stdout}, alors le contenu du fichier
2338 designe par le nom @var{local} contient la sortie standard du job
2339 au moment de son execution.
2341 Si le nom @var{local} vaut @samp{stderr}, alors le contenu du fichier
2342 designe par le nom @var{local} contient la sortie d'erreur du job
2343 au moment de son execution.
2345 @item PID : type LONG
2347 La valeur du PID (@i{process identifier}) du job sur la machine sur
2348 lqsuelle il s'execute.
2350 @item QUEUE : type STRING
2352 Le nom de la queue, aussi appelee classe ou file suivant les
2353 terminologies, qui accueille le job.
2355 @item QUEUEDTIME : type LONG
2357 La date depuis laquelle le job a ete place en queue dans le gestionnaire
2360 @item SERVER : type STRING
2362 Le nom complet du serveur qui recoit les soumissions de job.
2364 @item STARTDATE : type LONG
2366 La date a partir de laquelle l'utilisateur desire que le job soit
2367 execute. L'execution ne demarrera qu'au dela de cette date et a
2368 condition que toutes les conditions de ressources soient remplies.
2370 @item STATE : type STRING
2372 L'etat actuel du job.
2374 ATTENTION : Ces valeurs ne sont pas encore normalisees.
2376 @item TEXT : type STRING
2378 Un texte d'information que le gestionnaire peut emettre a destination de
2379 l'utilisateur lorsque l'ensemble des parametres n'est pas suffisant pour
2380 traduire l'etat reel du job. Par exemple, ce message peut informer
2381 l'utilisateur de la raison qui maintient un job dans un etat suspendu ou
2382 qui l'empeche de s'executer.
2384 @item TMPDIR : type STRING
2386 Un chemin d'acces absolu a un repertoire qui sera cree au demarrage du
2387 job et qui isolera le job des autres travaux en cours d'execution sur la
2390 @item USEDCPUTIME : type LONG
2392 Le temps de calcul (@i{CPU time}) en secondes reellement consomme par le job.
2394 @item USEDDISKSIZE : type LONG
2396 L'espace disque en octets reellement consomme par le job.
2398 @item USEDRAMSIZE : type LONG
2400 L'espace disque en octets reellement consommee par le job.
2402 @item USEDWALLTIME : type LONG
2404 Le temps reel (@i{elapsed time}) en secondes reellement consomme par le job.
2406 @item USER : type STRING
2408 Le nom de l'utilisateur (@i{username}) sous lequel le job devra tourner
2409 sur la machine d'execution. Ce parametre est utile lorsque l'utilisateur
2410 possede des comptes differents sur les machines sur lequel il soumet et calcule.
2417 @c ----------------------
2418 @c ----------------------
2419 @c ----------------------
2421 @node Classe Versatile, Exceptions, Classe Parametre, Classes utilisateur
2422 @comment node-name, next, previous, up
2424 @subsubsection Versatile
2427 Cette classe est normalement invisible en tant que telle a l'utilsateur
2428 de la bibliotheque de classes Batch. Mais il est tout de meme utile de
2429 la presenter car son action est visible, notamment dans son interaction
2430 fine avec la classe @emph{Parametre}. @xref{Classe Parametre}.
2432 Comme il a ete precise dans la descrption de la classe @emph{Parametre},
2433 la classe @emph{Versatile} a ete concue pour encapsuler les valeurs de
2434 la map @emph{Parametre} qui peuvent etre de types effectifs differents.
2436 Ces types, decrits par l'enumeration @emph{DiscriminatorType}, sont
2437 actuellement au nombre de trois : @var{long}, @var{string} et
2438 @var{couple}. Ces types correpondent au types de base du langage C++ ou
2439 de la biliotheque de classes Batch. @xref{Types de base}.
2441 Le type special @var{undefined} ne sert que pour l'objet
2442 @emph{Versatile} juste cree mais non encore affecte d'une valeur et donc
2443 d'un type. La premiere affection d'une valeur a un objet
2444 @emph{Versatile} non encore affecte lui donne automatiquement le type de
2447 Les objets de classe @emph{Versatile} peuvent se comporter soit comme
2448 des variables scalaires, c'est-a-dire ne contenant qu'une valeur unique,
2449 soit comme des listes, auquel cas elles utilisent l'interface des
2450 @emph{list} de la STL. Toutefois afin de faciliter l'ecriture pour
2451 l'utilisateur basique de la classe @emph{Versatile} --- et de la classe
2452 @emph{Parametre} ---, des operateurs de concatenation @samp{+=} et
2453 @samp{,} ont ete ajoutes.
2460 // Les types autorises
2461 enum DiscriminatorType @{ UNDEFINED, LONG, STRING, COUPLE @};
2464 DiscriminatorType type; // le type de l'element interne
2465 int maxelem; // le nombre d'elements autorises
2468 class Versatile : public list< GenericType * >
2471 // Constructeur standard et destructeur
2473 virtual ~Versatile();
2475 // Constructeur par recopie
2476 Versatile(const Versatile & V);
2478 // Constructeur depuis le type de "base"
2480 Versatile(const string & s);
2481 Versatile(const Couple & c);
2483 // Operateur d'affectation et de concatenation
2484 // a partir d'un type de "base"
2485 Versatile & operator = (const long l)
2486 throw(TypeMismatchException);
2487 Versatile & operator = (const string & ch)
2488 throw(TypeMismatchException);
2489 Versatile & operator +=(const string & ch)
2490 throw(TypeMismatchException,ListIsFullException);
2491 Versatile & operator , (const string & ch)
2492 throw(TypeMismatchException,ListIsFullException);
2493 Versatile & operator = (const Couple & cp)
2494 throw(TypeMismatchException);
2495 Versatile & operator +=(const Couple & cp)
2496 throw(TypeMismatchException,ListIsFullException);
2497 Versatile & operator , (const Couple & cp)
2498 throw(TypeMismatchException,ListIsFullException);
2500 // Operateur d'affectation entre objets
2501 Versatile & operator = (const Versatile & V)
2502 throw(TypeMismatchException);
2504 // Conversion de type vers un type de "base"
2505 operator long() const throw(TypeMismatchException);
2506 operator string() const throw(TypeMismatchException);
2507 operator Couple() const throw(TypeMismatchException);
2508 string str() const throw(TypeMismatchException);
2510 // Operateur pour l'affichage sur un stream
2511 friend ostream & operator << (ostream & os, const Versatile & );
2513 // Positionnement et recuperation du type de l'element interne
2514 void setType(DiscriminatorType) throw(TypeMismatchException);
2515 DiscriminatorType getType() const;
2517 // Positionnement et recuperation du nombre d'elements internes
2518 void setMaxSize(int i);
2519 int getMaxSize() const;
2521 // Positionnement et recuperation du nom de l'objet
2522 string getName() const;
2523 void setName(const string & name);
2526 // Efface tous les elements internes de l'objet
2527 virtual void eraseAll();
2529 DiscriminatorType _discriminator; // type de l'element interne
2530 int _maxsize; // nombre max d'elements internes
2531 string _name; // nom de l'objet (sert pour les exceptions)
2543 // On cree un objet Versatile non encore affecte (scalaire)
2546 // L'affectation d'un long lui donne le type LONG
2547 Vlong = 1024L * 1024L * 1024L;
2548 cout << "Versatile long (must be 1073741824) : " << Vlong << endl;
2550 // On cree un objet Versatile non encore affecte (scalaire)
2553 // L'affectation d'une string (const char * promu en string)
2554 // lui donne le type STRING
2555 Vstring = "UneChaine";
2556 cout << "Versatile string (must be UneChaine) : " << Vstring << endl;
2560 // L'affectation d'un autre type leve une exception.
2561 // Il n'y a pas de retypage dynamique.
2563 cout << "ERR : No TypeMismatchException catched for Versatile long"
2566 catch (TypeMismatchException & ex)
2568 cout << "OK : TypeMismatchException catched for Versatile long"
2572 // Reaffectation avec le meme type
2573 Vlong = 1024L * 1024L;
2574 cout << "Versatile long (must be 1048576) : " << Vlong << endl;
2576 // On cree un objet Versatile non encore affecte (scalaire) ...
2579 // ... que l'on transforme en liste (non limitee)
2580 Vcat1.setMaxSize(0);
2582 // On affecte la premiere valeur ...
2585 // ... puis les suivantes par concatenation
2590 cout << "Versatile string concatenation (must be A B C D E) : "
2593 // Idem que pour Vcat1, mais avec une limite a 5 elements dans la liste
2595 Vcat2.setMaxSize(5);
2596 Vcat2 = "a", "b", "c", "d", "e";
2597 cout << "Versatile string concatenation (must be a b c d e) : "
2600 // On tronque les 2 derniers elements de la liste (il en reste 3)
2601 Vcat2.setMaxSize(3);
2602 cout << "Versatile string concatenation (must be a b c) : "
2606 Versatile Vcopy2(Vcat2);
2607 cout << "Versatile copy (must be a b c) : " << Vcopy2 << endl;
2611 cout << "Versatile affect (must be A B C D E) : " << Vaffect << endl;
2613 cout << "Versatile affect (must be a b c) : " << Vaffect << endl;
2617 // Retypage dynamique interdit
2619 cout << "ERR : No TypeMismatchException catched for Versatile"
2622 catch (TypeMismatchException & ex)
2624 cout << "OK : TypeMismatchException catched for Versatile string"
2630 // Concatenation au dela de la limite interdit
2632 cout << "ERR : No ListIsFullException catched for Versatile string"
2635 catch (ListIsFullException & ex)
2637 cout << "OK : ListIsFullException catched for Versatile string"
2641 // Les objets Versatile se comportent (presque) comme des objets
2642 // standards du langage
2644 cout << "Long value of Versatile long (must be 1048576) : "
2648 cout << "String value of Versatile (must be EncoreUneAutreChaine):"
2659 Le constructeur par defaut fabrique un objet scalaire de type
2660 @var{undefined} et de nom @samp{undefined}.
2665 Le destructeur efface tout le contenu de l'objet si celui-ci avait ete affecte.
2668 @b{Versatile(const Versatile & V)}
2670 Le constructeur par recopie duplique l'objet passe en argument ainsi que
2671 les valeurs qu'il contient. Le nouvel objet est totalement independant
2675 @b{Versatile(long l)@*
2676 Versatile(const string & s)@*
2677 Versatile(const Couple & c)}
2679 Ces constructeurs fabriquent des objets scalaires @emph{Versatile} a partir des
2680 types de base passes en argument. Chaque objet acquerera definitivement
2681 le type correspondant au type de base : @var{long} pour @samp{long},
2682 @var{string} pour @samp{string} et @var{couple} pour @samp{Couple}.
2685 @b{Versatile & operator = (const long l) throw(TypeMismatchException)@*
2686 Versatile & operator = (const string & ch) throw(TypeMismatchException)@*
2687 Versatile & operator = (const Couple & cp) throw(TypeMismatchException)}
2689 Ces operateurs affectent ou reaffectent la valeur passee en argument a
2690 l'objet. Le type de la valeur doit correspondre au type de l'objet si
2691 celui-ci a deja ete affecte, sinon une exception @emph{TypeMismatchException} est
2692 levee. @xref{Classe TypeMismatchException}.
2694 L'ancienne valeur de l'objet est perdue.
2697 @b{Versatile & operator += (const string & ch)
2698 throw(TypeMismatchException, ListIsFullException)@*
2699 Versatile & operator , (const string & ch)
2700 throw(TypeMismatchException, ListIsFullException)@*
2701 Versatile & operator += (const Couple & cp)
2702 throw(TypeMismatchException, ListIsFullException)@*
2703 Versatile & operator , (const Couple & cp)
2704 throw(TypeMismatchException, ListIsFullException)}
2706 Ces operateurs concatenent la valeur passee en argument a l'objet. Le
2707 type de la valeur doit correspondre au type interne de l'objet si
2708 celui-ci a deja ete affecte, sinon une exception @emph{TypeMismatchException} est
2709 levee. @xref{Classe TypeMismatchException}.
2711 Si la taille maximale de la liste est depasse, une exception @emph{ListIsFullException} est
2712 levee. @xref{Classe ListIsFullException}.
2715 @b{Versatile & operator = (const Versatile & V) throw(TypeMismatchException)}
2717 L'operateur d'affectation duplique l'objet passe en argument dans
2718 l'objet. Toutes les valeurs internes sont dupliquees de maniere a avoir
2719 une independance totale entre les deux objets a l'issue de
2722 Il est a noter qu'il est possible d'affecter a un objet un objet
2723 possedant un type different, auquel cas l'objet courant change de type
2724 pour acquerir celui de l'objet passe en argument. C'est le seul cas de
2725 changement de type autorise pour un objet.
2728 @b{operator long() const throw(TypeMismatchException)@*
2729 operator string() const throw(TypeMismatchException)@*
2730 operator Couple() const throw(TypeMismatchException)@*
2731 string str() const throw(TypeMismatchException)}
2733 Ces operateur de conversion dans les types de base permettent de
2734 recuperer la valeur interne de l'objet. Lorsque le type interne est
2735 incompatible avec la conversion une exception @emph{TypeMismatchException} est
2736 levee. @xref{Classe TypeMismatchException}.
2739 @b{ostream & operator << (ostream & os, const Versatile & )}
2741 Cet operateur permet de voir le contenu de l'objet sur un flot de sortie.
2744 @b{void setType(DiscriminatorType) throw(TypeMismatchException)}
2746 Cette methode change le type interne de l'objet en celui passe en
2747 argument. Ceci n'est possible que pour un objet non encore affecte. Si
2748 le nouveau type est different du type actuel une exception @emph{TypeMismatchException} est
2749 levee. @xref{Classe TypeMismatchException}.
2752 @b{DiscriminatorType getType() const}
2754 Cet accesseur renvoie le type interne de l'objet.
2757 @b{void setMaxSize(int i)}
2759 Cette methode permet de changer le nombre d'elements que l'objet est
2760 capable de stocker. Par defaut ce nombre est 1 a la construction de
2761 l'objet, signifiant qu'il ne peut contenir qu'une seule valeur a la fois
2764 Si ce nombre est superieur a 1 alors il represente une
2765 limite qui ne pourra etre depassee par l'objet sans lever d'exception
2766 @emph{ListIsFullException}. @xref{Classe ListIsFullException}.
2768 Si ce nombre vaut 0 (zero) alors il n'y a aucune limite superieure au
2769 nombre d'element dans l'objet.
2772 @b{int getMaxSize() const}
2774 Cet accesseur renvoie la taille maximale admise par l'objet.
2777 @b{void setName(const string & name)}
2779 Cette methode permet de positionner le nom de l'objet. Par defaut ce nom
2780 vaut @samp{undefined} a la construction de l'objet.
2782 Il est interessant de positionner le nom a une valeur significative
2783 comme par exemple le nom de la variable contenant l'objet car lorsqu'une
2784 exception est levee ce nom apparait en clair et aide au debugging.
2787 @b{string getName() const}
2789 Cet accesseur renvoie le nom interne de l'objet.
2797 @c ----------------------
2798 @c ----------------------
2799 @c ----------------------
2801 @node Exceptions, Classe APIInternalFailureException, Classe Versatile, Classes generiques
2802 @comment node-name, next, previous, up
2804 @subsection Exceptions
2807 La bibliotheque de classes Batch definit un certain nombre d'exceptions
2808 qui sont levees par les classes lors d'evenements qui traduisent un
2809 comportement anormal de la bibliotheque.
2812 * Classe APIInternalFailureException:: Erreur d'utilisation de l'API.
2813 * Classe ConnexionFailureException:: Probleme de connexion de l'API.
2814 * Classe GenericException:: Classe-mere de toutes les exceptions.
2815 * Classe InvalidArgumentException:: Parametre errone d'une methode.
2816 * Classe InvalidKeyException:: Clef erronee d'une map.
2817 * Classe ListIsFullException:: Debordement de taille d'une liste.
2818 * Classe NotYetImplementedException:: Methodes non encore implementee.
2819 * Classe RunTimeException:: Erreur d'execution imprevue.
2820 * Classe TypeMismatchException:: Probleme de conversion de type.
2824 @c ----------------------
2825 @c ----------------------
2826 @c ----------------------
2828 @node Classe APIInternalFailureException, Classe ConnexionFailureException, Exceptions, Exceptions
2829 @comment node-name, next, previous, up
2831 @subsubsection APIInternalFailureException
2832 @findex APIInternalFailureException
2834 Cette exception est levee par les classes d'implementation de la
2835 bibliotheque lorsqu'une erreur est detectee au moment de la
2836 communication avec l'API du gestionnaire de batch. En general l'erreur
2837 renvoyee par l'API est incluse dans le message de l'exception.
2839 Cette exception herite de la classe @emph{GenericException} qui definit
2840 uniquement un constructeur et deux membres publics constants : @emph{type} et
2841 @emph{message}. @xref{Classe GenericException}.
2847 class APIInternalFailureException : public GenericException
2851 APIInternalFailureException(string msg = "undefined");
2859 @b{APIInternalFailureException(string msg = "undefined")}
2861 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
2862 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
2863 membre public constant @emph{message}.
2865 Le membre public constant @emph{type} est initialise avec le nom de la
2866 classe, soit @emph{APIInternalFailureException}.
2873 @c ----------------------
2874 @c ----------------------
2875 @c ----------------------
2877 @node Classe ConnexionFailureException, Classe GenericException, Classe APIInternalFailureException, Exceptions
2878 @comment node-name, next, previous, up
2880 @subsubsection ConnexionFailureException
2881 @findex ConnexionFailureException
2883 Cette exception est levee par les classes d'implementation de la
2884 bibliotheque lorsqu'une erreur est detectee au moment de la
2885 connexion au gestionnaire de batch. En general l'erreur
2886 renvoyee par l'API de connexion est incluse dans le message de l'exception.
2888 Cette exception herite de la classe @emph{GenericException} qui definit
2889 uniquement un constructeur et deux membres publics constants : @emph{type} et
2890 @emph{message}. @xref{Classe GenericException}.
2896 class ConnexionFailureException : public GenericException
2900 ConnexionFailureException(string msg = "undefined");
2908 @b{ConnexionFailureException(string msg = "undefined")}
2910 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
2911 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
2912 membre public constant @emph{message}.
2914 Le membre public constant @emph{type} est initialise avec le nom de la
2915 classe, soit @emph{ConnexionFailureException}.
2921 @c ----------------------
2922 @c ----------------------
2923 @c ----------------------
2925 @node Classe GenericException, Classe InvalidArgumentException, Classe ConnexionFailureException, Exceptions
2926 @comment node-name, next, previous, up
2928 @subsubsection GenericException
2929 @findex GenericException
2931 Cette classe est generique comme son nom l'indique et definit une
2932 interface commune pour toutes les exceptions de la
2935 Cette exception definit uniquement un constructeur et deux membres
2936 publics constants : @emph{type} et @emph{message}. @xref{Classe
2944 class GenericException
2947 const string type; // la nature de l'exception
2948 const string message; // la raison de l'exception
2951 GenericException(const string tp = "GenericException",
2952 const string msg = "undefined");
2960 @b{GenericException(const string tp = "GenericException", const string msg = "undefined")}
2962 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
2963 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
2964 membre public constant @emph{message}.
2966 Le membre public constant @emph{type} est initialise avec le parametre
2967 @emph{tp} qui contient generalement le nom de la classe.
2974 @c ----------------------
2975 @c ----------------------
2976 @c ----------------------
2978 @node Classe InvalidArgumentException, Classe InvalidKeyException, Classe GenericException, Exceptions
2979 @comment node-name, next, previous, up
2981 @subsubsection InvalidArgumentException
2982 @findex InvalidArgumentException
2984 Cette exception est levee par les classes de la bibliotheque lorsqu'un
2985 parametre erronne est passe en argument a une methode. En general
2986 le nom de l'arguement erronne est inclus dans le message de
2989 Cette exception herite de la classe @emph{GenericException} qui definit
2990 uniquement un constructeur et deux membres publics constants : @emph{type} et
2991 @emph{message}. @xref{Classe GenericException}.
2997 class InvalidArgumentException : public GenericException
3001 InvalidArgumentException(string msg = "undefined");
3009 @b{InvalidArgumentException(string msg = "undefined")}
3011 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
3012 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
3013 membre public constant @emph{message}.
3015 Le membre public constant @emph{type} est initialise avec le nom de la
3016 classe, soit @emph{InvalidArgumentException}.
3023 @c ----------------------
3024 @c ----------------------
3025 @c ----------------------
3027 @node Classe InvalidKeyException, Classe ListIsFullException, Classe InvalidArgumentException, Exceptions
3028 @comment node-name, next, previous, up
3030 @subsubsection InvalidKeyException
3031 @findex InvalidKeyException
3034 Cette exception est levee par les methodes de la classe @emph{Parametre}
3035 lorsqu'une clef erronnee est utilisee. En general le nom de la clef
3036 erronnee est inclus dans le message de l'exception.
3038 Cette exception herite de la classe @emph{GenericException} qui definit
3039 uniquement un constructeur et deux membres publics constants : @emph{type} et
3040 @emph{message}. @xref{Classe GenericException}.
3046 class InvalidKeyException : public GenericException
3050 InvalidKeyException(string msg = "undefined");
3058 @b{InvalidKeyException(string msg = "undefined")}
3060 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
3061 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
3062 membre public constant @emph{message}.
3064 Le membre public constant @emph{type} est initialise avec le nom de la
3065 classe, soit @emph{InvalidKeyException}.
3072 @c ----------------------
3073 @c ----------------------
3074 @c ----------------------
3076 @node Classe ListIsFullException, Classe NotYetImplementedException, Classe InvalidKeyException, Exceptions
3077 @comment node-name, next, previous, up
3079 @subsubsection ListIsFullException
3080 @findex ListIsFullException
3082 Cette exception est levee par les methodes de la classe @emph{Versatile}
3083 lorsque la taille maximale de la liste interne est depasse. En general
3084 le nom de l'objet en erreur est inclus dans le message de l'exception.
3086 Cette exception herite de la classe @emph{GenericException} qui definit
3087 uniquement un constructeur et deux membres publics constants : @emph{type} et
3088 @emph{message}. @xref{Classe GenericException}.
3094 class ListIsFullException : public GenericException
3098 ListIsFullException(string msg = "undefined");
3106 @b{ListIsFullException(string msg = "undefined")}
3108 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
3109 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
3110 membre public constant @emph{message}.
3112 Le membre public constant @emph{type} est initialise avec le nom de la
3113 classe, soit @emph{ListIsFullException}.
3121 @c ----------------------
3122 @c ----------------------
3123 @c ----------------------
3125 @node Classe NotYetImplementedException, Classe RunTimeException, Classe ListIsFullException, Exceptions
3126 @comment node-name, next, previous, up
3128 @subsubsection NotYetImplementedException
3129 @findex NotYetImplementedException
3131 Cette exception est levee par les classes de la bibliotheque lorsqu'une
3132 methode declaree mais non encore implementee est utilisee. En general
3133 le nom de l'objet en erreur est inclus dans le message de l'exception.
3135 Cette exception herite de la classe @emph{GenericException} qui definit
3136 uniquement un constructeur et deux membres publics constants : @emph{type} et
3137 @emph{message}. @xref{Classe GenericException}.
3143 class NotYetImplementedException : public GenericException
3147 NotYetImplementedException(string msg = "undefined");
3155 @b{NotYetImplementedException(string msg = "undefined")}
3157 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
3158 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
3159 membre public constant @emph{message}.
3161 Le membre public constant @emph{type} est initialise avec le nom de la
3162 classe, soit @emph{NotYetImplementedException}.
3170 @c ----------------------
3171 @c ----------------------
3172 @c ----------------------
3174 @node Classe RunTimeException, Classe TypeMismatchException, Classe NotYetImplementedException, Exceptions
3175 @comment node-name, next, previous, up
3177 @subsubsection RunTimeException
3178 @findex RunTimeException
3180 Cette exception est levee par les classes de la bibliotheque lorsqu'une
3181 erreur inconnue et imprevue apparait. Cette exception est le
3182 comportement par defaut que doit gerer le gestionnaire d'exception en ce
3183 qui concerne les classes de la bibliotheque. En general le nom de
3184 l'objet en erreur est inclus dans le message de l'exception.
3186 Cette exception herite de la classe @emph{GenericException} qui definit
3187 uniquement un constructeur et deux membres publics constants : @emph{type} et
3188 @emph{message}. @xref{Classe GenericException}.
3194 class RunTimeException : public GenericException
3198 RunTimeException(string msg = "undefined");
3206 @b{RunTimeException(string msg = "undefined")}
3208 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
3209 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
3210 membre public constant @emph{message}.
3212 Le membre public constant @emph{type} est initialise avec le nom de la
3213 classe, soit @emph{RunTimeException}.
3221 @c ----------------------
3222 @c ----------------------
3223 @c ----------------------
3225 @node Classe TypeMismatchException, Classes specifiques, Classe RunTimeException, Exceptions
3226 @comment node-name, next, previous, up
3228 @subsubsection TypeMismatchException
3229 @findex TypeMismatchException
3231 Cette exception est levee par les methodes de la classe @emph{Versatile}
3232 lorsque qu'une erreur de type est rencontree dans un objet. Ce genre
3233 d'erreur survient lorsqu'on essaie d'affecter une valeur d'un type
3234 different du type interne de l'objet @emph{Versatile} a ce meme objet,
3235 ou bien lorsqu'on ajoute une valeur d'un type different a une liste. En
3236 general le nom de l'objet en erreur est inclus dans le message de
3239 Cette exception herite de la classe @emph{GenericException} qui definit
3240 uniquement un constructeur et deux membres publics constants : @emph{type} et
3241 @emph{message}. @xref{Classe GenericException}.
3247 class TypeMismatchException : public GenericException
3251 TypeMismatchException(string msg = "undefined");
3259 @b{TypeMismatchException(string msg = "undefined")}
3261 Ce contructeur prend la chaine @emph{msg} comme message d'erreur a
3262 renvoyer au gestionnaire d'exception. Cette valeur est stockee dans le
3263 membre public constant @emph{message}.
3265 Le membre public constant @emph{type} est initialise avec le nom de la
3266 classe, soit @emph{TypeMismatchException}.
3275 @c ----------------------
3276 @c ----------------------
3277 @c ----------------------
3279 @node Classes specifiques, Classes PBS, Classe TypeMismatchException, Classes
3280 @comment node-name, next, previous, up
3282 @section Classes specifiques
3283 @cindex classes specifiques
3285 Afin de pouvoir se connecter aux gestionnaires de batch reels a travers
3286 leurs API, les classes generiques ont ete derivees pour offrir une
3287 implementation correspondant a l'interface qu'elles definissent.
3289 Pour traduire a la fois le fait que les nouvelles classes derivent d'une
3290 classe generique et qu'elles sont une implementation d'une API
3291 particuliere, on adopte la convention de nom suivante : la classe se
3292 nomme comme sa classe generique mais est suffixee par le nom de l'API du
3293 gestionnaire de batch, les deux termes etant separes par un caractere
3296 Actuellement, seul le gestionnaire de batch OpenPBS, @xref{Prerequis}, est
3297 supporte. Mais ce catalogue devrait s'enrichir par la suite.
3299 Les classes de la bibliotheque sont egalement accessibles a travers un
3300 interpreteur Python, ce qui a necessite la creation de certaines classes
3301 d'interface avec l'interpreteur.
3304 * Classes PBS:: Classes d'implementation pour OpenPBS
3305 * Classes Python:: Classes d'interfacage avec Python.
3308 @c ----------------------
3309 @c ----------------------
3310 @c ----------------------
3312 @node Classes PBS, Classe FactBatchManager_PBS, Classes specifiques, Classes specifiques
3313 @comment node-name, next, previous, up
3315 @subsection Classes PBS
3318 Actuellement seules les classes @emph{BatchManager}, @emph{JobInfo} et
3319 @emph{Job} ont besoin d'etre derivees pour implementer la communication
3320 et l'interfacage avec l'API du gestionnaire de batch OpenPBS.
3324 * Classe FactBatchManager_PBS:: Description de la classe FactBatchManager_PBS.
3325 * Classe BatchManager_PBS:: Description de la classe BatchManager_PBS.
3326 * Classe JobInfo_PBS:: Description de la classe JobInfo_PBS.
3327 * Classe Job_PBS:: Description de la classe Job_PBS.
3331 @node Classe FactBatchManager_PBS, Classe BatchManager_PBS, Classes PBS, Classes PBS
3332 @comment node-name, next, previous, up
3333 @subsubsection FactBatchManager_PBS
3334 @cindex FactBatchManager_PBS
3336 Cette classe derive de la classe generique @emph{FactBatchManager},
3337 @xref{Classe FactBatchManager}.
3339 Les objets de la classe @emph{BatchManager_PBS} realisent l'interface de
3340 la bibliotheque avec l'API du gestionnaire de batch OpenPBS.
3346 class FactBatchManager_PBS : public FactBatchManager
3349 // Constructeur et destructeur
3350 FactBatchManager_PBS();
3351 virtual ~FactBatchManager_PBS();
3353 virtual BatchManager_PBS * operator() (const char * hostname) const;
3367 // On recupere l'instance du catalogue de gestionnaires de batch
3368 Batch::BatchManagerCatalog cata = Batch::BatchManagerCatalog::getInstance();
3370 // On cree une fabrique de BatchManager de type PBS
3371 Batch::FactBatchManager & fbm = * cata("PBS");
3379 @b{FactBatchManager_PBS()}
3381 Ce constructeur instancie un objet de la classe
3382 @emph{FactBatchManager_PBS} et l'enregistre automatiquement aupres du
3383 catalogue de fabrique. @xref{Classe BatchManagerCatalog}.
3385 Le type est positionne a la valeur PBS.
3388 @b{~FactBatchManager_PBS()}
3390 Le destructeur ne fait rien de particulier.
3393 @b{BatchManager_PBS * operator() (const char * hostname) const}
3395 Cet operateur renvoie un objet nouvellement cree de type
3396 @emph{BatchManager_PBS} derivant de @emph{BatchManager} et oeuvrant sur
3397 la machine @emph{hostname}. La destruction de l'objet est a la charge de
3404 @c ----------------------
3405 @c ----------------------
3406 @c ----------------------
3408 @node Classe BatchManager_PBS, Classe JobInfo_PBS, Classe FactBatchManager_PBS, Classes PBS
3409 @comment node-name, next, previous, up
3411 @subsubsection BatchManager_PBS
3412 @cindex BatchManager_PBS
3414 Cette classe derive de la classe generique @emph{BatchManager},
3415 @xref{Classe BatchManager}.
3417 Les objets de la classe @emph{BatchManager_PBS} realisent l'interface de
3418 la bibliotheque avec l'API du gestionnaire de batch OpenPBS.
3424 class BatchManager_PBS : public BatchManager
3427 // Constructeur et destructeur
3428 BatchManager_PBS(FactBatchManager * parent,
3429 const char * host) throw(InvalidArgumentException);
3430 virtual ~BatchManager_PBS();
3432 // Recupere le nom du serveur par defaut
3433 static string getDefaultServer();
3435 // Recupere le l'identifiant d'un job deja soumis au BatchManager
3436 virtual const JobId getJobIdByReference(const string & ref);
3438 // Methodes pour le controle des jobs : virtuelles pures
3439 // soumet un job au gestionnaire
3440 virtual const JobId submitJob(const Job & job);
3442 // retire un job du gestionnaire
3443 virtual void deleteJob(const JobId & jobid);
3445 // suspend un job en file d'attente
3446 virtual void holdJob(const JobId & jobid);
3448 // relache un job suspendu
3449 virtual void releaseJob(const JobId & jobid);
3451 // modifie un job en file d'attente
3452 virtual void alterJob(const JobId & jobid,
3453 const Parametre & param,
3454 const Environnement & env);
3455 virtual void alterJob(const JobId & jobid,
3456 const Parametre & param);
3457 virtual void alterJob(const JobId & jobid,
3458 const Environnement & env);
3460 // renvoie l'etat du job
3461 virtual JobInfo queryJob(const JobId & jobid);
3463 // modifie un job en file d'attente
3464 virtual void setParametre(const JobId & jobid,
3465 const Parametre & param);
3466 virtual void setEnvironnement(const JobId & jobid,
3467 const Environnement & env);
3470 string _hostname; // serveur ou tourne le BatchManager
3482 // On recupere l'instance du catalogue de gestionnaires de batch
3483 Batch::BatchManagerCatalog cata = Batch::BatchManagerCatalog::getInstance();
3485 // On cree une fabrique de BatchManager de type PBS
3486 Batch::BatchManager & myBM = (* cata("PBS"))("serveur.domaine.fr")
3488 // Maintenant, on peut utiliser toutes les fonctionnalites du
3489 // gestionnaire de batch a travers le variable myBM
3497 @b{BatchManager_PBS(FactBatchManager * parent,
3498 const char * host) throw(InvalidArgumentException)}
3500 Excepte un pointeur sur la fabrique qui a produit l'objet, le
3501 constructeur accepte zero ou un argument de type @emph{string} decrivant
3502 soit le nom de domaine completement qualifie (FQDN, @i{fully qualified
3503 domain name}) du serveur de batch, soit son adresse IP dans un format
3504 decimal "aaa.bbb.ccc.ddd".
3506 Si aucun parametre n'est passe au constructeur, celui-ci prend le
3507 serveur par defaut tel que renvoye par la methode @emph{getDefaultServer}.
3509 Une resolution du nom ou de l'adresse peut etre realisee en fonction des
3510 capacites de la plate-forme pour s'assurer que le serveur est connu et
3511 joignable. En cas d'echec, une exception InvalidArgumentException est
3512 levee. @xref{Classe InvalidArgumentException}.
3514 Ceci fait, une connexion est etablie avec le gestionnaire de batch qui
3515 est maintenue jusqu'a destruction de l'objet.
3520 Le destructeur supprime la connexion precedemment etablie par le
3521 constructeur lorsque celle-ci a reussi.
3524 @b{const JobId submitJob(const Job & job)}
3526 Cette methode soumet le job passe en argument au gestionnaire de
3527 batch. Etant donne que le job ne peut pas etre envoye tel quel puisqu'il
3528 a un format generique au sein de la bibliotheque de classes Batch, cette
3529 methode est chargee de le convertir dans un format adapte au
3530 gestionnaire de batch sous-jacent.
3532 La methode opere ici une conversion du job de la classe @emph{Job} en @emph{Job_PBS}.
3534 Ce n'est que lorsque cette conversion est realisee que le job est soumis
3535 au gestionnaire a travers son API. L'identifiant propose par le
3536 gestionnaire est alors renvoye a l'appelant. Si la soumission echoue
3537 pour une raison ou une autre, une exception APIInternalFailureException est
3538 levee. @xref{Classe APIInternalFailureException}.
3541 @b{void deleteJob(const JobId & jobid)}
3543 Cette methode retire le job dont l'identifiant est passe en argument de
3544 la file d'attente du gestionnaire, ou bien l'arrete en cours
3545 d'execution. Cette methode est inoperante sur des travaux deja termines,
3546 auquel cas une exception APIInternalFailureException est
3547 levee. @xref{Classe APIInternalFailureException}.
3551 @b{void holdJob(const JobId & jobid)}
3553 Cette methode suspend le job dont l'identifiant est passe en argument au
3554 sein de la file d'attente du gestionnaire. Cette methode est inoperante
3555 sur des travaux en cours d'execution ou deja termines, ainsi que sur des
3556 travaux deja suspendus.
3557 En cas de probleme, une exception APIInternalFailureException est
3558 levee. @xref{Classe APIInternalFailureException}.
3561 @b{void releaseJob(const JobId & jobid)}
3563 Cette methode relache un job precedemment suspendu en file
3564 d'attente dont l'identifiant est passe en argument. Elle est inoperante
3565 sur des travaux deja reclaches, en cours d'execution ou termines.
3566 En cas de probleme, une exception APIInternalFailureException est
3567 levee. @xref{Classe APIInternalFailureException}.
3571 @b{void alterJob(const JobId & jobid, const Parametre & param, const Environnement & env)@*
3572 void alterJob(const JobId & jobid, const Parametre & param)@*
3573 void alterJob(const JobId & jobid, const Environnement & env)}
3575 Ces methodes permettent de modifier les parametres d'execution et
3576 d'environnement d'un job dont l'identifiant est passe en
3577 argument. @xref{Classe Parametre}. @xref{Classe Environnement}. Il
3578 est important de noter que le job doit etre encore place en file
3579 d'attente sinon la methode est inoperante.
3580 En cas de probleme, une exception APIInternalFailureException est
3581 levee. @xref{Classe APIInternalFailureException}.
3584 @b{JobInfo queryJob(const JobId & jobid)}
3586 Cette methode permet de recuperer les informations concernant le job
3587 dont l'identifiant est passe en argument dans un objet de classe
3588 @emph{JobInfo}. @xref{Classe JobInfo}. On y retrouve les parametres
3589 d'execution et d'environnement du job tels qu'ils ont ete passes au
3590 gestionnaire au moment de la soumission, ainsi que des informations
3591 concernant l'execution du job comme par exemple la machine d'execution,
3592 le temps consomme, la memoire consommee, etc.
3594 Il n'est pas toujours possible d'interroger un job deja termine.
3595 En cas de probleme, une exception APIInternalFailureException est
3596 levee. @xref{Classe APIInternalFailureException}.
3600 @b{const JobId getJobIdByReference(const string & ref)}
3602 Cette methode permet de recuperer au sein de la classe un identifiant de
3603 job a partir d'une chaine de caracteres obtenue par un biais
3604 externe. Cet identifiant pourra etre utilise par la suite au sein de la
3605 biliotheque de classes pour controler le job comme s'il avait ete cree
3606 et soumis depuis la biliotheque-meme.
3609 @b{void setParametre(const JobId & jobid, const Parametre & param)}
3611 Cette methode n'est utile que pour l'interfacage avec Python, car Python
3612 ne sait pas gerer la surcharge de methode, et de fait leve des
3613 exceptions lors d'appels a de telles methodes.
3615 Elle est equivalente a la methode @samp{void alterJob(const JobId & jobid, const Parametre & param)}.
3618 @b{void setEnvironnement(const JobId & jobid, const Environnement & env)}
3620 Cette methode n'est utile que pour l'interfacage avec Python, car Python
3621 ne sait pas gerer la surcharge de methode, et de fait leve des
3622 exceptions lors d'appels a de telles methodes.
3624 Elle est equivalente a la methode @samp{void alterJob(const JobId & jobid, const Environnement & env)}.
3631 @c ----------------------
3632 @c ----------------------
3633 @c ----------------------
3636 @node Classe JobInfo_PBS, Classe Job_PBS, Classe BatchManager_PBS, Classes PBS
3637 @comment node-name, next, previous, up
3639 @subsubsection JobInfo_PBS
3642 Un objet de classe @emph{JobInfo} represente l'ensemble des informations
3643 disponibles sur un travail actif, c'est-a-dire soumis au gestionnaire de
3644 batch, a un instant donne.
3646 Cet objet reprend des informations issues du job tel qu'il a ete soumis,
3647 @xref{Classe Job}, mais aussi des informations produites par le
3648 gestionnaire de batch a partir de la soumission et du transit du job en
3649 son sein : nom de la queue dans laquelle le job est inscrit, duree
3650 d'execution, date de soumission, etc.
3652 Ces informations sont disponibles aupres de l'utilisateur de la classe a
3653 travers les objets @emph{Parametre} et @emph{Environnement} que l'objet
3654 @emph{JobInfo} peut fournir.
3660 class JobInfo_PBS : public JobInfo
3663 // Constructeur standard et destructeur
3665 JobInfo_PBS(struct batch_status * stat_list,
3666 bool tobedeleted = false);
3667 virtual ~JobInfo_PBS();
3669 // Constructeur par recopie
3670 JobInfo_PBS(const JobInfo_PBS & jinfo);
3672 // Methodes pour l'interfacage avec Python (SWIG)
3673 string __str__() const; // SWIG : affichage en Python
3674 string __repr__() const; // SWIG : affichage en Python
3677 Parametre _param; // parametres du job
3678 Environnement _env; // variables d'environnement du job
3687 @dots{} (ici on cree un BatchManager bm et un Job job)
3689 // On soumet le job et on recupere un identifiant
3690 JobId jobid = bm.submitJob(job);
3692 // Ce qui permet d'interroger l'etat du job en cours
3693 // Nota : l'objet retourne est un JobInfo_PBS
3694 JobInfo jinfo = jobid.queryJob();
3704 Ce constructeur cree un objet @emph{JobInfo_PBS} vide.
3709 Le destructeur libere l'espace memoire alloue pour l'objet si la
3710 desollacation n'a pas eu deja lieu dans le constructeur.
3713 @b{JobInfo_PBS(const JobInfo_PBS & jinfo)}
3715 Le constructeur par recopie produit un objet identique a celui passe en
3716 argument. Les deux objets sont totalement independants l'un de l'autre.
3719 @b{JobInfo_PBS(struct batch_status * stat_list, bool tobedeleted = false)}
3721 Ce constructeur recupere une liste chainee du type interne OpenPBS
3722 @emph{struct batch_status *}, la parcoure et l'analyse pour en extraire
3723 les informations utilisables par la bibliotheque de classes et les
3724 stocker dans deux objets internes @emph{Parametre} et
3725 @emph{Environnement}.
3727 Si le parametre @emph{tobedeleted} vaut @emph{true} alors la liste
3728 chainee @emph{stat_list} sera desallouee a la fin du constructeur. Sinon
3729 elle sera desalloue dans le destructeur au plus tard.
3732 @b{string __str__() const}
3734 Cette methode n'est utile que pour l'interfacage avec Python. Elle
3735 permet d'afficher l'etat de l'objet @emph{JobInfo}.
3738 @b{string __repr__() const}
3740 Cette methode n'est utile que pour l'interfacage avec Python. Elle
3741 permet d'afficher l'etat de l'objet @emph{JobInfo}.
3748 @c ----------------------
3749 @c ----------------------
3750 @c ----------------------
3753 @node Classe Job_PBS, Classes Python, Classe JobInfo_PBS, Classes PBS
3754 @comment node-name, next, previous, up
3756 @subsubsection Job_PBS
3759 Un objet de classe @emph{Job} possede une structure generique
3760 potentiellement utilisable par tout gestionnaire de batch mais pas en
3761 l'etat. Une conversion dans un format lisible par le gestionnaire doit
3764 Ceci se fait en produisant a partir des donnees generiques de la classe
3765 @emph{Job} des structures de donnees specifiques qui peuvent etre
3766 directement passees a l'API du gestionnaire.
3768 La classe @emph{Job_PBS} se distingue donc de la classe @emph{Job} par son
3769 constructeur et par des accesseurs specifiques qui produisent des
3770 donnees lisibles par OpenPBS.
3772 Etant donnee la specificite de cette classe, elle ne devrait concerner
3773 que les developpeurs de la bibliotheque de classes Batch.
3782 // Constructeurs et destructeur
3783 Job_PBS(const Job & job);
3787 struct attropl * getAttributesOP();
3788 struct attrl * getAttributes();
3790 char * getDestination();
3793 struct attropl * _p_attropl; // liste d'attributs + operateur
3794 struct attrl * _p_attrl; // liste d'attributs
3795 char * _script; // chemin d'acces au script du job
3796 char * _destination; // queue dans laquelle le job est soumis
3811 @dots{} (ici on cree les parametres du job)
3813 Job job(param, env);
3815 // On fabrique un job specifique a OpenPBS a partir du job generique
3816 // Ceci ne concerne en general pas l'utilisateur de la bibliotheque
3817 Job_PBS jobpbs(job);
3826 @b{Job_PBS(const Job & job)}
3828 Le constructeur convertit les objets internes @emph{Parametre} et
3829 @emph{Environnement} de l'objet passe en argument en un ensemble de
3830 quatre structures C @emph{AttributesOP}, @emph{Attributes},
3831 @emph{Script} et @emph{Destination} directement utilisable par l'API de
3837 Le destructeur libere simplement les espaces alloues pour les structures
3838 @emph{AttributesOP}, @emph{Attributes}, @emph{Script} et
3842 @b{struct attropl * getAttributesOP()}
3844 Cet accesseur retourne un pointeur sur la structure interne
3845 @emph{AttributesOP} de l'objet. Cette structure n'est pas protogee
3846 contre les modifications accidentelles de l'utilisateur. Par consequent
3847 il est recommande d'eviter d'y apporter toute alteration sous peine de
3850 Pour la definition de la structure @emph{AttributesOP}, voir la
3851 documentation OpenPBS.
3854 @b{struct attrl * getAttributes()}
3856 Cet accesseur retourne un pointeur sur la structure interne
3857 @emph{Attributes} de l'objet. Cette structure n'est pas protogee
3858 contre les modifications accidentelles de l'utilisateur. Par consequent
3859 il est recommande d'eviter d'y apporter toute alteration sous peine de
3862 Pour la definition de la structure @emph{Attributes}, voir la
3863 documentation OpenPBS.
3866 @b{char * getScript()}
3868 Cet accesseur retourne un parametre @emph{Script} qui est une chaine de
3869 caracteres C contenant le chemin absolu (sur la machine d'execution)
3870 du script a soumettre au gestionnaire de batch.
3872 Cette chaine n'est pas protegee contre les modifications accidentelles
3873 de l'utilisateur. Il est donc recommande de ne pas y apporter de modification.
3876 @b{char * getDestination()}
3878 Cet accesseur retourne un parametre @emph{Destination} qui est une chaine de
3879 caracteres C contenant le nom de la queue, ou classe ou file selon les terminologies,
3880 du gestionnaire de batch dans laquelle le job doit etre soumis.
3882 Cette chaine n'est pas protegee contre les modifications accidentelles
3883 de l'utilisateur. Il est donc recommande de ne pas y apporter de modification.
3890 @c ----------------------
3891 @c ----------------------
3892 @c ----------------------
3894 @node Classes Python, Classe PyVersatile, Classe Job_PBS, Classes specifiques
3895 @comment node-name, next, previous, up
3897 @subsection Classes Python
3898 @cindex classes Python
3900 L'integration de la bibliotheque de classes Batch dans l'interpreteur
3901 Python a beaucoup progresse depuis la precedente version et se trouve
3902 etre quasiment iso-fonctionelle avec le C++.
3904 Actuellement, l'interface avec Python s'appuie a la fois sur les
3905 fonctionnalites de l'utilitaire SWIG, et sur la definition d'une classe
3906 specifique qui permet de voir en Python la classe @emph{Versatile}.
3908 Certaines classes ont de plus des methodes specifiques pour le wrapping
3909 Python qui simplifient grandement le developpement des classes
3910 d'interface au detriment, il est vrai, d'une bonne independance entre
3911 les langages. Ce choix n'est pas definitif et pourra etre revu si
3912 l'occasion s'en presente.
3914 Quoi qu'il en soit toutes les classes de haut niveau sont interfacees en
3915 Python sous le meme nom et proposent les memes methodes (sauf celles
3916 surchargees en C++ qui sot parfois renommees pour lever
3917 l'ambiguite). Pour ne pas refaire un expose detaille et fastidieux des
3918 fonctionnalites Python de la bibliotheque de classes, il est propose de
3919 retrouver les noms et la syntaxe de ces classe dans la partie
3920 Utilisation de ce document. @xref{Utilisation}.
3923 * Classe PyVersatile:: Description de la classe PyVersatile.
3926 @c ----------------------
3927 @c ----------------------
3928 @c ----------------------
3931 @node Classe PyVersatile, Utilisation, Classes Python, Classes Python
3932 @comment node-name, next, previous, up
3934 @subsubsection PyVersatile
3938 La classe @emph{PyVersatile} derive de la classe @emph{Versatile} et
3939 offre la possibilite de convertir un tel objet en objet Python et
3947 class PyVersatile : public Versatile
3950 // Constructeur a partir d'un objet Versatile
3951 PyVersatile(const Versatile &);
3953 // Constructeur a partir d'un PyObject
3954 PyVersatile(const PyObject *) throw(TypeMismatchException,
3955 ListIsFullException,
3956 InvalidArgumentException);
3958 // Conversion de type vers un PyObject
3959 operator PyObject *() const;
3961 // Operateur d'affectation a partir d'un objet Versatile
3962 PyVersatile & operator =(const Versatile &);
3976 // On cree un objet Versatile contenant
3977 // une liste de chaine de caracteres
3981 // On convertit cet objet Versatile en PyVersatile
3984 // De la on produit un objet Python
3985 // qui est une liste de chaine de caracteres
3986 PyObject * PyO = PyV;
3995 @b{PyVersatile(const Versatile &)}
3997 Ce constructeur convertit un objet @emph{Versatile} en objet @emph{PyVersatile}.
4000 @b{PyVersatile(const PyObject *) throw(TypeMismatchException, ListIsFullException, InvalidArgumentException)}
4002 Ce constructeur convertit un objet Python passe en argument en un objet
4005 Seuls certains objets Python peuvent etre convertis : les @emph{string}
4006 et les @emph{long}, ainsi que les listes homogenes de ces types, ce qui
4007 est coherent avec la nature de l'objet @emph{Versatile}. Si tel n'est
4008 pas le cas, une exception Python est renvoyee a l'interpreteur.
4012 @b{operator PyObject *() const}
4014 Cet operateur convertit l'objet en objet Python. Selon le cas, l'objet
4015 retourne est soit un scalaire soit une liste. L'objet retourne est
4016 alloue dynamiquement et doit donc etre pris en charge par l'interpreteur.
4019 @b{PyVersatile & operator =(const Versatile &)}
4021 L'affectation d'un objet @emph{Versatile} passe en argument est
4022 similaire a l'affectation entre objets @emph{Versatile}. Les structures
4023 de donnees internes initiales de l'objet sont effacees et remplacees par
4024 une copie des donnees internes de l'objet passe en argument. Les deux
4025 objets restent independants l'un de l'autre a l'issue de l'affectation.
4033 @c ----------------------
4034 @c ----------------------
4035 @c ----------------------
4037 @node Utilisation, Connexion, Classe PyVersatile, Top
4038 @comment node-name, next, previous, up
4040 @chapter Utilisation
4043 Ce chapitre presente les differentes actions qu'il est possible de
4044 realiser avec les classes de la bilbiotheque.
4046 On presente un cas hypothetique ou un utilisateur voudrait soumettre et
4047 controler un job depuis un code C++. Les sections suivantes decrivent
4048 les operations a faire ainsi que leur action sur le travail soumis.
4051 * Connexion:: Creation d'un gestionnaire de batch.
4052 * Creation:: Declaration d'un job (travail).
4053 * Soumission:: Demande d'execution du job.
4054 * Interrogation:: Recuperation des informations sur le job.
4055 * Destruction:: Arret du job en cours.
4056 * Suspension:: Suspension du job en file d'attente.
4057 * Reprise:: Liberation du job en file d'attente.
4058 * Modification:: Modification d'un job en file d'attente.
4062 @c ----------------------
4063 @c ----------------------
4064 @c ----------------------
4066 @node Connexion, Creation, Utilisation, Utilisation
4067 @comment node-name, next, previous, up
4072 La premiere etape avant toute utilisation pratique des classes de la
4073 bibliotheque consiste a se connecter a un gestionnaire de batch.
4075 Ce concept de connexion est purement interne a la bibliotheque car il
4076 est tout a fait possible d'imaginer le controle de jobs a travers l'API
4077 d'un gestionnaire sans jamais etablir ni maintenir une quelconque
4078 connexion avec celui-ci. D'autres par contre reclament l'etablissement
4081 Quoiqu'il en soit ceci n'est pas genant et l'etablissement et le
4082 maintien de la connexion avec le gestionnaire de batch se fait par la
4083 creation d'un objet de classe @emph{BatchManager} ou d'une classe
4086 En pratique, la classe @emph{BatchManager} se comporte comme une
4087 interface et seules les classes d'implementation derivee doivent etre
4090 Si l'on prend le cas d'un serveur @samp{serveur.domaine.fr} supportant
4091 un gestionnaire de batch OpenPBS, on peut s'y connecter de la maniere
4098 BatchManagerCatalog cata = BatchManagerCatalog::getInstance();
4099 BatchManager_PBS & bm = * (* cata('PBS'))("serveur.domaine.fr");
4102 @item Exemple Python:
4105 cata = BatchManagerCatalog.getInstance()
4106 bm = cata('PBS')('serveur.domaine.fr')
4111 Tant que l'objet @emph{bm} sera present --- tant que son destructeur
4112 n'aura pas ete appele --- la connexion sera maintenue. La deconnexion
4113 aura lieu a la destruction de l'objet.
4115 @xref{Classe BatchManager}.
4116 @xref{Classe BatchManager_PBS}.
4119 @c ----------------------
4120 @c ----------------------
4121 @c ----------------------
4123 @node Creation, Soumission, Connexion, Utilisation
4124 @comment node-name, next, previous, up
4128 La creation du job est l'etape qui precede toute soumission. Elle
4129 necessite de decrire d'un maniere ou d'un autre ce que l'on va demander
4130 a la machine d'executer.
4132 Pour cela on passe par deux objets intermediaires qui sont l'objet
4133 @emph{Parametre} et l'objet @emph{Environnement}.
4135 Le minimum a preciser est en general le chemin absolu d'acces a
4136 l'executable, quoique ceci depende fortement de la configuration du
4137 gestionnaire auquel on se connecte. Celui-ci peut reclamer des
4138 parametres supplementaires.
4140 Pour connaitre l'ensemble des parametres disponibles : @xref{Classe
4143 On supposera dans cet exemple que l'application en question sait
4144 reconnaitre une variable d'environnement @var{myapp_loglevel} qui prend
4145 une valeur numerique correspondant au niveau d'information affiche en
4148 Cette application imaginaire utilise egalement trois fichiers :
4152 un fichier d'entree nomme @file{Cas1.data} sur la machine locale qu'il
4153 faudra renommer @file{fort.9} pour que l'application puisse le lire
4154 (notre application imaginaire est ecrite en FORTRAN et attend un fichier
4155 d'entree sur son descripteur 9);
4158 un fichier de sortie standard que l'on voudra recuperer sous le nom
4162 un fichier d'erreur standard que l'on voudra recuperer sous le nom
4167 Le job est ensuite cree simplement a l'aide des deux objets precedents.
4174 param[EXECUTABLE] = "/home/user/my_app/bin/exec_app.sh";
4175 param[INFILE] = Couple("/home/user/my_app/data/Cas1.data","fort.9");
4176 param[OUTFILE] = Couple("/home/user/my_app/data/Cas1.out", "stdout"),
4177 Couple("/home/user/my_app/data/Cas1.err", "stderr");
4180 env["MYAPP_LOGLEVEL"] = "3";
4182 Job job(param, env);
4185 @item Exemple Python:
4189 param["EXECUTABLE"] = "/home/user/my_app/bin/exec_app.sh"
4190 param["INFILE"] = [ ("/home/user/my_app/data/Cas1.data","fort.9") ]
4191 param["OUTFILE"] = [ ("/home/user/my_app/data/Cas1.out", "stdout"),
4192 ("/home/user/my_app/data/Cas1.err", "stderr") ]
4195 env["MYAPP_LOGLEVEL"] = "3"
4198 job.setParametre(param)
4199 job.setEnvironnement(env)
4205 @xref{Classe Parametre}.
4206 @xref{Classe Environnement}.
4210 @c ----------------------
4211 @c ----------------------
4212 @c ----------------------
4214 @node Soumission, Interrogation, Creation, Utilisation
4215 @comment node-name, next, previous, up
4220 Une fois le job cree, il est alors tres simple de le soumettre au
4221 gestionnaire de batch en passant par l'intermediaire de l'objet
4222 @emph{BatchManager} cree precedemment.
4224 Cette soumission produira un objet @emph{JobId} qui servira a controler
4225 le job par la suite.
4227 Cependant des exceptions peuvent etre levees au moment de la soumission
4228 et il convient de fournir un gestionnaire d'exception pour gerer
4229 proprement ces incidents.
4236 const JobId jobid = bm.submitJob(job);
4238 @} catch (GenericException & ex) @{
4243 @item Exemple Python:
4247 jobid = bm.submitJob(job)
4256 @xref{Classe JobId}.
4260 @c ----------------------
4261 @c ----------------------
4262 @c ----------------------
4264 @node Interrogation, Destruction, Soumission, Utilisation
4265 @comment node-name, next, previous, up
4266 @section Interrogation
4267 @cindex interrogation
4270 La fourniture d'un objet @emph{JobId} permet d'avoir tout controle sur
4271 le job en cours. En particulier il est possible de l'interroger :
4272 ceci generera un objet @emph{JobInfo} qui donnera l'ensemble des
4273 informations disponibles sur l'etat du job aupres du gestionnaire de
4276 Ces informations sont disponibles a travers deux objets internes de
4277 classes @emph{Parametre} et @emph{Environnement}, les memes que pour la
4278 classe @emph{Job}, mais modifies et completes avec les donnees les plus
4279 a jour du gestionnaire de batch.
4286 const JobInfo jinfo = jobid.queryJob();
4288 Parametre newparam = jinfo.getParametre();
4289 Environnement newenv = jinfo.getEnvironnement();
4291 @} catch (GenericException & ex) @{
4296 @item Exemple Python:
4300 jobinfo = jobid.queryJob()
4302 newparam = jinfo.getParametre()
4303 newenv = jinfo.getEnvironnement()
4311 @xref{Classe JobId}.
4312 @xref{Classe JobInfo}.
4317 @c ----------------------
4318 @c ----------------------
4319 @c ----------------------
4321 @node Destruction, Suspension, Interrogation, Utilisation
4322 @comment node-name, next, previous, up
4323 @section Destruction
4329 Il est possible de detruire un job que celui-ci soit encore en file
4330 d'attente ou bien que son execution ait deja commence, auquel cas elle
4331 serait immediatement interrompue.
4341 @} catch (GenericException & ex) @{
4346 @item Exemple Python:
4359 @xref{Classe JobId}.
4364 @c ----------------------
4365 @c ----------------------
4366 @c ----------------------
4368 @node Suspension, Reprise, Destruction, Utilisation
4369 @comment node-name, next, previous, up
4374 La suspension consiste a figer en file d'attente un job qui n'aurait pas
4375 encore commence son execution. Il n'est pas possible de suspendre un job
4378 Il y a deux manieres de suspendre un job en file d'attente :
4380 @item en utilisant la methode @samp{holdJob};
4381 @item en modifiant les parametres du job a l'aide de la methode @samp{alterJob}.
4393 @} catch (GenericException & ex) @{
4398 @item Exemple Python:
4419 jobid.alterJob(altparam);
4421 @} catch (GenericException & ex) @{
4426 @item Exemple Python:
4429 // Compte tenu de la surcharge d'operateur, cet exemple peut ne pas
4430 // fonctionner encore
4433 altparam["HOLD"] = 1
4434 jobid.alterJob(altparam)
4444 @xref{Classe JobId}.
4448 @c ----------------------
4449 @c ----------------------
4450 @c ----------------------
4452 @node Reprise, Modification, Suspension, Utilisation
4453 @comment node-name, next, previous, up
4458 La reprise est l'operation inverse de la suspension en ceci qu'elle
4459 libere un job precedemment suspendu en file d'attente. Le job continuera
4460 alors son cheminement normal au sein du gestionnaire de batch.
4462 Il y a deux manieres de suspendre un job en file d'attente :
4464 @item en utilisant la methode @samp{releaseJob};
4465 @item en modifiant les parametres du job a l'aide de la methode @samp{alterJob}.
4477 @} catch (GenericException & ex) @{
4482 @item Exemple Python:
4503 jobid.alterJob(altparam);
4505 @} catch (GenericException & ex) @{
4510 @item Exemple Python:
4513 // Compte tenu de la surcharge d'operateur, cet exemple peut ne pas
4514 // fonctionner encore
4517 altparam["HOLD"] = 0
4518 jobid.alterJob(altparam)
4527 @xref{Classe JobId}.
4531 @c ----------------------
4532 @c ----------------------
4533 @c ----------------------
4535 @node Modification, Installation de la bibliotheque, Reprise, Utilisation
4536 @comment node-name, next, previous, up
4537 @section Modification
4538 @cindex modification
4541 Il est possible de modifier tout ou partie des parametres et des
4542 variables d'un job a condition que celui-ci soit encore en file
4543 d'attente. Un job dont l'execution a deja debute devient inalterable,
4544 sauf a l'arreter definitvement.
4546 La modification se fait en declarant un objet @emph{Parametre} et/ou un
4547 objet @emph{Environnement} contenant l'ensemble des alterations a
4548 apporter a la description du job. Ces alterations peuvent porter sur des
4549 parametres ou des variables deja definies ou non.
4551 En reprenant le cas du job imaginaire utilise jusqu'ici, on peut
4552 souhaiter changer le script qui tient lieu d'executable car le precedent
4553 etait incomplet, modifier le niveau d'affichage de la log et ajouter une
4554 variable nommee @var{myapp_debug} qui indique au code de passer en mode
4555 debug. Ceci pourrait se faire de la maniere suivante :
4563 altparam[EXECUTABLE] = "/home/user/my_app/bin/exec_app.sh";
4565 Environnement altenv;
4566 altenv["MYAPP_LOGLEVEL"] = "4";
4567 altenv["MYAPP_DEBUG"] = "1";
4568 jobid.alterJob(altparam, altenv);
4570 @} catch (GenericException & ex) @{
4575 @item Exemple Python:
4578 // Compte tenu de la surcharge d'operateur, cet exemple peut ne pas
4579 // fonctionner encore
4582 altparam["EXECUTABLE"] = "/home/user/my_app/bin/exec_app.sh"
4585 altenv["MYAPP_LOGLEVEL"] = "4";
4586 altenv["MYAPP_DEBUG"] = "1";
4588 jobid.alterJob(altparam, altenv)
4597 @xref{Classe JobId}.
4600 @c ----------------------
4601 @c ----------------------
4602 @c ----------------------
4604 @node Installation de la bibliotheque, Prerequis, Modification, Top
4605 @comment node-name, next, previous, up
4606 @chapter Installation
4607 @cindex installation
4609 Cette section montre comment installer l'ensemble de la bibliotheque de
4610 classes Batch sur une machine Unix.
4614 * Installation rapide::
4617 * Compilation de la documentation::
4624 @c ----------------------
4625 @c ----------------------
4626 @c ----------------------
4628 @node Prerequis, Installation rapide, Installation de la bibliotheque, Installation de la bibliotheque
4629 @comment node-name, next, previous, up
4633 @unnumberedsubsubsec CMake
4636 La bibliotheque de classes Batch utilise CMake pour la configuration et
4637 la generation des Makefiles (voir le site officiel
4638 @uref{http://www.cmake.org/}). La version minimum requise est la 2.4.
4640 @unnumberedsubsec GCC/G++
4642 A l'heure actuelle, la bibliotheque de classes Batch est developpee en
4643 C++ et necessite de fait un compilateur pour ce langage. GCC/G++
4644 version 2.95.3 ou une version ulterieure est un choix judicieux.
4646 @unnumberedsubsec Gestionnaires de batch
4648 Comme la bibliotheque utilise les fonctionnalites de certains
4649 gestionnaires de batch, il est indispensable de pouvoir acceder aux
4650 bibliotheques et aux fichiers d'entete de ces produits, ou du moins des
4651 produits dont on se servira par la suite, ceci pour pouvoir communiquer
4652 a travers l'API qu'ils ont developpe.
4654 Le cas le plus simple est d'avoir le produit directement installe sur la
4655 machine sur laquelle sera compilee la bibliotheque de classes Batch.
4657 @unnumberedsubsubsec OpenPBS
4661 A ce jour, seul le gestionnaire de batch PBS (OpenPBS et PBS Pro) est
4662 supporte (voir le site officiel @uref{http://www.openpbs.org}). Il doit
4663 avoir une version au moins egale a 2.3.16.
4665 @unnumberedsubsubsec LSF
4668 Il est prevu d'avoir un support de LSF dans les mois qui viennent.
4670 @unnumberedsubsubsec LoadLeveler
4673 Il est prevu d'avoir un support de LoadLeveler mais dans un futur plus
4674 lointain en fonction de la disponibilite du produit mais surtout d'une
4675 machine sur lequel il serait installe.
4677 @unnumberedsubsubsec Sun Grid Engine
4679 Ce choix-la est beaucoup plus hypothetique, et risque bien de ne jamais
4682 @unnumberedsubsubsec Rsh/Ssh
4684 Il est prevu de simuler le fonctionnement d'un gestionnaire de batch a
4685 l'aide de commandes Unix Rsh et Ssh dans la mesure de leurs capacites
4686 lorsque qu'il n'est pas possible d'avoir un gestionnaire de batch sur
4687 certaines machines ou de s'y connecter (par exemple lorsqu'on traverse
4690 @unnumberedsubsec Python
4693 Les classes de haut-niveau de la bibliotheque de classes Batch disposent
4694 d'une interface en Python qui leur permet d'etre utilisables dans ce
4695 langage. L'usage de cette fonctionnalite necessite d'avoir a disposition
4696 une version de Python (voir le site officiel
4697 @uref{http://www.python.org}) au moins egale a 2.2.
4699 @unnumberedsubsec SWIG
4702 De plus l'interfacage avec Python est automatise a l'aide de
4703 l'utilitaire SWIG (voir le site officiel @uref{http://www.swig.org}) qui
4704 transcrit les definitions des classes C++ en classes Python. Il faut
4705 pour cela disposer de la version 1.3.17 ou ulterieure.
4710 @c ----------------------
4711 @c ----------------------
4712 @c ----------------------
4714 @node Installation rapide, Configuration, Prerequis, Installation de la bibliotheque
4715 @comment node-name, next, previous, up
4716 @section Installation rapide
4717 @cindex installation rapide
4719 Il faut commencer par decompresser le fichier @file{.tar.gz} ou
4720 @file{.tgz} et descendre dans le repertoire qu'il a cree :
4723 $ tar -xzvf libBatch-@value{VERSION}.tar.gz
4724 $ cd libBatch-@value{VERSION}
4727 Pour ceux qui sont vraiment presses, le minimum requis est :
4735 Pour ceux qui ont le temps de lire la suite, les sections suivantes
4736 decrivent plus en detail ces etapes et les differents tests que l'on
4739 @c ----------------------
4740 @c ----------------------
4741 @c ----------------------
4743 @node Configuration, Compilation, Installation rapide, Installation de la bibliotheque
4744 @comment node-name, next, previous, up
4745 @section Configuration
4746 @cindex configuration
4748 La phase de configuration, tres classique dans le domaine des logiciels
4749 libres, est basee sur CMake (voir @uref{http://www.cmake.org/}).
4751 La configuration est faite en appelant @file{cmake} avec en parametre
4752 le repertoire racine de la bibliotheque de classes
4753 Batch. Ce programme analyse l'ensemble des elements du systeme sur
4754 lequel se deroulera la compilation pour determiner les parametres
4755 optimaux et la presence de tous les produits necessaires a la
4758 On n'oubliera pas de se referer a la documentation de @file{cmake}
4759 notamment pour determiner l'emplacement definitif de l'installation. Le
4760 fichier @file{INSTALL} situe a la racine de la bibliotheque de classes
4761 Batch pourra egalement donner des indications d'utilisation.
4763 C'est aussi au cours de cette phase de configuration qu'il est
4764 indispensable de preciser avec quelles options la bibliotheque doit etre
4765 generee. En particulier il est necessaire d'indiquer avec quel(s)
4766 gestionnaire(s) de batch doit se faire la compilation de maniere a avoir
4767 acces a l'API. L'utilitaire @file{ccmake}, qui prend en parametre
4768 le repertoire racine de la bibliotheque de classes Batch, permet de
4769 preciser cette configuration.
4771 @c ----------------------
4772 @c ----------------------
4773 @c ----------------------
4775 @node Compilation, Compilation de la documentation, Configuration, Installation de la bibliotheque
4776 @comment node-name, next, previous, up
4777 @section Compilation
4780 La compilation proprement dite n'appelle pas de remarque particuliere :
4786 On n'oubliera pas d'utiliser les fonctionnalites de chaque @file{make},
4787 comme par exemple la compilation parallele pour reduire les temps de
4788 compilation (voir @inforef{Top, ,make}).
4790 @c ----------------------
4791 @c ----------------------
4792 @c ----------------------
4794 @node Compilation de la documentation, Tests, Compilation, Installation de la bibliotheque
4795 @comment node-name, next, previous, up
4796 @section Compilation de la documentation
4797 @cindex compilation de la documentation
4799 Normalement la documentation est automatiquement compilee lors de la
4800 compilation de la bibliotheque, mais uniquement sous forme HTML.
4801 Il est egalement possible d'obtenir un fichier @file{.info} ou un fichier
4802 @file{.dvi} qui permettra de generer d'autres formats comme le
4803 PostScript (fichier @file{.ps}) ou le PDF (fichier @file{.pdf}).
4804 Cependant les cibles permettant de generer ces autres formats n'ont pas
4805 ete creees a l'heure actuelle.
4807 @c ----------------------
4808 @c ----------------------
4809 @c ----------------------
4811 @node Tests, Installation, Compilation de la documentation, Installation de la bibliotheque
4812 @comment node-name, next, previous, up
4816 @unnumberedsubsec Tests de pre-installation
4818 La bibliotheque de classes Batch dispose d'un ensemble de tests
4819 permettant de verifier le fonctionnement des differents systemes de
4820 batch. Les tests sont executes de la maniere suivante :
4826 A la fin des tests, un compte rendu est fait qui avertit l'utilisateur
4827 des tests reussis et des echecs rencontres. Chaque test peut etre rejoue
4828 individuellement grace a l'utilitaire @file{ctest} et en precisant le
4829 nom du test. Par exemple :
4832 $ ctest -R Local_SSH
4835 @unnumberedsubsec Tests de post-installation
4837 Aucun test de post-installation n'est actuellement possible sur la
4838 bibliotheque de classes Batch.
4840 @c ----------------------
4841 @c ----------------------
4842 @c ----------------------
4844 @node Installation, Divers, Tests, Installation de la bibliotheque
4845 @comment node-name, next, previous, up
4846 @section Installation
4847 @cindex installation
4849 L'installation est la mise a disposition definitive dans le systeme de
4850 la bibliotheque de classes Batch. C'est la derniere etape de la
4851 procedure apres la configuration et la compilation.
4853 On l'execute de la maniere suivante :
4859 La bibliotheque, les fichiers d'entete, la documentation et eventuellement
4860 le module Python sont installes dans le repertoire definitif.
4864 @c ----------------------
4865 @c ----------------------
4866 @c ----------------------
4868 @node Divers, Index, Installation, Top
4869 @comment node-name, next, previous, up
4877 @c ----------------------
4878 @c ----------------------
4879 @c ----------------------
4881 @node Index, Top , Divers, Top
4882 @comment node-name, next, previous, up
4885 @heading Index des concepts
4888 @heading Index des fonctions et des methodes