Logo AND Algorithmique Numérique Distribuée

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