Se mejora el codo (para que el color siga la curva).

[z.facultad/75.42/plaqui.git] / Server / include / plaqui / server / runnable.h

diff --git a/Server/include/plaqui/server/runnable.h b/Server/include/plaqui/server/runnable.h
index 39a221f26a684bc1569c6930a9529b42d6f92f11..b1d169d3323109926a0e40b48f10a881cf130f84 100644 (file)
--- a/Server/include/plaqui/server/runnable.h
+++ b/Server/include/plaqui/server/runnable.h
@@ -29,27 +29,170 @@
 #define PLAQUI_RUNNABLE_H
 
 #include <glibmm/thread.h>
 #define PLAQUI_RUNNABLE_H
 
 #include <glibmm/thread.h>

+#include <sigc++/signal.h>

 
 

-namespace Plaqui {
+namespace PlaQui {

 
 

-       /// ealizauna tarea (generalmente en un thread).
+namespace Server {
+
+       /**
+        * Objeto cuya función principal es realizar una tarea puntual.
+        *
+        * Esta es la clase base para todos objetos que realizan una tarea, ya sea
+        * en un hilo (<em>thread</em>) propio o no. Al tener esta flexibilidad hay
+        * dos formas típicas de usarlo cuyo punto en común es implementar una
+        * subclase (ya que esta clase es abstracta) y sobreescribir el método
+        * privado real_run(). Una vez hecho esto hay dos opciones más comunes
+        * según se lo corra en un thread o no:
+        * - Para correrlo en el hilo principal (esperando que termine de
+        *   ejecutarse) generalmente basta con crear el objeto de forma estática y
+        *   llamar a su método run():
+        *   \code
+        *   #include "runnable.h"
+        *   #include <iostream>
+        *
+        *   // Mi objeto que realiza la tarea.
+        *   class MiRunnable: public Runnable {
+        *       void real_run(void) { std::cout << "Corriendo." << std::endl; }
+        *   }
+        *
+        *   // Programa principal.
+        *   int main(void) {
+        *       MiRunnable runner;
+        *       runner.run(false); // Corre en el hilo principal
+        *       return 0;
+        *   }
+        *   \endcode
+        * - Para correrlo en el hilo propio el proceso es un poco más complejo, en
+        *   especial si se necesita saber cuando finalizó. Si esto no fuera
+        *   necesario, basta con crear el objeto dinámicamente y correr su método
+        *   run(). El objeto se libera automáticamente cuando termina su tarea.
+        *   Si es necesario saber cuando termina, se puede usar la señal
+        *   signal_finished(). El caso típico sería:
+        *   \code
+        *   #include "runnable.h"
+        *   #include <iostream>
+        *
+        *   // Mi objeto que realiza la tarea.
+        *   class MiRunnable: public Runnable {
+        *       void real_run(void) { std::cout << "Corriendo." << std::endl; }
+        *   }
+        *
+        *   // Puntero al objeto que realiza la tarea.
+        *   MiRunnable* runner;
+        *
+        *   // Atiende la señal que indica que el objeto terminó su tarea.
+        *   void on_finished(void) {
+        *       runner = 0;
+        *   }
+        *
+        *   // Programa principal.
+        *   int main(void) {
+        *       runner = new MiRunnable();
+        *       runner->run(); // Corre en un hilo propio
+        *       // Espera a que termine la tarea.
+        *       while (runner) {
+        *           sleep(1);
+        *       }
+        *       // No necesito liberar su memoria, se libera automáticamente.
+        *       return 0;
+        *   }
+        *   \endcode
+        *
+        * Nótese que al correr la tarea en un hilo propio no se pueden capturar
+        * errores con un bloque <tt>try;catch</tt>. Para reportar errores se provee
+        * de la señal signal_error().
+        */

        class Runnable {
 
        class Runnable {
 

+               /////////////////////////////////////////////////////////////////////
+               // Tipos.
+
+               public:
+
+                       /// Error.
+                       typedef unsigned Error;
+
+               /////////////////////////////////////////////////////////////////////
+               /// \name Señales.
+               //@{
+
+               public:
+
+                       /// Tipo de señal para indicar que se finalizó la tarea.
+                       typedef SigC::Signal0<void> SignalFinished;
+
+                       /// Tipo de señal para indicar que hubo un error.
+                       typedef SigC::Signal2<void, const Error&, const std::string&>
+                               SignalError;
+
+                       /// Obtiene la señal que avisa cuando la tarea es finalizada.
+                       SignalFinished& signal_finished(void);
+
+                       /// Obtiene la señal que avisa que hubo un error.
+                       SignalError& signal_error(void);
+
+               //@}
+
+               /////////////////////////////////////////////////////////////////////
+               // Atributos.
+
+               private:
+
+                       /// Thread en el cual correr la tarea.
+                       Glib::Thread* _thread;
+
+                       /// Señal que indica que se finalizó la tarea.
+                       SignalFinished _finished;
+
+                       /// Señal que indica que hubo un error.
+                       SignalError _error;
+
+                       /// Indica si se debe frinalizar la tarea.
+                       bool _stop;
+
+                       /// Mutex para stop.
+                       Glib::Mutex stop_mutex;
+
+               /////////////////////////////////////////////////////////////////////
+               // Métodos.
+

                private:
                private:

-                       // Thread en el cual correr la tarea.
-                       Glib::Thread* thread;
+
+                       /**
+                        * Corre la tarea controlando cuando termina.
+                        *
+                        * \param runner Objeto con la tarea a realizar.
+                        */
+                       static void static_run(Runnable* runner);

 
                protected:
 
 
                protected:
 

-                       /// Realiza la terea.
-                       virtual void real_run(void) = 0;
+                       /**
+                        * Indica si la tarea debe finalizar.
+                        */
+                       bool stop(void);
+
+                       /**
+                        * Establece si la tarea debe finalizar.
+                        *
+                        * \param stop Nuevo valor.
+                        *
+                        * \return Valor anterior.
+                        */
+                       bool stop(bool stop);
+
+                       /**
+                        * Realiza la terea.
+                        */
+                       virtual void real_run(void) throw() = 0;

 
                public:
 
                        /**
                         * Destructor.
                         */
 
                public:
 
                        /**
                         * Destructor.
                         */

-                       virtual ~Runnable(void) {}
+                       virtual ~Runnable(void);

 
                        /**
                         * Constructor.
 
                        /**
                         * Constructor.


@@ -57,15 +200,26 @@ namespace Plaqui {
                        Runnable(void);
 
                        /**
                        Runnable(void);
 
                        /**

-                        * Comienza la tares.
+                        * Comienza la tarea.

                         *
                         * \param detach Si es true se corre en un thread propio. Si no no
                         *                               retorna hasta que finaliza.
                         */
                        virtual void run(bool detach = true);
 
                         *
                         * \param detach Si es true se corre en un thread propio. Si no no
                         *                               retorna hasta que finaliza.
                         */
                        virtual void run(bool detach = true);
 

+                       /**
+                        * Finaliza la tarea.
+                        *
+                        * \note Para saber cuando la tarea fue finalizada puede utilizar
+                        *       la señal signal_finished().
+                        */
+                       virtual void finish(void);
+
+

        };
 
 }
 
        };
 
 }
 

+}
+

 #endif // PLAQUI_RUNNABLE_H
 #endif // PLAQUI_RUNNABLE_H