Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Factorize s_type and value instr class
[simgrid.git] / src / instr / instr_interface.cpp
1 /* Copyright (c) 2010-2015. The SimGrid Team.
2  * All rights reserved.                                                     */
3
4 /* This program is free software; you can redistribute it and/or modify it
5  * under the terms of the license (GNU LGPL) which comes with this package. */
6
7 #include "simgrid_config.h"
8 #include "src/instr/instr_private.h"
9 #include "src/kernel/routing/NetPoint.hpp"
10 #include "src/surf/network_interface.hpp"
11 #include "src/surf/surf_private.h"
12 #include "surf/surf.h"
13
14 typedef enum {
15   INSTR_US_DECLARE,
16   INSTR_US_SET,
17   INSTR_US_ADD,
18   INSTR_US_SUB
19 } InstrUserVariable;
20
21 XBT_LOG_NEW_DEFAULT_SUBCATEGORY (instr_api, instr, "API");
22
23 xbt_dict_t created_categories = nullptr;
24 xbt_dict_t declared_marks = nullptr;
25 xbt_dict_t user_host_variables = nullptr;
26 xbt_dict_t user_vm_variables = nullptr;
27 xbt_dict_t user_link_variables = nullptr;
28 extern xbt_dict_t trivaNodeTypes;
29 extern xbt_dict_t trivaEdgeTypes;
30
31 static xbt_dynar_t instr_dict_to_dynar (xbt_dict_t filter)
32 {
33   if (not TRACE_is_enabled() || not TRACE_needs_platform())
34     return nullptr;
35
36   xbt_dynar_t ret = xbt_dynar_new (sizeof(char*), &xbt_free_ref);
37   xbt_dict_cursor_t cursor = nullptr;
38   char *name;
39   char *value;
40   xbt_dict_foreach(filter, cursor, name, value) {
41     xbt_dynar_push_as (ret, char*, xbt_strdup(name));
42   }
43   return ret;
44 }
45
46 /** \ingroup TRACE_category
47  *  \brief Declare a new category with a random color.
48  *
49  *  This function should be used to define a user category. The category can be used to differentiate the tasks that
50  *  are created during the simulation (for example, tasks from server1, server2, or request tasks, computation tasks,
51  *  communication tasks). All resource utilization (host power and link bandwidth) will be classified according to the
52  *  task category. Tasks that do not belong to a category are not traced. The color for the category that is being
53  *  declared is random. This function has no effect if a category with the same name has been already declared.
54  *
55  * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
56  *
57  *  \param category The name of the new tracing category to be created.
58  *
59  *  \see TRACE_category_with_color, MSG_task_set_category, SD_task_set_category
60  */
61 void TRACE_category(const char *category)
62 {
63   TRACE_category_with_color (category, nullptr);
64 }
65
66 /** \ingroup TRACE_category
67  *  \brief Declare a new category with a color.
68  *
69  *  Same as #TRACE_category, but let user specify a color encoded as a RGB-like string with three floats from 0 to 1.
70  *  So, to specify a red color, pass "1 0 0" as color parameter. A light-gray color can be specified using "0.7 0.7 0.7"
71  *   as color. This function has no effect if a category with the same name has been already declared.
72  *
73  * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
74  *
75  *  \param category The name of the new tracing category to be created.
76  *  \param color The color of the category (see \ref outcomes_vizu to
77  *  know how to correctly specify the color)
78  *
79  *  \see MSG_task_set_category, SD_task_set_category
80  */
81 void TRACE_category_with_color (const char *category, const char *color)
82 {
83   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with categories */
84   if (not TRACE_is_enabled() || not TRACE_needs_platform())
85     return;
86
87   if (not(TRACE_categorized() && category != nullptr))
88     return;
89
90   //check if category is already created
91   if (xbt_dict_get_or_null(created_categories, category) != nullptr)
92     return;
93
94   xbt_dict_set (created_categories, category, xbt_strdup("1"), nullptr);
95
96   //define final_color
97   char final_color[INSTR_DEFAULT_STR_SIZE];
98   if (not color) {
99     //generate a random color
100     double red = drand48();
101     double green = drand48();
102     double blue = drand48();
103     snprintf (final_color, INSTR_DEFAULT_STR_SIZE, "%f %f %f", red, green, blue);
104   }else{
105     snprintf (final_color, INSTR_DEFAULT_STR_SIZE, "%s", color);
106   }
107
108   XBT_DEBUG("CAT,declare %s, \"%s\" \"%s\"", category, color, final_color);
109
110   //define the type of this category on top of hosts and links
111   instr_new_variable_type (category, final_color);
112 }
113
114 /** \ingroup TRACE_category
115  *  \brief Get declared categories
116  *
117  * This function should be used to get categories that were already declared with #TRACE_category or with
118  * #TRACE_category_with_color.
119  *
120  * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
121  *
122  * \return A dynar with the declared categories, must be freed with xbt_dynar_free.
123  *
124  *  \see MSG_task_set_category, SD_task_set_category
125  */
126 xbt_dynar_t TRACE_get_categories ()
127 {
128   if (not TRACE_is_enabled() || not TRACE_categorized())
129     return nullptr;
130
131   return instr_dict_to_dynar (created_categories);
132 }
133
134 /** \ingroup TRACE_mark
135  * \brief Declare a new type for tracing mark.
136  *
137  * This function declares a new Paje event type in the trace file that can be used by simulators to declare
138  * application-level marks. This function is independent of which API is used in SimGrid.
139  *
140  * \param mark_type The name of the new type.
141  *
142  * \see TRACE_mark
143  */
144 void TRACE_declare_mark(const char *mark_type)
145 {
146   /* safe switchs. tracing has to be activated and if platform is not traced, we can't deal with marks */
147   if (not TRACE_is_enabled() || not TRACE_needs_platform())
148     return;
149
150   if (not mark_type)
151     THROWF (tracing_error, 1, "mark_type is nullptr");
152
153   //check if mark_type is already declared
154   if (xbt_dict_get_or_null(declared_marks, mark_type) != nullptr) {
155     THROWF (tracing_error, 1, "mark_type with name (%s) is already declared", mark_type);
156   }
157
158   XBT_DEBUG("MARK,declare %s", mark_type);
159   PJ_type_event_new(mark_type, PJ_type_get_root());
160   xbt_dict_set (declared_marks, mark_type, xbt_strdup("1"), nullptr);
161 }
162
163 /** \ingroup TRACE_mark
164  * \brief Declare a new colored value for a previously declared mark type.
165  *
166  * This function declares a new colored value for a Paje event type in the trace file that can be used by simulators to
167  * declare application-level marks. This function is independent of which API is used in SimGrid. The color needs to be
168  * a string with three numbers separated by spaces in the range [0,1].
169  * A light-gray color can be specified using "0.7 0.7 0.7" as color. If a nullptr color is provided, the color used will
170  * be white ("1 1 1").
171  *
172  * \param mark_type The name of the new type.
173  * \param mark_value The name of the new value for this type.
174  * \param mark_color The color of the new value for this type.
175  *
176  * \see TRACE_mark
177  */
178 void TRACE_declare_mark_value_with_color (const char *mark_type, const char *mark_value, const char *mark_color)
179 {
180   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
181   if (not TRACE_is_enabled() || not TRACE_needs_platform())
182     return;
183
184   if (not mark_type)
185     THROWF (tracing_error, 1, "mark_type is nullptr");
186   if (not mark_value)
187     THROWF (tracing_error, 1, "mark_value is nullptr");
188
189   type_t type = PJ_type_get (mark_type, PJ_type_get_root());
190   if (not type) {
191     THROWF (tracing_error, 1, "mark_type with name (%s) is not declared", mark_type);
192   }
193
194   char white[INSTR_DEFAULT_STR_SIZE] = "1.0 1.0 1.0";
195   if (not mark_color)
196     mark_color = white;
197
198   XBT_DEBUG("MARK,declare_value %s %s %s", mark_type, mark_value, mark_color);
199   value rett(mark_value, mark_color, type);
200 }
201
202 /** \ingroup TRACE_mark
203  * \brief Declare a new value for a previously declared mark type.
204  *
205  * This function declares a new value for a Paje event type in the trace file that can be used by simulators to declare
206  * application-level marks. This function is independent of which API is used in SimGrid. Calling this function is the
207  * same as calling \ref TRACE_declare_mark_value_with_color with a nullptr color.
208  *
209  * \param mark_type The name of the new type.
210  * \param mark_value The name of the new value for this type.
211  *
212  * \see TRACE_mark
213  */
214 void TRACE_declare_mark_value (const char *mark_type, const char *mark_value)
215 {
216   TRACE_declare_mark_value_with_color (mark_type, mark_value, nullptr);
217 }
218
219 /**
220  * \ingroup TRACE_mark
221  * \brief Create a new instance of a tracing mark type.
222  *
223  * This function creates a mark in the trace file. The first parameter had to be previously declared using
224  * #TRACE_declare_mark, the second is the identifier for this mark instance. We recommend that the mark_value is a
225  * unique value for the whole simulation. Nevertheless, this is not a strong requirement: the trace will be valid even
226  * if there are multiple mark identifiers for the same trace.
227  *
228  * \param mark_type The name of the type for which the new instance will belong.
229  * \param mark_value The name of the new instance mark.
230  *
231  * \see TRACE_declare_mark
232  */
233 void TRACE_mark(const char *mark_type, const char *mark_value)
234 {
235   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
236   if (not TRACE_is_enabled() || not TRACE_needs_platform())
237     return;
238
239   if (not mark_type)
240     THROWF (tracing_error, 1, "mark_type is nullptr");
241   if (not mark_value)
242     THROWF (tracing_error, 1, "mark_value is nullptr");
243
244   //check if mark_type is already declared
245   type_t type = PJ_type_get (mark_type, PJ_type_get_root());
246   if (not type) {
247     THROWF (tracing_error, 1, "mark_type with name (%s) is not declared", mark_type);
248   }
249
250   XBT_DEBUG("MARK %s %s", mark_type, mark_value);
251   new NewEvent(MSG_get_clock(), PJ_container_get_root(), type, value::get(mark_value, type));
252 }
253
254 /** \ingroup TRACE_mark
255  *  \brief Get declared marks
256  *
257  * This function should be used to get marks that were already declared with #TRACE_declare_mark.
258  *
259  * \return A dynar with the declared marks, must be freed with xbt_dynar_free.
260  */
261 xbt_dynar_t TRACE_get_marks ()
262 {
263   if (not TRACE_is_enabled())
264     return nullptr;
265
266   return instr_dict_to_dynar (declared_marks);
267 }
268
269 static void instr_user_variable(double time, const char *resource, const char *variable, const char *father_type,
270                          double value, InstrUserVariable what, const char *color, xbt_dict_t filter)
271 {
272   /* safe switches. tracing has to be activated and if platform is not traced, we don't allow user variables */
273   if (not TRACE_is_enabled() || not TRACE_needs_platform())
274     return;
275
276   //check if variable is already declared
277   char *created = (char*)xbt_dict_get_or_null(filter, variable);
278   if (what == INSTR_US_DECLARE){
279     if (not created) { // not declared yet
280       xbt_dict_set (filter, variable, xbt_strdup("1"), nullptr);
281       instr_new_user_variable_type (father_type, variable, color);
282     }
283   }else{
284     if (created) { // declared, let's work
285       char valuestr[100];
286       snprintf(valuestr, 100, "%g", value);
287       container_t container = PJ_container_get(resource);
288       type_t type = PJ_type_get (variable, container->type);
289       switch (what){
290       case INSTR_US_SET:
291         new SetVariableEvent(time, container, type, value);
292         break;
293       case INSTR_US_ADD:
294         new AddVariableEvent(time, container, type, value);
295         break;
296       case INSTR_US_SUB:
297         new SubVariableEvent(time, container, type, value);
298         break;
299       default:
300         THROW_IMPOSSIBLE;
301         break;
302       }
303     }
304   }
305 }
306
307 static void instr_user_srcdst_variable(double time, const char *src, const char *dst, const char *variable,
308                               const char *father_type, double value, InstrUserVariable what)
309 {
310   sg_netpoint_t src_elm = sg_netpoint_by_name_or_null(src);
311   if (not src_elm)
312     xbt_die("Element '%s' not found!",src);
313
314   sg_netpoint_t dst_elm = sg_netpoint_by_name_or_null(dst);
315   if (not dst_elm)
316     xbt_die("Element '%s' not found!",dst);
317
318   std::vector<simgrid::surf::LinkImpl*> route;
319   simgrid::kernel::routing::NetZoneImpl::getGlobalRoute(src_elm, dst_elm, &route, nullptr);
320   for (auto link : route)
321     instr_user_variable(time, link->cname(), variable, father_type, value, what, nullptr, user_link_variables);
322 }
323
324 /** \ingroup TRACE_API
325  *  \brief Creates a file with the topology of the platform file used for the simulator.
326  *
327  *  The graph topology will have the following properties: all hosts, links and routers of the platform file are mapped
328  *  to graph nodes; routes are mapped to edges.
329  *  The platform's AS are not represented in the output.
330  *
331  *  \param filename The name of the file that will hold the graph.
332  *
333  *  \return 1 of successful, 0 otherwise.
334  */
335 int TRACE_platform_graph_export_graphviz (const char *filename)
336 {
337   /* returns 1 if successful, 0 otherwise */
338   if (not TRACE_is_enabled())
339     return 0;
340   xbt_graph_t g = instr_routing_platform_graph();
341   if (g == nullptr)
342     return 0;
343   instr_routing_platform_graph_export_graphviz (g, filename);
344   xbt_graph_free_graph(g, xbt_free_f, xbt_free_f, nullptr);
345   return 1;
346 }
347
348 /*
349  * Derived functions that use instr_user_variable and TRACE_user_srcdst_variable. They were previously defined as
350  * pre-processors directives, but were transformed into functions so the user can track them using gdb.
351  */
352
353 /* for VM variables */
354 /** \ingroup TRACE_user_variables
355  *  \brief Declare a new user variable associated to VMs.
356  *
357  *  Declare a user variable that will be associated to VMs. A user vm variable can be used to trace user variables
358  *  such as the number of tasks in a VM, the number of clients in an application (for VMs), and so on. The color
359  *  associated to this new variable will be random.
360  *
361  *  \param variable The name of the new variable to be declared.
362  *
363  *  \see TRACE_vm_variable_declare_with_color
364  */
365 void TRACE_vm_variable_declare (const char *variable)
366 {
367   instr_user_variable(0, nullptr, variable, "MSG_VM", 0, INSTR_US_DECLARE, nullptr, user_vm_variables);
368 }
369
370 /** \ingroup TRACE_user_variables
371  *  \brief Declare a new user variable associated to VMs with a color.
372  *
373  *  Same as #TRACE_vm_variable_declare, but associated a color to the newly created user host variable. The color needs
374  *  to be a string with three numbers separated by spaces in the range [0,1].
375  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
376  *
377  *  \param variable The name of the new variable to be declared.
378  *  \param color The color for the new variable.
379  */
380 void TRACE_vm_variable_declare_with_color (const char *variable, const char *color)
381 {
382    instr_user_variable(0, nullptr, variable, "MSG_VM", 0, INSTR_US_DECLARE, color, user_vm_variables);
383 }
384
385 /** \ingroup TRACE_user_variables
386  *  \brief Set the value of a variable of a host.
387  *
388  *  \param vm The name of the VM to be considered.
389  *  \param variable The name of the variable to be considered.
390  *  \param value The new value of the variable.
391  *
392  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_add, TRACE_vm_variable_sub
393  */
394 void TRACE_vm_variable_set (const char *vm, const char *variable, double value)
395 {
396   TRACE_vm_variable_set_with_time (MSG_get_clock(), vm, variable, value);
397 }
398
399 /** \ingroup TRACE_user_variables
400  *  \brief Add a value to a variable of a VM.
401  *
402  *  \param vm The name of the VM to be considered.
403  *  \param variable The name of the variable to be considered.
404  *  \param value The value to be added to the variable.
405  *
406  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_sub
407  */
408 void TRACE_vm_variable_add (const char *vm, const char *variable, double value)
409 {
410   TRACE_vm_variable_add_with_time (MSG_get_clock(), vm, variable, value);
411 }
412
413 /** \ingroup TRACE_user_variables
414  *  \brief Subtract a value from a variable of a VM.
415  *
416  *  \param vm The name of the vm to be considered.
417  *  \param variable The name of the variable to be considered.
418  *  \param value The value to be subtracted from the variable.
419  *
420  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_add
421  */
422 void TRACE_vm_variable_sub (const char *vm, const char *variable, double value)
423 {
424   TRACE_vm_variable_sub_with_time (MSG_get_clock(), vm, variable, value);
425 }
426
427 /** \ingroup TRACE_user_variables
428  *  \brief Set the value of a variable of a VM at a given timestamp.
429  *
430  *  Same as #TRACE_vm_variable_set, but let user specify  the time used to trace it. Users can specify a time that
431  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
432  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
433  *  also traced.
434  *
435  *  \param time The timestamp to be used to tag this change of value.
436  *  \param vm The name of the VM to be considered.
437  *  \param variable The name of the variable to be considered.
438  *  \param value The new value of the variable.
439  *
440  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_add_with_time, TRACE_vm_variable_sub_with_time
441  */
442 void TRACE_vm_variable_set_with_time (double time, const char *vm, const char *variable, double value)
443 {
444   instr_user_variable(time, vm, variable, "MSG_VM", value, INSTR_US_SET, nullptr, user_vm_variables);
445 }
446
447 /** \ingroup TRACE_user_variables
448  *  \brief Add a value to a variable of a VM at a given timestamp.
449  *
450  *  Same as #TRACE_vm_variable_add, but let user specify the time used to trace it. Users can specify a time that
451  *  is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
452  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
453  *  also traced.
454  *
455  *  \param time The timestamp to be used to tag this change of value.
456  *  \param vm The name of the VM to be considered.
457  *  \param variable The name of the variable to be considered.
458  *  \param value The value to be added to the variable.
459  *
460  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_sub_with_time
461  */
462 void TRACE_vm_variable_add_with_time (double time, const char *vm, const char *variable, double value)
463 {
464   instr_user_variable(time, vm, variable, "MSG_VM", value, INSTR_US_ADD, nullptr, user_vm_variables);
465 }
466
467 /** \ingroup TRACE_user_variables
468  *  \brief Subtract a value from a variable of a VM at a given timestamp.
469  *
470  *  Same as #TRACE_vm_variable_sub, but let user specify the time used to trace it. Users can specify a time that
471  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
472  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
473  *  also traced.
474  *
475  *  \param time The timestamp to be used to tag this change of value.
476  *  \param vm The name of the VM to be considered.
477  *  \param variable The name of the variable to be considered.
478  *  \param value The value to be subtracted from the variable.
479  *
480  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_add_with_time
481  */
482 void TRACE_vm_variable_sub_with_time (double time, const char *vm, const char *variable, double value)
483 {
484   instr_user_variable(time, vm, variable, "MSG_VM", value, INSTR_US_SUB, nullptr, user_vm_variables);
485 }
486
487 /* for host variables */
488 /** \ingroup TRACE_user_variables
489  *  \brief Declare a new user variable associated to hosts.
490  *
491  *  Declare a user variable that will be associated to hosts.
492  *  A user host variable can be used to trace user variables such as the number of tasks in a server, the number of
493  *  clients in an application (for hosts), and so on. The color associated to this new variable will be random.
494  *
495  *  \param variable The name of the new variable to be declared.
496  *
497  *  \see TRACE_host_variable_declare_with_color
498  */
499 void TRACE_host_variable_declare (const char *variable)
500 {
501   instr_user_variable(0, nullptr, variable, "HOST", 0, INSTR_US_DECLARE, nullptr, user_host_variables);
502 }
503
504 /** \ingroup TRACE_user_variables
505  *  \brief Declare a new user variable associated to hosts with a color.
506  *
507  *  Same as #TRACE_host_variable_declare, but associated a color to the newly created user host variable. The color
508  *  needs to be a string with three numbers separated by spaces in the range [0,1].
509  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
510  *
511  *  \param variable The name of the new variable to be declared.
512  *  \param color The color for the new variable.
513  */
514 void TRACE_host_variable_declare_with_color (const char *variable, const char *color)
515 {
516   instr_user_variable(0, nullptr, variable, "HOST", 0, INSTR_US_DECLARE, color, user_host_variables);
517 }
518
519 /** \ingroup TRACE_user_variables
520  *  \brief Set the value of a variable of a host.
521  *
522  *  \param host The name of the host to be considered.
523  *  \param variable The name of the variable to be considered.
524  *  \param value The new value of the variable.
525  *
526  *  \see TRACE_host_variable_declare, TRACE_host_variable_add, TRACE_host_variable_sub
527  */
528 void TRACE_host_variable_set (const char *host, const char *variable, double value)
529 {
530   TRACE_host_variable_set_with_time (MSG_get_clock(), host, variable, value);
531 }
532
533 /** \ingroup TRACE_user_variables
534  *  \brief Add a value to a variable of a host.
535  *
536  *  \param host The name of the host to be considered.
537  *  \param variable The name of the variable to be considered.
538  *  \param value The value to be added to the variable.
539  *
540  *  \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_sub
541  */
542 void TRACE_host_variable_add (const char *host, const char *variable, double value)
543 {
544   TRACE_host_variable_add_with_time (MSG_get_clock(), host, variable, value);
545 }
546
547 /** \ingroup TRACE_user_variables
548  *  \brief Subtract a value from a variable of a host.
549  *
550  *  \param host The name of the host to be considered.
551  *  \param variable The name of the variable to be considered.
552  *  \param value The value to be subtracted from the variable.
553  *
554  *  \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_add
555  */
556 void TRACE_host_variable_sub (const char *host, const char *variable, double value)
557 {
558   TRACE_host_variable_sub_with_time (MSG_get_clock(), host, variable, value);
559 }
560
561 /** \ingroup TRACE_user_variables
562  *  \brief Set the value of a variable of a host at a given timestamp.
563  *
564  *  Same as #TRACE_host_variable_set, but let user specify  the time used to trace it. Users can specify a time that
565  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
566  *  definition, but should be used with caution since the trace  can be inconsistent if resource utilization traces are
567  *  also traced.
568  *
569  *  \param time The timestamp to be used to tag this change of value.
570  *  \param host The name of the host to be considered.
571  *  \param variable The name of the variable to be considered.
572  *  \param value The new value of the variable.
573  *
574  *  \see TRACE_host_variable_declare, TRACE_host_variable_add_with_time, TRACE_host_variable_sub_with_time
575  */
576 void TRACE_host_variable_set_with_time (double time, const char *host, const char *variable, double value)
577 {
578   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_SET, nullptr, user_host_variables);
579 }
580
581 /** \ingroup TRACE_user_variables
582  *  \brief Add a value to a variable of a host at a given timestamp.
583  *
584  *  Same as #TRACE_host_variable_add, but let user specify the time used to trace it. Users can specify a time that
585  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
586  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
587  *  also traced.
588  *
589  *  \param time The timestamp to be used to tag this change of value.
590  *  \param host The name of the host to be considered.
591  *  \param variable The name of the variable to be considered.
592  *  \param value The value to be added to the variable.
593  *
594  *  \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_sub_with_time
595  */
596 void TRACE_host_variable_add_with_time (double time, const char *host, const char *variable, double value)
597 {
598   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_ADD, nullptr, user_host_variables);
599 }
600
601 /** \ingroup TRACE_user_variables
602  *  \brief Subtract a value from a variable of a host at a given timestamp.
603  *
604  *  Same as #TRACE_host_variable_sub, but let user specify the time used to trace it. Users can specify a time that
605  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
606  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
607  *  also traced.
608  *
609  *  \param time The timestamp to be used to tag this change of value.
610  *  \param host The name of the host to be considered.
611  *  \param variable The name of the variable to be considered.
612  *  \param value The value to be subtracted from the variable.
613  *
614  *  \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_add_with_time
615  */
616 void TRACE_host_variable_sub_with_time (double time, const char *host, const char *variable, double value)
617 {
618   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_SUB, nullptr, user_host_variables);
619 }
620
621 /** \ingroup TRACE_user_variables
622  *  \brief Get declared user host variables
623  *
624  * This function should be used to get host variables that were already declared with #TRACE_host_variable_declare or
625  * with #TRACE_host_variable_declare_with_color.
626  *
627  * \return A dynar with the declared host variables, must be freed with xbt_dynar_free.
628  */
629 xbt_dynar_t TRACE_get_host_variables ()
630 {
631   return instr_dict_to_dynar (user_host_variables);
632 }
633
634 /* for link variables */
635 /** \ingroup TRACE_user_variables
636  *  \brief Declare a new user variable associated to links.
637  *
638  *  Declare a user variable that will be associated to links.
639  *  A user link variable can be used, for example, to trace user variables such as the number of messages being
640  *  transferred through network links. The color associated to this new variable will be random.
641  *
642  *  \param variable The name of the new variable to be declared.
643  *
644  *  \see TRACE_link_variable_declare_with_color
645  */
646 void TRACE_link_variable_declare (const char *variable)
647 {
648   instr_user_variable (0, nullptr, variable, "LINK", 0, INSTR_US_DECLARE, nullptr, user_link_variables);
649 }
650
651 /** \ingroup TRACE_user_variables
652  *  \brief Declare a new user variable associated to links with a color.
653  *
654  *  Same as #TRACE_link_variable_declare, but associated a color to the newly created user link variable. The color
655  *  needs to be a string with three numbers separated by spaces in the range [0,1].
656  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
657  *
658  *  \param variable The name of the new variable to be declared.
659  *  \param color The color for the new variable.
660  */
661 void TRACE_link_variable_declare_with_color (const char *variable, const char *color)
662 {
663   instr_user_variable (0, nullptr, variable, "LINK", 0, INSTR_US_DECLARE, color, user_link_variables);
664 }
665
666 /** \ingroup TRACE_user_variables
667  *  \brief Set the value of a variable of a link.
668  *
669  *  \param link The name of the link to be considered.
670  *  \param variable The name of the variable to be considered.
671  *  \param value The new value of the variable.
672  *
673  *  \see TRACE_link_variable_declare, TRACE_link_variable_add, TRACE_link_variable_sub
674  */
675 void TRACE_link_variable_set (const char *link, const char *variable, double value)
676 {
677   TRACE_link_variable_set_with_time (MSG_get_clock(), link, variable, value);
678 }
679
680 /** \ingroup TRACE_user_variables
681  *  \brief Add a value to a variable of a link.
682  *
683  *  \param link The name of the link to be considered.
684  *  \param variable The name of the variable to be considered.
685  *  \param value The value to be added to the variable.
686  *
687  *  \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_sub
688  */
689 void TRACE_link_variable_add (const char *link, const char *variable, double value)
690 {
691   TRACE_link_variable_add_with_time (MSG_get_clock(), link, variable, value);
692 }
693
694 /** \ingroup TRACE_user_variables
695  *  \brief Subtract a value from a variable of a link.
696  *
697  *  \param link The name of the link to be considered.
698  *  \param variable The name of the variable to be considered.
699  *  \param value The value to be subtracted from the variable.
700  *
701  *  \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_add
702  */
703 void TRACE_link_variable_sub (const char *link, const char *variable, double value)
704 {
705   TRACE_link_variable_sub_with_time (MSG_get_clock(), link, variable, value);
706 }
707
708 /** \ingroup TRACE_user_variables
709  *  \brief Set the value of a variable of a link at a given timestamp.
710  *
711  *  Same as #TRACE_link_variable_set, but let user specify the time used to trace it. Users can specify a time that
712  *  is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
713  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
714  *  also traced.
715  *
716  *  \param time The timestamp to be used to tag this change of value.
717  *  \param link The name of the link to be considered.
718  *  \param variable The name of the variable to be considered.
719  *  \param value The new value of the variable.
720  *
721  *  \see TRACE_link_variable_declare, TRACE_link_variable_add_with_time, TRACE_link_variable_sub_with_time
722  */
723 void TRACE_link_variable_set_with_time (double time, const char *link, const char *variable, double value)
724 {
725   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SET, nullptr, user_link_variables);
726 }
727
728 /** \ingroup TRACE_user_variables
729  *  \brief Add a value to a variable of a link at a given timestamp.
730  *
731  *  Same as #TRACE_link_variable_add, but let user specify the time used to trace it. Users can specify a time that
732  *  is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
733  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
734  *  also traced.
735  *
736  *  \param time The timestamp to be used to tag this change of value.
737  *  \param link The name of the link to be considered.
738  *  \param variable The name of the variable to be considered.
739  *  \param value The value to be added to the variable.
740  *
741  *  \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_sub_with_time
742  */
743 void TRACE_link_variable_add_with_time (double time, const char *link, const char *variable, double value)
744 {
745   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_ADD, nullptr, user_link_variables);
746 }
747
748 /** \ingroup TRACE_user_variables
749  *  \brief Subtract a value from a variable of a link at a given timestamp.
750  *
751  *  Same as #TRACE_link_variable_sub, but let user specify the time used to trace it. Users can specify a time that
752  *  is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
753  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
754  *  also traced.
755  *
756  *  \param time The timestamp to be used to tag this change of value.
757  *  \param link The name of the link to be considered.
758  *  \param variable The name of the variable to be considered.
759  *  \param value The value to be subtracted from the variable.
760  *
761  *  \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_add_with_time
762  */
763 void TRACE_link_variable_sub_with_time (double time, const char *link, const char *variable, double value)
764 {
765   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SUB, nullptr, user_link_variables);
766 }
767
768 /* for link variables, but with src and dst used for get_route */
769 /** \ingroup TRACE_user_variables
770  *  \brief Set the value of the variable present in the links connecting source and destination.
771  *
772  *  Same as #TRACE_link_variable_set, but instead of providing the name of link to be considered, provide the source
773  *  and destination hosts. All links that are part of the route between source and destination will have the variable
774  *  set to the provided value.
775  *
776  *  \param src The name of the source host for get route.
777  *  \param dst The name of the destination host for get route.
778  *  \param variable The name of the variable to be considered.
779  *  \param value The new value of the variable.
780  *
781  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add, TRACE_link_srcdst_variable_sub
782  */
783 void TRACE_link_srcdst_variable_set (const char *src, const char *dst, const char *variable, double value)
784 {
785   TRACE_link_srcdst_variable_set_with_time (MSG_get_clock(), src, dst, variable, value);
786 }
787
788 /** \ingroup TRACE_user_variables
789  *  \brief Add a value to the variable present in the links connecting source and destination.
790  *
791  *  Same as #TRACE_link_variable_add, but instead of providing the name of link to be considered, provide the source
792  *  and destination hosts. All links that are part of the route between source and destination will have the value
793  *  passed as parameter added to the current value of the variable name to be considered.
794  *
795  *  \param src The name of the source host for get route.
796  *  \param dst The name of the destination host for get route.
797  *  \param variable The name of the variable to be considered.
798  *  \param value The value to be added to the variable.
799  *
800  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_sub
801  */
802 void TRACE_link_srcdst_variable_add (const char *src, const char *dst, const char *variable, double value)
803 {
804   TRACE_link_srcdst_variable_add_with_time (MSG_get_clock(), src, dst, variable, value);
805 }
806
807 /** \ingroup TRACE_user_variables
808  *  \brief Subtract a value from the variable present in the links connecting source and destination.
809  *
810  *  Same as #TRACE_link_variable_sub, but instead of providing the name of link to be considered, provide the source
811  *  and destination hosts. All links that are part of the route between source and destination will have the value
812  *  passed as parameter subtracted from the current value of the variable name to be considered.
813  *
814  *  \param src The name of the source host for get route.
815  *  \param dst The name of the destination host for get route.
816  *  \param variable The name of the variable to be considered.
817  *  \param value The value to be subtracted from the variable.
818  *
819  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_add
820  */
821 void TRACE_link_srcdst_variable_sub (const char *src, const char *dst, const char *variable, double value)
822 {
823   TRACE_link_srcdst_variable_sub_with_time (MSG_get_clock(), src, dst, variable, value);
824 }
825
826 /** \ingroup TRACE_user_variables
827  *  \brief Set the value of the variable present in the links connecting source and destination at a given timestamp.
828  *
829  *  Same as #TRACE_link_srcdst_variable_set, but let user specify the time used to trace it. Users can specify a time
830  *  that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
831  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
832  *  also traced.
833  *
834  *  \param time The timestamp to be used to tag this change of value.
835  *  \param src The name of the source host for get route.
836  *  \param dst The name of the destination host for get route.
837  *  \param variable The name of the variable to be considered.
838  *  \param value The new value of the variable.
839  *
840  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add_with_time, TRACE_link_srcdst_variable_sub_with_time
841  */
842 void TRACE_link_srcdst_variable_set_with_time (double time, const char *src, const char *dst, const char *variable,
843                                                double value)
844 {
845   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SET);
846 }
847
848 /** \ingroup TRACE_user_variables
849  *  \brief Add a value to the variable present in the links connecting source and destination at a given timestamp.
850  *
851  *  Same as #TRACE_link_srcdst_variable_add, but let user specify the time used to trace it. Users can specify a time
852  *  that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
853  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
854  *  also traced.
855  *
856  *  \param time The timestamp to be used to tag this change of value.
857  *  \param src The name of the source host for get route.
858  *  \param dst The name of the destination host for get route.
859  *  \param variable The name of the variable to be considered.
860  *  \param value The value to be added to the variable.
861  *
862  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_sub_with_time
863  */
864 void TRACE_link_srcdst_variable_add_with_time (double time, const char *src, const char *dst, const char *variable,
865                                                double value)
866 {
867   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_ADD);
868 }
869
870 /** \ingroup TRACE_user_variables
871  *  \brief Subtract a value from the variable present in the links connecting source and dest. at a given timestamp.
872  *
873  *  Same as #TRACE_link_srcdst_variable_sub, but let user specify the time used to trace it. Users can specify a time
874  *  that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
875  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
876  *  also traced.
877  *
878  *  \param time The timestamp to be used to tag this change of value.
879  *  \param src The name of the source host for get route.
880  *  \param dst The name of the destination host for get route.
881  *  \param variable The name of the variable to be considered.
882  *  \param value The value to be subtracted from the variable.
883  *
884  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_add_with_time
885  */
886 void TRACE_link_srcdst_variable_sub_with_time (double time, const char *src, const char *dst, const char *variable,
887                                                double value)
888 {
889   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SUB);
890 }
891
892 /** \ingroup TRACE_user_variables
893  *  \brief Get declared user link variables
894  *
895  * This function should be used to get link variables that were already declared with #TRACE_link_variable_declare or
896  * with #TRACE_link_variable_declare_with_color.
897  *
898  * \return A dynar with the declared link variables, must be freed with xbt_dynar_free.
899  */
900 xbt_dynar_t TRACE_get_link_variables ()
901 {
902   return instr_dict_to_dynar (user_link_variables);
903 }
904
905 /** \ingroup TRACE_user_variables
906  *  \brief Declare a new user state associated to hosts.
907  *
908  *  Declare a user state that will be associated to hosts.
909  *  A user host state can be used to trace application states.
910  *
911  *  \param state The name of the new state to be declared.
912  *
913  *  \see TRACE_host_state_declare_value
914  */
915 void TRACE_host_state_declare (const char *state)
916 {
917   instr_new_user_state_type("HOST", state);
918 }
919
920 /** \ingroup TRACE_user_variables
921  *  \brief Declare a new value for a user state associated to hosts.
922  *
923  *  Declare a value for a state. The color needs to be a string with 3 numbers separated by spaces in the range [0,1].
924  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
925  *
926  *  \param state The name of the new state to be declared.
927  *  \param value The name of the value
928  *  \param color The color of the value
929  *
930  *  \see TRACE_host_state_declare
931  */
932 void TRACE_host_state_declare_value (const char *state, const char *value, const char *color)
933 {
934   instr_new_value_for_user_state_type (state, value, color);
935 }
936
937 /** \ingroup TRACE_user_variables
938  *  \brief Set the user state to the given value.
939  *
940  *  Change a user state previously declared to the given value.
941  *
942  *  \param host The name of the host to be considered.
943  *  \param state The name of the state previously declared.
944  *  \param value The new value of the state.
945  *
946  *  \see TRACE_host_state_declare, TRACE_host_push_state, TRACE_host_pop_state, TRACE_host_reset_state
947  */
948 void TRACE_host_set_state(const char* host, const char* state, const char* value_str)
949 {
950   container_t container = PJ_container_get(host);
951   type_t type = PJ_type_get (state, container->type);
952   value* val =
953       value::get_or_new(value_str, nullptr, type); /* if user didn't declare a value with a color, use nullptr color */
954   new SetStateEvent(MSG_get_clock(), container, type, val);
955 }
956
957 /** \ingroup TRACE_user_variables
958  *  \brief Push a new value for a state of a given host.
959  *
960  *  Change a user state previously declared by pushing the new value to the state.
961  *
962  *  \param host The name of the host to be considered.
963  *  \param state The name of the state previously declared.
964  *  \param value The value to be pushed.
965  *
966  *  \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_pop_state, TRACE_host_reset_state
967  */
968 void TRACE_host_push_state(const char* host, const char* state, const char* value_str)
969 {
970   container_t container = PJ_container_get(host);
971   type_t type = PJ_type_get (state, container->type);
972   value* val =
973       value::get_or_new(value_str, nullptr, type); /* if user didn't declare a value with a color, use nullptr color */
974   new PushStateEvent(MSG_get_clock(), container, type, val);
975 }
976
977 /** \ingroup TRACE_user_variables
978  *  \brief Pop the last value of a state of a given host.
979  *
980  *  Change a user state previously declared by removing the last value of the state.
981  *
982  *  \param host The name of the host to be considered.
983  *  \param state The name of the state to be popped.
984  *
985  *  \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state, TRACE_host_reset_state
986  */
987 void TRACE_host_pop_state (const char *host, const char *state)
988 {
989   container_t container = PJ_container_get(host);
990   type_t type = PJ_type_get (state, container->type);
991   new PopStateEvent(MSG_get_clock(), container, type);
992 }
993
994 /** \ingroup TRACE_API
995  *  \brief Get Paje container types that can be mapped to the nodes of a graph.
996  *
997  *  This function can be used to create a user made  graph configuration file for Triva. Normally, it is used with the
998  *  functions defined in \ref TRACE_user_variables.
999  *
1000  *  \return A dynar with the types, must be freed with xbt_dynar_free.
1001  */
1002 xbt_dynar_t TRACE_get_node_types ()
1003 {
1004   return instr_dict_to_dynar (trivaNodeTypes);
1005 }
1006
1007 /** \ingroup TRACE_API
1008  *  \brief Get Paje container types that can be mapped to the edges of a graph.
1009  *
1010  *  This function can be used to create a user made graph configuration file for Triva. Normally, it is used with the
1011  *  functions defined in \ref TRACE_user_variables.
1012  *
1013  *  \return A dynar with the types, must be freed with xbt_dynar_free.
1014  */
1015 xbt_dynar_t TRACE_get_edge_types ()
1016 {
1017   return instr_dict_to_dynar (trivaEdgeTypes);
1018 }