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 es 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                 /// \name Señales.
 118                 //@{
 119
 120                 public:
 121
 122                         /// Tipo de señal para indicar que se finalizó la tarea.
 123                         typedef SigC::Signal0<void> SignalFinished;
 124
 125                         /// Tipo de señal para indicar que hubo un error.
 126                         typedef SigC::Signal2<void, const Error&, const std::string&>
 127                                 SignalError;
 128
 129                         /// Obtiene la señal que avisa cuando la tarea es finalizada.
 130                         SignalFinished& signal_finished(void);
 131
 132                         /// Obtiene la señal que avisa que hubo un error.
 133                         SignalError& signal_error(void);
 134
 135                 //@}
 136
 137                 /////////////////////////////////////////////////////////////////////
 138                 // Atributos.
 139
 140                 private:
 141
 142                         /// Thread en el cual correr la tarea.
 143                         Glib::Thread* _thread;
 144
 145                         /// Señal que indica que se finalizó la tarea.
 146                         SignalFinished _finished;
 147
 148                         /// Señal que indica que hubo un error.
 149                         SignalError _error;
 150
 151                         /// Indica si se debe frinalizar la tarea.
 152                         bool _stop;
 153
 154                         /// Mutex para stop.
 155                         Glib::Mutex stop_mutex;
 156
 157                 /////////////////////////////////////////////////////////////////////
 158                 // Métodos.
 159
 160                 private:
 161
 162                         /**
 163                          * Corre la tarea controlando cuando termina.
 164                          *
 165                          * \param runner Objeto con la tarea a realizar.
 166                          */
 167                         static void static_run(Runnable* runner);
 168
 169                 protected:
 170
 171                         /**
 172                          * Indica si la tarea debe finalizar.
 173                          */
 174                         bool stop(void);
 175
 176                         /**
 177                          * Establece si la tarea debe finalizar.
 178                          *
 179                          * \param stop Nuevo valor.
 180                          *
 181                          * \return Valor anterior.
 182                          */
 183                         bool stop(bool stop);
 184
 185                         /**
 186                          * Realiza la terea.
 187                          */
 188                         virtual void real_run(void) throw() = 0;
 189
 190                 public:
 191
 192                         /**
 193                          * Destructor.
 194                          */
 195                         virtual ~Runnable(void);
 196
 197                         /**
 198                          * Constructor.
 199                          */
 200                         Runnable(void);
 201
 202                         /**
 203                          * Comienza la tarea.
 204                          *
 205                          * \param detach Si es true se corre en un thread propio. Si no no
 206                          *                               retorna hasta que finaliza.
 207                          */
 208                         virtual void run(bool detach = true);
 209
 210                         /**
 211                          * Finaliza la tarea.
 212                          *
 213                          * \note Para saber cuando la tarea fue finalizada puede utilizar
 214                          *       la señal signal_finished().
 215                          */
 216                         virtual void finish(void);
 217
 218
 219         };
 220
 221 }
 222
 223 }
 224
 225 #endif // PLAQUI_RUNNABLE_H