RunBase.hh

Go to the documentation of this file.

//======================================================================
/*! \file RunBase.hh
 *
 *  Fichier de déclaration d'une classe de base pour les analyses: RunBase.
 */
//======================================================================


#ifndef RUN_BASE_HH
#define RUN_BASE_HH

#include "EventManager.hh"
#include "GStringList.hh"

//======================================================================
/*! \class RunBase
 *
 *  Classe de base pour créer des analyses de données.
 *  Elle hérite d'un gestionnaire d'événements (EventManager)
 *  et définit les fonctions de base (le plus souvent purement
 *  virtuelles) liées à la lecture des événements.
 *
 *  Ces fonctions concernent l'analyse elle-même:
 *  - initialisation de la structure d'événement (RunInit)
 *  - ouverture et fermeture des flux d'entrée (Open, Close)
 *  - lecture d'événements (ReadEvent (abstraite) et AnalyseEvent)
 *  - analyse: ensemble d'événements dans un fichier (AnalyseEvents) ou
 *    ensemble de fichiers (Run)
 *
 *  et les fonctions utilisateur associées:
 *  - UserEventDefine:  définition des paramètres utilisateur additionnels
 *  - UserRunStart:     début d'analyse d'un nouveau fichier
 *  - UserEvent:        traitement utilisateur d'un événement
 *  - UserUpdate:       fonction après traitement de l'événement et mise à jour des spectres
 *  - UserRunStop:      fin d'analyse d'un fichier
 *
 *  Le fonctions utilisateur doivent retourner une valeur nulle si tout
 *  va bien, une valeur négative en cas de problème et une valeur positive
 *  pour interrompre l'analyse.
 *
 *  \par Fonctions abstraites:
 *
 *  Les fonctions suivantes doivent impérativement être définies
 *  dans les classes dérivées:
 *  - int   Open  ( const string &f_name );\n
 *      elle doit appeler la fonction RunStart();
 *  - bool  IsOpen ( );
 *  - int   Close ( );\n
 *      elle doit appeler la fonction RunStop();
 *  - int   RunInit ( );
 *  - int   ReadEvent ( );
 *
 *  \par Squelette de l'analyse:
 *
 *  Traitement partiel d'événements
 *  - création d'une instance héritant de RunBase
 *  - initialisation avec Init
 *    - RunInit (fonction abstraite)
 *    - UserEventDefine
 *  - ouverture d'un fichier: Open (fonction abstraite)
 *    - appel à RunStart si nécessaire
 *        - IncrementFileCount
 *        - UserRunStart
 *  - traitement d'événements AnalyseEvents
 *    - traitement de chaque événement AnalyseEvent
 *        - ReadEvent
 *        - IncrementEventCount
 *        - UserEvent
 *        - IncrementSpectra
 *        - UserUpdate
 *  - fermeture du fichier: Close (fonction abstraite)
 *    - appel à RunStop
 *        - UserRunStop
 *
 *  Traitement d'une série de fichiers
 *  - préparation de l'analyse (détermination des fichiers d'entrée)
 *     - SetFileMode,
 *     - SetFileName,
 *     - SetFilePattern, SetFilePatternLen, SetFileNumbers,
 *  - execution
 *    - appel à Run, qui utilise:
 *      - Init
 *        - RunInit (fonction abstraite)
 *        - UserEventDefine
 *      - Open (fonction abstraite)
 *      - AnalyseEvents
 *      - Close (fonction abstraite)
 *
 */
class RunBase : public EventManager
{
//----------------------------------------------------------------------
  /*! \object_doc */
  GObjectV(RunBase);
//----------------------------------------------------------------------

  /// Type de fichiers source
  enum FileMode
  {
    runTape = 0,
    runFile = 1,
    runList = 2
  };

  protected:
    string    work_dir;             ///< répertoire de base du programme

    bool      run_init;             ///< test si l'initialisation est effectuéed42d@
    bool      run_started;          ///< test si un run est en cours

    // variables générales pour l'analyse des
    Int_t         file_mode;            ///< mode de sélection des fichiers

    string        file_name;            ///< nom effectif du fichier d'entréeb6c1cdb3a1@
    string        file_pattern;         ///< format de recherche des fichiers runs par leur numéro
    u_int         file_pattern_len;     ///< longueur du format de numéro de run
    string        file_numbers;         ///< numéro des fichiers de runs
    Int_t         file_num;             ///< numéro du fichier traité\x80-\xFF]*
    Int_t         file_sub_num;         ///< numéro secondaire du fichier traité3118ee1@
    GStringList   file_list;            ///< liste des fichiers validant le format
    bool          file_list_changed;    ///< indique s'il faut redéterminer la liste de fichiers

    Int_t         file_count;           ///< nombre de fichiers lus
    Int_t         event_count;          ///< nombre d'événements lus dans le fichier
    Int_t         total_event_count;    ///< nombre d'événements lus total

//----------------------------------------------------------------------
//  CONSTRUCTEUR / AFFECTATION / DESTRUCTEUR
//----------------------------------------------------------------------

  public:

