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 <sigc++/slot.h>
  75          *   #include <iostream>
  76          *
  77          *   // Mi objeto que realiza la tarea.
  78          *   class MiRunnable: public Runnable {
  79          *       void real_run(void) { std::cout << "Corriendo." << std::endl; }
  80          *   }
  81          *
  82          *   // Puntero al objeto que realiza la tarea.
  83          *   MiRunnable* runner;
  84          *
  85          *   // Atiende la señal que indica que el objeto terminó su tarea.
  86          *   void on_finished(void) {
  87          *       runner = 0;
  88          *   }
  89          *
  90          *   // Programa principal.
  91          *   int main(void) {
  92          *       runner = new MiRunnable();
  93          *       // Conecta la señal finished para saber cuando terminó.
  94          *       runner->signal_finished().connect(SigC::slot(on_finished));
  95          *       runner->run(); // Corre en un hilo propio
  96          *       // Espera a que termine la tarea.
  97          *       while (runner) {
  98          *           sleep(1);
  99          *       }
 100          *       // No necesito liberar su memoria, se libera automáticamente.
 101          *       return 0;
 102          *   }
 103          *   \endcode
 104          *
 105          * Nótese que al correr la tarea en un hilo propio no se pueden capturar
 106          * errores con un bloque <tt>try;catch</tt>. Para reportar errores se provee
 107          * de la señal signal_error().
 108          */
 109         class Runnable {
 110
 111                 /////////////////////////////////////////////////////////////////////
 112                 // Tipos.
 113
 114                 public:
 115
 116                         /// Error.
 117                         typedef unsigned Error;
 118
 119                 /////////////////////////////////////////////////////////////////////
 120                 /// \name Señales
 121                 //@{
 122
 123                 public:
 124
 125                         /// Tipo de señal para indicar que se finalizó la tarea.
 126                         typedef SigC::Signal0<void> SignalFinished;
 127
 128                         /// Tipo de señal para indicar que hubo un error.
 129                         typedef SigC::Signal2<void, const Error&, const std::string&>
 130                                 SignalError;
 131
 132                         /// Obtiene la señal que avisa cuando la tarea es finalizada.
 133                         SignalFinished& signal_finished(void);
 134
 135                         /// Obtiene la señal que avisa que hubo un error.
 136                         SignalError& signal_error(void);
 137
 138                 //@}
 139
 140                 /////////////////////////////////////////////////////////////////////
 141                 // Atributos.
 142
 143                 private:
 144
 145                         /// Thread en el cual correr la tarea.
 146                         Glib::Thread* _thread;
 147
 148                         /// Señal que indica que se finalizó la tarea.
 149                         SignalFinished _finished;
 150
 151                         /// Señal que indica que hubo un error.
 152                         SignalError _error;
 153
 154                         /// Indica si se debe frinalizar la tarea.
 155                         bool _stop;
 156
 157                         /// Mutex para stop.
 158                         Glib::Mutex stop_mutex;
 159
 160                 /////////////////////////////////////////////////////////////////////
 161                 // Métodos.
 162
 163                 private:
 164
 165                         /**
 166                          * Corre la tarea controlando cuando termina.
 167                          *
 168                          * \param runner Objeto con la tarea a realizar.
 169                          */
 170                         static void static_run(Runnable* runner);
 171
 172                 protected:
 173
 174                         /**
 175                          * Indica si la tarea debe finalizar.
 176                          */
 177                         bool stop(void);
 178
 179                         /**
 180                          * Establece si la tarea debe finalizar.
 181                          *
 182                          * \param stop Nuevo valor.
 183                          *
 184                          * \return Valor anterior.
 185                          */
 186                         bool stop(bool stop);
 187
 188                         /**
 189                          * Realiza la terea.
 190                          */
 191                         virtual void real_run(void) throw() = 0;
 192
 193                 public:
 194
 195                         /**
 196                          * Destructor.
 197                          */
 198                         virtual ~Runnable(void);
 199
 200                         /**
 201                          * Constructor.
 202                          */
 203                         Runnable(void);
 204
 205                         /**
 206                          * Comienza la tarea.
 207                          *
 208                          * \param detach Si es true se corre en un thread propio. Si no no
 209                          *                               retorna hasta que finaliza.
 210                          */
 211                         virtual void run(bool detach = true);
 212
 213                         /**
 214                          * Finaliza la tarea.
 215                          *
 216                          * \note Para saber cuando la tarea fue finalizada puede utilizar
 217                          *       la señal signal_finished().
 218                          */
 219                         virtual void finish(void);
 220
 221
 222         };
 223
 224 }
 225
 226 }
 227
 228 #endif // PLAQUI_RUNNABLE_H