acf21d256e15d00cbf5664124cbeb2b9c4b90ca8
[anna.git] / include / anna / core / mt / Semaphore.hpp
1 // ANNA - Anna is Not Nothingness Anymore                                                         //
2 //                                                                                                //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
4 //                                                                                                //
5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
7
8
9 #ifndef anna_core_mt_Semaphore_hpp
10 #define anna_core_mt_Semaphore_hpp
11
12 #include <semaphore.h>
13
14 #include <anna/core/functions.hpp>
15 #include <anna/core/RuntimeException.hpp>
16 #include <anna/core/mt/Safe.hpp>
17
18 namespace anna {
19
20 //class RuntimeException;
21
22 /**
23    Clase para facilitar el uso de semaforos.
24
25    Esta facilidad que nos ofrece el sistema operativo se suele usar para limitar el numero de
26    accesos a un determinado recurso.
27
28    La funcionalidad de esta clase solo estara disponible en aplicaciones multithread.
29 */
30 class Semaphore : public Safe {
31 public:
32   // Constructor
33   /**
34      Constructor.
35
36      @param count Numero de accesos simultaneos que permitimos sobre el recurso que queremos
37      compartir.
38      \param mode Modo de actuacion de esta instancia en modo ST cuando montamos una
39      seccion critca sobre este objeto. En modo MT siempre sera Mode::Normal, es decir
40      abre una seccion critica sobre este objeto, que bloqueara a cualquier otro thread
41      que intente acceder a el.
42   */
43   Semaphore(unsigned int count);
44
45   /**
46      Destructor.
47   */
48   virtual ~Semaphore();
49
50   /**
51      Notifica que desea acceder al recurso. Si se ha alcanzado la cuenta maxima de accesos
52      simultaneos el thread que invoca a este metodo quedara bloqueado mientras que algun
53      otro threads no invoque al metodo #signal.
54
55      Cada llamada a este metodo debe tener su correspondiente llamada a #signal.
56   */
57   void wait() throw(RuntimeException);
58
59   /**
60      Comprueba si se ha alcanzado la cuenta maxima de accesos simultaneos y devolvera \em
61      true si todavia es posible acceder sin quedar bloqueado o \em false en otro caso.
62   */
63   bool tryWait() throw(RuntimeException);
64
65   /**
66      Decrementa la cuenta de utilizacion del recurso, con lo que algunos de los threads
67      que puede haber esperando se desbloqueara.
68   */
69   void signal() throw(RuntimeException);
70
71   /**
72      Devuelve una cadena con informacion relevante de esta instancia.
73      \return Una cadena con informacion relevante de esta instancia.
74   */
75   virtual std::string asString() const throw();
76
77 protected:
78   /**
79     Marca el inicio del acceso seguro a este objeto.
80     \warning Cada invocacion a este metodo debe tener su correspondiente llamada al metodo #unlock.
81     Es muy aconsejable delegar las llamadas a estos metodos en una instancia Guard.
82     \return Siempre devuelve \em true;
83   */
84   void lock() throw(RuntimeException) { wait(); }
85
86   /**
87     Indica el final del acceso seguro iniciado al invocar #lock.
88     \warning Indica el final del acceso seguro iniciado al invocar #lock.
89     Es muy aconsejable delegar las llamadas a estos metodos en una instancia Guard.
90     \return Siempre devuelve \em true;
91   */
92   void unlock() throw() { signal(); }
93
94 private:
95   sem_t a_id;
96 };
97
98 } //namespace anna
99
100 #endif