1 // ANNA - Anna is Not Nothingness Anymore //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo //
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 //
9 #ifndef anna_timex_Context_hpp
10 #define anna_timex_Context_hpp
15 #include <anna/core/functions.hpp>
16 #include <anna/core/mt/SafeSortedVector.hpp>
17 #include <anna/core/mt/Guard.hpp>
18 #include <anna/core/tracing/Logger.hpp>
20 #include <anna/xml/Node.hpp>
21 #include <anna/xml/Attribute.hpp>
23 #include <anna/timex/Engine.hpp>
24 #include <anna/timex/TimeEventObserver.hpp>
25 #include <anna/timex/Transaction.hpp>
27 #include <anna/core/util/Millisecond.hpp>
34 * Automatiza todas las operaciones relacionadas con el control de las transaciones de nuestra aplicación.
36 * \param Tid Indica el tipo de dato usado para ordenar las transaciones en el contexto. Es distinto del identificador
37 * de transacción. El identificador de transacción facilita su localización en los niveles de plataforma, mientras que
38 * este \em Tid facilita su localización a niveles de aplicación. Habitualmente este \em Tid será una cadena alfanumérica.
41 * \li El contexto asociado a la anna::timex::Transaction no puede ser usado al nivel de aplicación, ya que esta
42 * clase lo usa internamente.
43 * \li No se puede establecer un observador para estas transaciones ya que de otro modo el contexto no podría
44 * seguir la pista de las operaciones realizadas sobre ella.
46 * El tipo de dato Tid debe tener los operadores requeridos para actuar como clave de una map <Tid, Transaction>
48 template <typename Tid> class Context : public timex::TimeEventObserver {
51 * Crea una transacción con el identificador recibido como parámetro.
52 * En caso de que el identificador ya esté registrado en el contexto obtendremos una excepción.
54 * \param tid Identificador de aplicación de la transación.
55 * \param classType Tipo de transación que deseamos crear. Este parámetro sólo será útil en caso de que nuestra aplicación
56 * tenga que gestionar varios tipos de transaciones u operaciones.
58 * Este método terminará llamando al método #createTransaction.
60 * \return La nueva transación que ya habrá sido activada.
62 Transaction* open(const Tid& tid, const int classType = 0)
63 throw(RuntimeException) {
64 Transaction* result = NULL;
66 Guard guard(a_mutex, "timex::Context::open");
67 transaction_iterator ii = a_transactions.find(tid);
69 if(ii != a_transactions.end()) {
70 std::string msg(transaction(ii)->asString());
71 msg += " | Already in progress";
72 throw RuntimeException(msg, ANNA_FILE_LOCATION);
75 if((result = createTransaction(classType)) == NULL) {
76 std::string msg("timex::Context::createTransaction returned NULL | ClassType: ");
77 msg += functions::asString(classType);
78 throw RuntimeException(msg, ANNA_FILE_LOCATION);
81 result->setTimeout(a_timeout);
82 result->setObserver(this);
83 result->setControlPoint();
84 result->setId(anna_ptrnumber_cast(result));
85 // Copia en el contexto de la transacción la clave usada.
86 // Se usará para poder buscar por clave a la hora de liberar la transacción.
87 std::pair <transaction_iterator, bool> rr = a_transactions.insert(value_type(tid, result));
88 result->setContext((void*) &rr.first->first);
92 a_timeController.activate(result);
93 } catch(RuntimeException&) {
94 releaseTransaction(result);
99 std::string msg("timex::Context::open | ");
100 msg += result->asString();
101 Logger::information(msg, ANNA_FILE_LOCATION);
107 * Devuelve al instancia de la transación correspondiente al identificador recibido como parámetro.
108 * \param tid Identificador de aplicación de la transación.
109 * \param emode Modo de actuar en caso de que no se encuentre la transacción correspondiente al identificador.
110 * \return La transación correspondiente al identificador recibido. Puede ser NULL.
112 Transaction* find(const Tid& tid, const Exception::Mode::_v emode = Exception::Mode::Throw)
113 throw(RuntimeException) {
114 Guard guard(a_mutex, "timex::Context::find");
115 transaction_iterator ii = a_transactions.find(tid);
116 Transaction* result = (ii != a_transactions.end()) ? transaction(ii) : NULL;
119 if(Exception::Mode::Throw) {
120 std::string msg("Transaction: ");
121 msg += identifierAsString(tid);
122 msg += " | Tid not found";
123 throw RuntimeException(msg, ANNA_FILE_LOCATION);
124 } else if(Exception::Mode::Trace && Logger::isActive(Logger::Warning)) {
125 std::string msg("Transaction: ");
126 msg += identifierAsString(tid);
127 msg += " | Tid not found";
128 Logger::warning(msg, ANNA_FILE_LOCATION);
136 * Obtiene el identificador de aplicación asociado a la transación recibida como parámetro.
137 * \param transaction Puntero a la transación a procesar. Debe haber sido creada con el método #open.
138 * \return El identificador de aplicación indicado en el método #open.
140 const Tid& getIdentifier(const Transaction* transaction) const
141 throw(RuntimeException) {
142 if(transaction == NULL)
143 throw RuntimeException("timex::Context::getIdentifier | Can not work with NULL transaction", ANNA_FILE_LOCATION);
145 const void* context = transaction->getContext();
147 if(context == NULL) {
148 std::string msg("timex::Context::getIdentifier | ");
149 msg += transaction->asString();
150 msg += " | Can not work with NULL context";
151 throw RuntimeException(msg, ANNA_FILE_LOCATION);
154 return contextAsIdentifier(context);
158 * Termina la transación antes de que termine su periodo de espera.
159 * \param transaction Transación a terminar. Si fuera NULL este método no tiene ningún efecto.
161 void close(Transaction* transaction)
163 if(transaction == NULL)
167 std::string msg("timex::Context::close | ");
168 msg += transaction->asString();
169 Logger::information(msg, ANNA_FILE_LOCATION);
173 a_timeController.cancel(transaction);
174 } catch(RuntimeException& ex) {
180 * Devuelve la información relevante de esta clase en forma de documento XML.
181 * \param parent Nodo XML del que colgar la información de esta instancia.
182 * \return Un documento XML con la información relevante de esta clase.
184 virtual xml::Node* asXML(xml::Node* parent) const
186 xml::Node* result = parent->createChild("timex.Context");
187 result->createAttribute("Size", a_transactions.size());
188 result->createAttribute("AvgSize", (a_counter == 0) ? 0 : a_accSize / a_counter);
189 result->createChild("Timeout")->createAttribute("Millisecond", a_timeout.getValue());
190 result->createChild("AvgResponseTime")->createAttribute("Millisecond", (a_counter == 0) ? 0 : a_accDelay / a_counter);
195 * Obtiene la instancia del gestor del contexto asociado a la transación recibida como parámetro.
197 * \param transaction Puntero a la transación a procesar. Si no ha sido creada con el método #open
198 * el resultado de esta operación no está determinado.
199 * \return la instancia del gestor del contexto asociado a la transación recibida como parámetro.
202 static const Context* getInstance(const Transaction* transaction)
203 throw(RuntimeException) {
204 if(transaction == NULL)
205 throw RuntimeException("timex::Context::getInstance | Can not work with NULL transaction", ANNA_FILE_LOCATION);
207 return reinterpret_cast <const Context*>(transaction->getObserver());
214 * \param observerName Esta clase hera de #anna::timex::TimeEventObserver por lo que debe tener un nombre lógico
215 * \param timeController Gestor de temporización usado en la aplicación.
216 * \param timeout Duración de las transaciones creadas por el contexto. En principio todas las transaciones tendrán la misma
217 * duración, pero en próximas versiones se podría ampliar la funcionalidad para que cada transación pueda indicar su duración de
218 * forma independiente.
220 Context(const char* observerName, timex::Engine& timeController, const Millisecond& timeout) :
221 TimeEventObserver(observerName),
222 a_timeController(timeController),
224 a_counter = a_accDelay = a_accSize = 0;
228 * Método virtual puro que creará las transaciones de este contexto cuando sea necesario.
229 * Lo más adecuado sería implementar este método mediate el uso del patrón #anna::Recycler.
230 * \param classType Tipo de transación que deseamos crear. Este parámetro sólo será útil en caso de que nuestra aplicación
231 * tenga que gestionar varios tipos de transaciones u operaciones.
232 * \return Una nueva transación que puede ser usada por este contexto.
234 virtual Transaction* createTransaction(const int classType) throw() = 0;
237 * Método virtual puro que liberá el espacio asociado a la transación recibida como parámetro.
238 * Lo más adecuado sería implementar este método mediate el uso del patrón #anna::Recycler.
239 * \param transaction Transación a liberar.
241 virtual void releaseTransaction(Transaction* transaction) throw() = 0;
244 * Método virtual puro que debe devolver una \em std::string correspondiente al valor del identificador
245 * recibido como parámetro.
246 * \param tid Identificador único que la transación.
247 * \return una \em std::string correspondiente al valor del identificador recibido como parámetro.
249 virtual std::string identifierAsString(const Tid& tid) const throw() = 0;
252 * Método virtual puro que debe devolver la clave de aplicación asociada a una transación
253 * \param tid Puntero que apunta a la clave de aplicación usada para acceder a una transacción.
254 * \return La clave de aplicación correspondiente al puntero recibido como parámetro.
256 virtual const Tid& contextAsIdentifier(const void* tid) const throw() = 0;
259 typedef typename std::map <Tid, Transaction*> transaction_container;
260 typedef typename transaction_container::iterator transaction_iterator;
261 typedef typename transaction_container::value_type value_type;
263 Engine& a_timeController;
264 transaction_container a_transactions;
266 Millisecond a_timeout;
267 unsigned int a_counter;
268 unsigned int a_accDelay;
269 unsigned int a_accSize;
271 /* Método re-implementado de timex::TimeEventObserver */
272 void release(timex::TimeEvent* event)
274 Transaction* tt = static_cast <Transaction*>(event);
275 Guard guard(a_mutex, "timex::Context::release");
276 // Calcula la duración media de las transaciones de este contexto.
277 const Millisecond &delay = tt->getDelay();
278 const int size = a_transactions.size();
280 /* Si desborda el acumulador de tiempo ... */
281 if(++ a_counter == 0 || (a_accDelay + delay) < a_accDelay || (a_accSize + size) < a_accSize) {
287 const Tid& tid(contextAsIdentifier(tt->getContext()));
289 if(a_transactions.erase(tid) == 0) {
290 std::string msg("Transaction: ");
291 msg += identifierAsString(tid);
292 msg += " | Tid can not be erased from map";
293 Logger::warning(msg, ANNA_FILE_LOCATION);
296 releaseTransaction(tt);
298 a_accSize += a_transactions.size();
301 static Transaction* transaction(transaction_iterator ii) throw() { return ii->second; }