    // Constructeur par défaut.
    RunBase ( );

  protected:
    // Constructeur de recopie.
    RunBase ( const RunBase &original );

  public:
    // Destructeur
    virtual ~RunBase ( );


//----------------------------------------------------------------------
//  FONCTIONS DE BASE POUR LA LECTURE D'EVENEMENTS

    /*! Ouverture effective du fichier de run (file_name).
     *  La fonction retourne 0 si le fichier est ouvert, une valeur
     *  négative en cas de problème, et une valeur positive s'il faut
     *  interrompre l'exécution.
     *  La fonction doit appeler RunStart ( );
     */
    virtual int   Open  ( ) = 0;
    virtual int   Open  ( const string &f_name );
    virtual int   Open  ( const u_int f_num, u_int f_sub = 0 );

    /*! Fonction qui retourne vrai si un fichier en cours d'analyse est ouvert.*/
    virtual bool  IsOpen ( ) = 0;

    /*! Fermeture du fichier en cours d'analyse.
     *  La fonction retourne 0 si le fichier est fermé, une valeur
     *  négative en cas de problème, et une valeur positive s'il faut
     *  interrompre l'exécution.
     *  La fonction doit appeler RunStop ( );
     */
    virtual int   Close ( ) = 0;

    /*! Initialisation de l'analyse: cette fonction a pour objectif
     *  de créer la structure d'événement.
     *  Elle doit ensuite faire appel à la fonction utilisateur
     *  UserEventDefine pour l'ajout de paramètres supplémentaires.
     */
    virtual int   RunInit ( ) = 0;

    virtual int   ClearEvent ( );

    /*! Lecture d'un événement: cette méthode doit être redéfinie
     *  dans les classes dérivées.
     *  La fonction mets à jour l'ensemble des paramètres de la
     *  structure d'événements à partir d'un événement lu dans le
     *  flux d'entrée.
     *  La fonction retourne 0 si la lecture s'est bien passée, et
     *  -1 en cas de fin de fichier.
     */
    virtual int   ReadEvent ( ) = 0;

    // traitement complet d'un événement
    virtual int   AnalyseEvent ( );

    // Lecture d'un ensemble d'événements
    virtual int   AnalyseEvents ( const u_int n );

    // fonctions de traitement d'une analyse
    virtual int   Init      ( );
    virtual void  Run       ( );
    virtual void  Reset     ( );
    virtual void  FullReset ( );

  protected:
    virtual int   RunStart ( );
    virtual int   RunStop  ( );

    // specific functions for derived classes
    virtual void  AnalysisStart ( );    // inline
    virtual void  AnalysisStop  ( );    // inline

    virtual void  RunTape ( );
    virtual void  RunFile ( );
    virtual void  RunList ( );


//  FONCTIONS POUR LES CLASSES DERIVEES

  protected:
    virtual void  IncrementEventCount ( );
    virtual void  IncrementFileCount  ( );

  public:
    string  GetWorkDirectory ( ) const;             // inline
    void    SetWorkDirectory ( const string & wd ); // inline

    virtual Int_t   GetTotalEventCount ( ) const;
    virtual Int_t   GetEventCount      ( ) const;
    virtual Int_t   GetFileCount       ( ) const;

    virtual bool    IsRunInit    ( ) const;
    virtual bool    IsRunStarted ( ) const;
    virtual bool    IsRunStopped ( ) const;

    virtual void    SetFileMode       ( const Int_t mode );
    virtual void    SetFileName       ( const string &f_name );
    virtual void    SetFilePattern    ( const string &pattern );
    virtual void    SetFilePatternLen ( const u_int len );
    virtual void    SetFileNumbers    ( const string &f_num );
    virtual Int_t   SetFileListNames  ( );

    virtual Int_t   GetFileMode       ( ) const;
    virtual string  GetFileName       ( ) const;
    virtual string  GetFilePattern    ( ) const;
    virtual Int_t   GetFilePatternLen ( ) const;
    virtual string  GetFileNumbers    ( ) const;
    virtual Int_t   GetFileNumber     ( ) const;

    virtual Int_t   TapeRewind   ( );
    virtual Int_t   TapeForward  ( const Int_t n = 1 );
    virtual Int_t   TapeBackward ( const Int_t n = 1 );

//----------------------------------------------------------------------
//  FONCTIONS UTILISATEUR

    virtual int UserEventDefine ( );
    virtual int UserRunStart    ( );
    virtual int UserEvent       ( );
    virtual int UserUpdate      ( );
    virtual int UserRunStop     ( );

//----------------------------------------------------------------------
//  pour ROOT...
  public:
    /*! Définition à usage de ROOT... */
    ClassDef(RunBase,0);
};


//======================================================================
//  FONCTIONS INLINE POUR L'ANALYSE
//======================================================================

/*! Return the work directory.*/
inline string RunBase::GetWorkDirectory ( ) const
  { return (work_dir); }

/*! Set the working directory.
 *  \param  wd    name of the directory
 */
inline void RunBase::SetWorkDirectory ( const string & wd )
  { work_dir = wd; }

