Server/include/plaqui/server/runnable.h

   1 // vim: set noexpandtab tabstop=4 shiftwidth=4:
   2 //----------------------------------------------------------------------------
   3 //                                  PlaQui
   4 //----------------------------------------------------------------------------
   5 // This file is part of PlaQui.
   6 //
   7 // PlaQui is free software; you can redistribute it and/or modify it under the
   8 // terms of the GNU General Public License as published by the Free Software
   9 // Foundation; either version 2 of the License, or (at your option) any later
  10 // version.
  11 //
  12 // PlaQui is distributed in the hope that it will be useful, but WITHOUT ANY
  13 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  14 // FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  15 // details.
  16 //
  17 // You should have received a copy of the GNU General Public License along
  18 // with PlaQui; if not, write to the Free Software Foundation, Inc., 59 Temple
  19 // Place, Suite 330, Boston, MA  02111-1307  USA
  20 //----------------------------------------------------------------------------
  21 // Creado:  Sat Oct 18 20:55:08 2003
  22 // Autores: Leandro Lucarella <llucare@fi.uba.ar>
  23 //----------------------------------------------------------------------------
  24 //
  25 // $Id$
  26 //
  27
  28 #ifndef PLAQUI_RUNNABLE_H
  29 #define PLAQUI_RUNNABLE_H
  30
  31 #include <glibmm/thread.h>
  32 #include <sigc++/signal.h>
  33
  34 namespace PlaQui {
  35
  36 namespace Server {
  37
  38         /**
  39          * Objeto cuya función principal es realizar una tarea puntual.
  40          *
  41          * Esta el la clase base para todos objetos que realizan una tarea, ya sea
  42          * en un hilo (<em>thread</em>) propio o no. Al tener esta flexibilidad hay
  43          * dos formas típicas de usarlo cuyo punto en común es implementar una
  44          * subclase (ya que esta clase es abstracta) y sobreescribir el método
  45          * privado real_run(). Una vez hecho esto hay dos opciones más comunes
  46          * según se lo corra en un thread o no:
  47          * - Para correrlo en el hilo principal (esperando que termine de
  48          *   ejecutarse) generalmente basta con crear el objeto de forma estática y
  49          *   llamar a su método run():
  50          *   \code
  51          *   #include "runnable.h"
  52          *   #include <iostream>
  53          *
  54          *   // Mi objeto que realiza la tarea.
  55          *   class MiRunnable: public Runnable {
  56          *       void real_run(void) { std::cout << "Corriendo." << std::endl; }
  57          *   }
  58          *
  59          *   // Programa principal.
  60          *   int main(void) {
  61          *       MiRunnable runner;
  62          *       runner.run(false); // Corre en el hilo principal
  63          *       return 0;
  64          *   }
  65          *   \endcode
  66          * - Para correrlo en el hilo propio el proceso es un poco más complejo, en
  67          *   especial si se necesita saber cuando finalizó. Si esto no fuera
  68          *   necesario, basta con crear el objeto dinámicamente y correr su método
  69          *   run(). El objeto se libera automáticamente cuando termina su tarea.
  70          *   Si es necesario saber cuando termina, se puede usar la señal
  71          *   signal_finished(). El caso típico sería:
  72          *   \code
  73          *   #include "runnable.h"
  74          *   #include <iostream>
  75          *
  76          *   // Mi objeto que realiza la tarea.
  77          *   class MiRunnable: public Runnable {
  78          *       void real_run(void) { std::cout << "Corriendo." << std::endl; }
  79          *   }
  80          *
  81          *   // Puntero al objeto que realiza la tarea.
  82          *   MiRunnable* runner;
  83          *
  84          *   // Atiende la señal que indica que el objeto terminó su tarea.
  85          *   void on_finished(void) {
  86          *       runner = 0;
  87          *   }
  88          *
  89          *   // Programa principal.
  90          *   int main(void) {
  91          *       runner = new MiRunnable();
  92          *       runner->run(); // Corre en un hilo propio
  93          *       // Espera a que termine la tarea.
  94          *       while (runner) {
  95          *           sleep(1);
  96          *       }
  97          *       // No necesito liberar su memoria, se libera automáticamente.
  98          *       return 0;
  99          *   }
 100          *   \endcode
 101          *
 102          * Nótese que al correr la tarea en un hilo propio no se pueden capturar
 103          * errores con un bloque <tt>try;catch</tt>. Para reportar errores se provee
 104          * de la señal signal_error().
 105          */
 106         class Runnable {
 107
 108                 /////////////////////////////////////////////////////////////////////
 109                 // Tipos.
 110
 111                 public:
 112
 113                         /// Error.
 114                         typedef unsigned Error;
 115
 116                 /////////////////////////////////////////////////////////////////////
 117                 // Atributos.
 118
 119                 private:
 120
 121                         /// Thread en el cual correr la tarea.
 122                         Glib::Thread* _thread;
 123
 124                         /// Señal que indica que se finalizó la tarea.
 125                         SignalFinished _finished;
 126
 127                         /// Señal que indica que hubo un error.
 128                         SignalError _error;
 129
 130                         /// Indica si se debe frinalizar la tarea.
 131                         bool _stop;
 132
 133                         /// Mutex para stop.
 134                         Glib::Mutex stop_mutex;
 135
 136                 /////////////////////////////////////////////////////////////////////
 137                 // Métodos.
 138
 139                 private:
 140
 141                         /**
 142                          * Corre la tarea controlando cuando termina.
 143                          *
 144                          * \param runner Objeto con la tarea a realizar.
 145                          */
 146                         static void static_run(Runnable* runner);
 147
 148                 protected:
 149
 150                         /**
 151                          * Indica si la tarea debe finalizar.
 152                          */
 153                         bool stop(void);
 154
 155                         /**
 156                          * Establece si la tarea debe finalizar.
 157                          *
 158                          * \param stop Nuevo valor.
 159                          *
 160                          * \return Valor anterior.
 161                          */
 162                         bool stop(bool stop);
 163
 164                         /**
 165                          * Realiza la terea.
 166                          */
 167                         virtual void real_run(void) throw() = 0;
 168
 169                 public:
 170
 171                         /**
 172                          * Destructor.
 173                          */
 174                         virtual ~Runnable(void);
 175
 176                         /**
 177                          * Constructor.
 178                          */
 179                         Runnable(void);
 180
 181                         /**
 182                          * Comienza la tarea.
 183                          *
 184                          * \param detach Si es true se corre en un thread propio. Si no no
 185                          *                               retorna hasta que finaliza.
 186                          */
 187                         virtual void run(bool detach = true);
 188
 189                         /**
 190                          * Finaliza la tarea.
 191                          *
 192                          * \note Para saber cuando la tarea fue finalizada puede utilizar
 193                          *       la señal signal_finished().
 194                          */
 195                         virtual void finish(void);
 196
 197                         /////////////////////////////////////////////////////////////////
 198                         /// \name Señales.
 199                         //@{
 200
 201                         /// Tipo de señal para indicar que se finalizó la tarea.
 202                         typedef SigC::Signal0<void> SignalFinished;
 203
 204                         /// Tipo de señal para indicar que hubo un error.
 205                         typedef SigC::Signal2<void, const Error&, const std::string&>
 206                                 SignalError;
 207
 208                         /// Obtiene la señal que avisa cuando la tarea es finalizada.
 209                         SignalFinished& signal_finished(void);
 210
 211                         /// Obtiene la señal que avisa que hubo un error.
 212                         SignalError& signal_error(void);
 213
 214                         //@}
 215
 216         };
 217
 218 }
 219
 220 }
 221
 222 #endif // PLAQUI_RUNNABLE_H