/*! Définit le nom de fichier.
 *  \param  f_name    nom de fichier
 */
inline void RunBase::SetFileName ( const string &f_name )
  { file_name = f_name; }

/*! Définit le type de source des fichiers run.
 *  \param  mode    mode de lecture
 */
inline void RunBase::SetFileMode ( const Int_t mode )
  { file_mode = mode; }

/*! Définit le patron pour la recherche des noms de fichiers.
 *  \param  pattern   format de la recherche
 */
inline void RunBase::SetFilePattern ( const string &pattern )
  { file_pattern = pattern; file_list_changed = true; }

/*! Définit la longueur du format des numéros de run dans les fichiers.
 *  \param  len   longueur du format de numéro de run des fichiers
 */
inline void RunBase::SetFilePatternLen ( const u_int len )
  { file_pattern_len = len; file_list_changed = true; }

/*! Définit la liste des fichiers.
 *  \param  f_num     chaîne de définition de la liste
 */
inline void RunBase::SetFileNumbers ( const string &f_num )
  { file_numbers = f_num; file_list_changed = true; }


/*! Retourne le mode de lecture des fichiers de runs.*/
inline Int_t RunBase::GetFileMode ( ) const
  { return (file_mode); }

/*! Retourne le nom du fichier de runs en cours de traitement.*/
inline string RunBase::GetFileName ( ) const
  { return (file_name); }

/*! Retourne le format pour listes de fichiers de runs.*/
inline string RunBase::GetFilePattern ( ) const
  { return (file_pattern); }

/*! Retourne la longueur du format pour listes de fichiers de runs.*/
inline Int_t RunBase::GetFilePatternLen ( ) const
  { return (file_pattern_len); }

/*! Retourne la liste des numéros de fichiers de runs.*/
inline string RunBase::GetFileNumbers ( ) const
  { return (file_numbers); }

/*! Retourne le numéro du fichier en cours de traitement.*/
inline Int_t RunBase::GetFileNumber ( ) const
  { return (file_num); }

//----------------------------------------------------------------------

/*! Retourne vrai si l'analyse est initialisée.*/
inline bool RunBase::IsRunInit ( ) const
  { return (run_init); }

/*! Retourne vrai si l'analyse est démarrée.*/
inline bool RunBase::IsRunStarted ( ) const
  { return (run_started); }

/*! Retourne vrai si l'analyse est arrêtée.*/
inline bool RunBase::IsRunStopped ( ) const
  { return (!run_started); }


//----------------------------------------------------------------------

/*! Retourne le nombre total d'événements lus.*/
inline Int_t RunBase::GetTotalEventCount ( ) const
  { return (total_event_count); }

/*! Retourne le nombre d'événements lus dans le fichier.*/
inline Int_t RunBase::GetEventCount ( ) const
  { return (event_count); }

/*! Retourne le nombre de fichiers lus.*/
inline Int_t RunBase::GetFileCount ( ) const
  { return (file_count); }

/*! Incrémente le nombre d'événements lus.*/
inline void RunBase::IncrementEventCount ( )
  { event_count++; total_event_count++; }

/*! Incrémente le nombre de fichiers lus.*/
inline void RunBase::IncrementFileCount ( )
  { file_count++; }

//----------------------------------------------------------------------

/*! Function called at run start, before user function, for specific
 *  actions from derived classes.
 */
inline void RunBase::AnalysisStart ( ) { }

/*! Function called at run stop, after user function for specific
 *  actions from derived classes.
 */
inline void RunBase::AnalysisStop ( ) { }

//----------------------------------------------------------------------

/*! Fonction utilisateur par défaut pour la définitions des paramètres
 *  User de l'événement et la définition des spectres.
 *  Cette fonction est appelée une seule fois, lors de la première
 *  initialisation d'une instance RunBase. Lorsque plusieurs fichiers
 *  runs sont lus, elle n'est pas rappelée (la structure d'événement
 *  est censé rester la même).
 */
inline int RunBase::UserEventDefine ( )
  {
    #ifdef DEBUG_RUN
    DEBUG_LINE << "UserEventDefine ( ) default function" << endl;
    #endif
    return (0);
  }

/*! Fonction utilisateur par défaut d'initialisation d'un run.
 *  Cette fonction est appelée à chaque début de run.
 */
inline int RunBase::UserRunStart ( )
  {
    #ifdef DEBUG_RUN
    DEBUG_LINE << "UserRunStart ( ) default function" << endl;
    #endif
    return (0);
  }

/*! Fonction utilisateur par défaut de traitement de chaque événement.
 */
inline int RunBase::UserEvent ( )
  { return (0); }

/*! Fonction utilisateur par défaut appelée après l'incrémentation des
 *  spectres, après le traitement d'un événement.
 */
inline int RunBase::UserUpdate ( )
  { return (0); }

/*! Fonction utilisateur par défaut appelée en fin de run.
 */
inline int RunBase::UserRunStop ( )
  {
    #ifdef DEBUG_RUN1
    DEBUG1_LINE << "UserRunStop ( ) default function" << endl;
    #endif
    return (0);
  }

//======================================================================
#endif