Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
no need for a lib to store the netcards. A dict is easier
[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/NetCard.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 (!TRACE_is_enabled() || !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 (!TRACE_is_enabled() || !TRACE_needs_platform())
85     return;
86
87   if (!(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 (!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 (!TRACE_is_enabled() || !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 (!TRACE_is_enabled() || !TRACE_needs_platform())
148     return;
149
150   if (!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 (!TRACE_is_enabled() || !TRACE_needs_platform())
182     return;
183
184   if (!mark_type)
185     THROWF (tracing_error, 1, "mark_type is nullptr");
186   if (!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 (!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 (!mark_color)
196     mark_color = white;
197
198   XBT_DEBUG("MARK,declare_value %s %s %s", mark_type, mark_value, mark_color);
199   PJ_value_new (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 (!TRACE_is_enabled() || !TRACE_needs_platform())
237     return;
238
239   if (!mark_type)
240     THROWF (tracing_error, 1, "mark_type is nullptr");
241   if (!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 (!type){
247     THROWF (tracing_error, 1, "mark_type with name (%s) is not declared", mark_type);
248   }
249
250   val_t value = PJ_value_get (mark_value, type);
251   XBT_DEBUG("MARK %s %s", mark_type, mark_value);
252   new_pajeNewEvent (MSG_get_clock(), PJ_container_get_root(), type, value);
253 }
254
255 /** \ingroup TRACE_mark
256  *  \brief Get declared marks
257  *
258  * This function should be used to get marks that were already declared with #TRACE_declare_mark.
259  *
260  * \return A dynar with the declared marks, must be freed with xbt_dynar_free.
261  */
262 xbt_dynar_t TRACE_get_marks ()
263 {
264   if (!TRACE_is_enabled())
265     return nullptr;
266
267   return instr_dict_to_dynar (declared_marks);
268 }
269
270 static void instr_user_variable(double time, const char *resource, const char *variable, const char *father_type,
271                          double value, InstrUserVariable what, const char *color, xbt_dict_t filter)
272 {
273   /* safe switches. tracing has to be activated and if platform is not traced, we don't allow user variables */
274   if (!TRACE_is_enabled() || !TRACE_needs_platform())
275     return;
276
277   //check if variable is already declared
278   char *created = (char*)xbt_dict_get_or_null(filter, variable);
279   if (what == INSTR_US_DECLARE){
280     if (created){//already declared
281       return;
282     }else{
283       xbt_dict_set (filter, variable, xbt_strdup("1"), nullptr);
284       instr_new_user_variable_type (father_type, variable, color);
285     }
286   }else{
287     if (!created){//not declared, ignore
288       return;
289     } else {
290       char valuestr[100];
291       snprintf(valuestr, 100, "%g", value);
292       container_t container = PJ_container_get(resource);
293       type_t type = PJ_type_get (variable, container->type);
294       switch (what){
295       case INSTR_US_SET:
296         new_pajeSetVariable(time, container, type, value);
297         break;
298       case INSTR_US_ADD:
299         new_pajeAddVariable(time, container, type, value);
300         break;
301       case INSTR_US_SUB:
302         new_pajeSubVariable(time, container, type, value);
303         break;
304       default:
305         THROW_IMPOSSIBLE;
306         break;
307       }
308     }
309   }
310 }
311
312 static void instr_user_srcdst_variable(double time, const char *src, const char *dst, const char *variable,
313                               const char *father_type, double value, InstrUserVariable what)
314 {
315   sg_netcard_t src_elm = sg_netcard_by_name_or_null(src);
316   if(!src_elm)
317     xbt_die("Element '%s' not found!",src);
318
319   sg_netcard_t dst_elm = sg_netcard_by_name_or_null(dst);
320   if(!dst_elm)
321     xbt_die("Element '%s' not found!",dst);
322
323   std::vector<Link*> route;
324   simgrid::kernel::routing::NetZoneImpl::getGlobalRoute(src_elm, dst_elm, &route, nullptr);
325   for (auto link : route)
326     instr_user_variable (time, link->getName(), variable, father_type, value, what, nullptr, user_link_variables);
327 }
328
329 /** \ingroup TRACE_API
330  *  \brief Creates a file with the topology of the platform file used for the simulator.
331  *
332  *  The graph topology will have the following properties: all hosts, links and routers of the platform file are mapped
333  *  to graph nodes; routes are mapped to edges.
334  *  The platform's AS are not represented in the output.
335  *
336  *  \param filename The name of the file that will hold the graph.
337  *
338  *  \return 1 of successful, 0 otherwise.
339  */
340 int TRACE_platform_graph_export_graphviz (const char *filename)
341 {
342   /* returns 1 if successful, 0 otherwise */
343   if (!TRACE_is_enabled())
344     return 0;
345   xbt_graph_t g = instr_routing_platform_graph();
346   if (g == nullptr)
347     return 0;
348   instr_routing_platform_graph_export_graphviz (g, filename);
349   xbt_graph_free_graph(g, xbt_free_f, xbt_free_f, nullptr);
350   return 1;
351 }
352
353 /*
354  * Derived functions that use instr_user_variable and TRACE_user_srcdst_variable. They were previously defined as
355  * pre-processors directives, but were transformed into functions so the user can track them using gdb.
356  */
357
358 /* for VM variables */
359 /** \ingroup TRACE_user_variables
360  *  \brief Declare a new user variable associated to VMs.
361  *
362  *  Declare a user variable that will be associated to VMs. A user vm variable can be used to trace user variables
363  *  such as the number of tasks in a VM, the number of clients in an application (for VMs), and so on. The color
364  *  associated to this new variable will be random.
365  *
366  *  \param variable The name of the new variable to be declared.
367  *
368  *  \see TRACE_vm_variable_declare_with_color
369  */
370 void TRACE_vm_variable_declare (const char *variable)
371 {
372   instr_user_variable(0, nullptr, variable, "MSG_VM", 0, INSTR_US_DECLARE, nullptr, user_vm_variables);
373 }
374
375 /** \ingroup TRACE_user_variables
376  *  \brief Declare a new user variable associated to VMs with a color.
377  *
378  *  Same as #TRACE_vm_variable_declare, but associated a color to the newly created user host variable. The color needs
379  *  to be a string with three numbers separated by spaces in the range [0,1].
380  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
381  *
382  *  \param variable The name of the new variable to be declared.
383  *  \param color The color for the new variable.
384  */
385 void TRACE_vm_variable_declare_with_color (const char *variable, const char *color)
386 {
387    instr_user_variable(0, nullptr, variable, "MSG_VM", 0, INSTR_US_DECLARE, color, user_vm_variables);
388 }
389
390 /** \ingroup TRACE_user_variables
391  *  \brief Set the value of a variable of a host.
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 new value of the variable.
396  *
397  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_add, TRACE_vm_variable_sub
398  */
399 void TRACE_vm_variable_set (const char *vm, const char *variable, double value)
400 {
401   TRACE_vm_variable_set_with_time (MSG_get_clock(), vm, variable, value);
402 }
403
404 /** \ingroup TRACE_user_variables
405  *  \brief Add a value to 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 added to the variable.
410  *
411  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_sub
412  */
413 void TRACE_vm_variable_add (const char *vm, const char *variable, double value)
414 {
415   TRACE_vm_variable_add_with_time (MSG_get_clock(), vm, variable, value);
416 }
417
418 /** \ingroup TRACE_user_variables
419  *  \brief Subtract a value from a variable of a VM.
420  *
421  *  \param vm The name of the vm to be considered.
422  *  \param variable The name of the variable to be considered.
423  *  \param value The value to be subtracted from the variable.
424  *
425  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_add
426  */
427 void TRACE_vm_variable_sub (const char *vm, const char *variable, double value)
428 {
429   TRACE_vm_variable_sub_with_time (MSG_get_clock(), vm, variable, value);
430 }
431
432 /** \ingroup TRACE_user_variables
433  *  \brief Set the value of a variable of a VM at a given timestamp.
434  *
435  *  Same as #TRACE_vm_variable_set, but let user specify  the time used to trace it. Users can specify a time that
436  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
437  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
438  *  also traced.
439  *
440  *  \param time The timestamp to be used to tag this change of value.
441  *  \param vm The name of the VM to be considered.
442  *  \param variable The name of the variable to be considered.
443  *  \param value The new value of the variable.
444  *
445  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_add_with_time, TRACE_vm_variable_sub_with_time
446  */
447 void TRACE_vm_variable_set_with_time (double time, const char *vm, const char *variable, double value)
448 {
449   instr_user_variable(time, vm, variable, "MSG_VM", value, INSTR_US_SET, nullptr, user_vm_variables);
450 }
451
452 /** \ingroup TRACE_user_variables
453  *  \brief Add a value to a variable of a VM at a given timestamp.
454  *
455  *  Same as #TRACE_vm_variable_add, but let user specify the time used to trace it. Users can specify a time that
456  *  is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
457  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
458  *  also traced.
459  *
460  *  \param time The timestamp to be used to tag this change of value.
461  *  \param vm The name of the VM to be considered.
462  *  \param variable The name of the variable to be considered.
463  *  \param value The value to be added to the variable.
464  *
465  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_sub_with_time
466  */
467 void TRACE_vm_variable_add_with_time (double time, const char *vm, const char *variable, double value)
468 {
469   instr_user_variable(time, vm, variable, "MSG_VM", value, INSTR_US_ADD, nullptr, user_vm_variables);
470 }
471
472 /** \ingroup TRACE_user_variables
473  *  \brief Subtract a value from a variable of a VM at a given timestamp.
474  *
475  *  Same as #TRACE_vm_variable_sub, but let user specify the time used to trace it. Users can specify a time that
476  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
477  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
478  *  also traced.
479  *
480  *  \param time The timestamp to be used to tag this change of value.
481  *  \param vm The name of the VM to be considered.
482  *  \param variable The name of the variable to be considered.
483  *  \param value The value to be subtracted from the variable.
484  *
485  *  \see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_add_with_time
486  */
487 void TRACE_vm_variable_sub_with_time (double time, const char *vm, const char *variable, double value)
488 {
489   instr_user_variable(time, vm, variable, "MSG_VM", value, INSTR_US_SUB, nullptr, user_vm_variables);
490 }
491
492 /** \ingroup TRACE_user_variables
493  *  \brief Get declared user vm variables
494  *
495  * This function should be used to get VM variables that were already declared with #TRACE_vm_variable_declare or with
496  * #TRACE_vm_variable_declare_with_color.
497  *
498  * \return A dynar with the declared host variables, must be freed with xbt_dynar_free.
499  */
500 xbt_dynar_t TRACE_get_vm_variables ()
501 {
502   return instr_dict_to_dynar (user_vm_variables);
503 }
504
505 /* for host variables */
506 /** \ingroup TRACE_user_variables
507  *  \brief Declare a new user variable associated to hosts.
508  *
509  *  Declare a user variable that will be associated to hosts.
510  *  A user host variable can be used to trace user variables such as the number of tasks in a server, the number of
511  *  clients in an application (for hosts), and so on. The color associated to this new variable will be random.
512  *
513  *  \param variable The name of the new variable to be declared.
514  *
515  *  \see TRACE_host_variable_declare_with_color
516  */
517 void TRACE_host_variable_declare (const char *variable)
518 {
519   instr_user_variable(0, nullptr, variable, "HOST", 0, INSTR_US_DECLARE, nullptr, user_host_variables);
520 }
521
522 /** \ingroup TRACE_user_variables
523  *  \brief Declare a new user variable associated to hosts with a color.
524  *
525  *  Same as #TRACE_host_variable_declare, but associated a color to the newly created user host variable. The color
526  *  needs to be a string with three numbers separated by spaces in the range [0,1].
527  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
528  *
529  *  \param variable The name of the new variable to be declared.
530  *  \param color The color for the new variable.
531  */
532 void TRACE_host_variable_declare_with_color (const char *variable, const char *color)
533 {
534   instr_user_variable(0, nullptr, variable, "HOST", 0, INSTR_US_DECLARE, color, user_host_variables);
535 }
536
537 /** \ingroup TRACE_user_variables
538  *  \brief Set the value of a variable of a host.
539  *
540  *  \param host The name of the host to be considered.
541  *  \param variable The name of the variable to be considered.
542  *  \param value The new value of the variable.
543  *
544  *  \see TRACE_host_variable_declare, TRACE_host_variable_add, TRACE_host_variable_sub
545  */
546 void TRACE_host_variable_set (const char *host, const char *variable, double value)
547 {
548   TRACE_host_variable_set_with_time (MSG_get_clock(), host, variable, value);
549 }
550
551 /** \ingroup TRACE_user_variables
552  *  \brief Add a value to a variable of a host.
553  *
554  *  \param host The name of the host to be considered.
555  *  \param variable The name of the variable to be considered.
556  *  \param value The value to be added to the variable.
557  *
558  *  \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_sub
559  */
560 void TRACE_host_variable_add (const char *host, const char *variable, double value)
561 {
562   TRACE_host_variable_add_with_time (MSG_get_clock(), host, variable, value);
563 }
564
565 /** \ingroup TRACE_user_variables
566  *  \brief Subtract a value from a variable of a host.
567  *
568  *  \param host The name of the host to be considered.
569  *  \param variable The name of the variable to be considered.
570  *  \param value The value to be subtracted from the variable.
571  *
572  *  \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_add
573  */
574 void TRACE_host_variable_sub (const char *host, const char *variable, double value)
575 {
576   TRACE_host_variable_sub_with_time (MSG_get_clock(), host, variable, value);
577 }
578
579 /** \ingroup TRACE_user_variables
580  *  \brief Set the value of a variable of a host at a given timestamp.
581  *
582  *  Same as #TRACE_host_variable_set, but let user specify  the time used to trace it. Users can specify a time that
583  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
584  *  definition, but should be used with caution since the trace  can be inconsistent if resource utilization traces are
585  *  also traced.
586  *
587  *  \param time The timestamp to be used to tag this change of value.
588  *  \param host The name of the host to be considered.
589  *  \param variable The name of the variable to be considered.
590  *  \param value The new value of the variable.
591  *
592  *  \see TRACE_host_variable_declare, TRACE_host_variable_add_with_time, TRACE_host_variable_sub_with_time
593  */
594 void TRACE_host_variable_set_with_time (double time, const char *host, const char *variable, double value)
595 {
596   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_SET, nullptr, user_host_variables);
597 }
598
599 /** \ingroup TRACE_user_variables
600  *  \brief Add a value to a variable of a host at a given timestamp.
601  *
602  *  Same as #TRACE_host_variable_add, but let user specify the time used to trace it. Users can specify a time that
603  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
604  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
605  *  also traced.
606  *
607  *  \param time The timestamp to be used to tag this change of value.
608  *  \param host The name of the host to be considered.
609  *  \param variable The name of the variable to be considered.
610  *  \param value The value to be added to the variable.
611  *
612  *  \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_sub_with_time
613  */
614 void TRACE_host_variable_add_with_time (double time, const char *host, const char *variable, double value)
615 {
616   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_ADD, nullptr, user_host_variables);
617 }
618
619 /** \ingroup TRACE_user_variables
620  *  \brief Subtract a value from a variable of a host at a given timestamp.
621  *
622  *  Same as #TRACE_host_variable_sub, but let user specify the time used to trace it. Users can specify a time that
623  *  is not the simulated clock time as defined by the core  simulator. This allows a fine-grain control of time
624  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
625  *  also traced.
626  *
627  *  \param time The timestamp to be used to tag this change of value.
628  *  \param host The name of the host to be considered.
629  *  \param variable The name of the variable to be considered.
630  *  \param value The value to be subtracted from the variable.
631  *
632  *  \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_add_with_time
633  */
634 void TRACE_host_variable_sub_with_time (double time, const char *host, const char *variable, double value)
635 {
636   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_SUB, nullptr, user_host_variables);
637 }
638
639 /** \ingroup TRACE_user_variables
640  *  \brief Get declared user host variables
641  *
642  * This function should be used to get host variables that were already declared with #TRACE_host_variable_declare or
643  * with #TRACE_host_variable_declare_with_color.
644  *
645  * \return A dynar with the declared host variables, must be freed with xbt_dynar_free.
646  */
647 xbt_dynar_t TRACE_get_host_variables ()
648 {
649   return instr_dict_to_dynar (user_host_variables);
650 }
651
652 /* for link variables */
653 /** \ingroup TRACE_user_variables
654  *  \brief Declare a new user variable associated to links.
655  *
656  *  Declare a user variable that will be associated to links.
657  *  A user link variable can be used, for example, to trace user variables such as the number of messages being
658  *  transferred through network links. The color associated to this new variable will be random.
659  *
660  *  \param variable The name of the new variable to be declared.
661  *
662  *  \see TRACE_link_variable_declare_with_color
663  */
664 void TRACE_link_variable_declare (const char *variable)
665 {
666   instr_user_variable (0, nullptr, variable, "LINK", 0, INSTR_US_DECLARE, nullptr, user_link_variables);
667 }
668
669 /** \ingroup TRACE_user_variables
670  *  \brief Declare a new user variable associated to links with a color.
671  *
672  *  Same as #TRACE_link_variable_declare, but associated a color to the newly created user link variable. The color
673  *  needs to be a string with three numbers separated by spaces in the range [0,1].
674  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
675  *
676  *  \param variable The name of the new variable to be declared.
677  *  \param color The color for the new variable.
678  */
679 void TRACE_link_variable_declare_with_color (const char *variable, const char *color)
680 {
681   instr_user_variable (0, nullptr, variable, "LINK", 0, INSTR_US_DECLARE, color, user_link_variables);
682 }
683
684 /** \ingroup TRACE_user_variables
685  *  \brief Set the value of a variable of a link.
686  *
687  *  \param link The name of the link to be considered.
688  *  \param variable The name of the variable to be considered.
689  *  \param value The new value of the variable.
690  *
691  *  \see TRACE_link_variable_declare, TRACE_link_variable_add, TRACE_link_variable_sub
692  */
693 void TRACE_link_variable_set (const char *link, const char *variable, double value)
694 {
695   TRACE_link_variable_set_with_time (MSG_get_clock(), link, variable, value);
696 }
697
698 /** \ingroup TRACE_user_variables
699  *  \brief Add a value to a variable of a link.
700  *
701  *  \param link The name of the link to be considered.
702  *  \param variable The name of the variable to be considered.
703  *  \param value The value to be added to the variable.
704  *
705  *  \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_sub
706  */
707 void TRACE_link_variable_add (const char *link, const char *variable, double value)
708 {
709   TRACE_link_variable_add_with_time (MSG_get_clock(), link, variable, value);
710 }
711
712 /** \ingroup TRACE_user_variables
713  *  \brief Subtract a value from a variable of a link.
714  *
715  *  \param link The name of the link to be considered.
716  *  \param variable The name of the variable to be considered.
717  *  \param value The value to be subtracted from the variable.
718  *
719  *  \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_add
720  */
721 void TRACE_link_variable_sub (const char *link, const char *variable, double value)
722 {
723   TRACE_link_variable_sub_with_time (MSG_get_clock(), link, variable, value);
724 }
725
726 /** \ingroup TRACE_user_variables
727  *  \brief Set the value of a variable of a link at a given timestamp.
728  *
729  *  Same as #TRACE_link_variable_set, but let user specify the time used to trace it. Users can specify a time that
730  *  is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
731  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
732  *  also traced.
733  *
734  *  \param time The timestamp to be used to tag this change of value.
735  *  \param link The name of the link to be considered.
736  *  \param variable The name of the variable to be considered.
737  *  \param value The new value of the variable.
738  *
739  *  \see TRACE_link_variable_declare, TRACE_link_variable_add_with_time, TRACE_link_variable_sub_with_time
740  */
741 void TRACE_link_variable_set_with_time (double time, const char *link, const char *variable, double value)
742 {
743   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SET, nullptr, user_link_variables);
744 }
745
746 /** \ingroup TRACE_user_variables
747  *  \brief Add a value to a variable of a link at a given timestamp.
748  *
749  *  Same as #TRACE_link_variable_add, but let user specify the time used to trace it. Users can specify a time that
750  *  is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
751  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
752  *  also traced.
753  *
754  *  \param time The timestamp to be used to tag this change of value.
755  *  \param link The name of the link to be considered.
756  *  \param variable The name of the variable to be considered.
757  *  \param value The value to be added to the variable.
758  *
759  *  \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_sub_with_time
760  */
761 void TRACE_link_variable_add_with_time (double time, const char *link, const char *variable, double value)
762 {
763   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_ADD, nullptr, user_link_variables);
764 }
765
766 /** \ingroup TRACE_user_variables
767  *  \brief Subtract a value from a variable of a link at a given timestamp.
768  *
769  *  Same as #TRACE_link_variable_sub, but let user specify the time used to trace it. Users can specify a time that
770  *  is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
771  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
772  *  also traced.
773  *
774  *  \param time The timestamp to be used to tag this change of value.
775  *  \param link The name of the link to be considered.
776  *  \param variable The name of the variable to be considered.
777  *  \param value The value to be subtracted from the variable.
778  *
779  *  \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_add_with_time
780  */
781 void TRACE_link_variable_sub_with_time (double time, const char *link, const char *variable, double value)
782 {
783   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SUB, nullptr, user_link_variables);
784 }
785
786 /* for link variables, but with src and dst used for get_route */
787 /** \ingroup TRACE_user_variables
788  *  \brief Set the value of the variable present in the links connecting source and destination.
789  *
790  *  Same as #TRACE_link_variable_set, but instead of providing the name of link to be considered, provide the source
791  *  and destination hosts. All links that are part of the route between source and destination will have the variable
792  *  set to the provided value.
793  *
794  *  \param src The name of the source host for get route.
795  *  \param dst The name of the destination host for get route.
796  *  \param variable The name of the variable to be considered.
797  *  \param value The new value of the variable.
798  *
799  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add, TRACE_link_srcdst_variable_sub
800  */
801 void TRACE_link_srcdst_variable_set (const char *src, const char *dst, const char *variable, double value)
802 {
803   TRACE_link_srcdst_variable_set_with_time (MSG_get_clock(), src, dst, variable, value);
804 }
805
806 /** \ingroup TRACE_user_variables
807  *  \brief Add a value to the variable present in the links connecting source and destination.
808  *
809  *  Same as #TRACE_link_variable_add, but instead of providing the name of link to be considered, provide the source
810  *  and destination hosts. All links that are part of the route between source and destination will have the value
811  *  passed as parameter added to the current value of the variable name to be considered.
812  *
813  *  \param src The name of the source host for get route.
814  *  \param dst The name of the destination host for get route.
815  *  \param variable The name of the variable to be considered.
816  *  \param value The value to be added to the variable.
817  *
818  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_sub
819  */
820 void TRACE_link_srcdst_variable_add (const char *src, const char *dst, const char *variable, double value)
821 {
822   TRACE_link_srcdst_variable_add_with_time (MSG_get_clock(), src, dst, variable, value);
823 }
824
825 /** \ingroup TRACE_user_variables
826  *  \brief Subtract a value from the variable present in the links connecting source and destination.
827  *
828  *  Same as #TRACE_link_variable_sub, but instead of providing the name of link to be considered, provide the source
829  *  and destination hosts. All links that are part of the route between source and destination will have the value
830  *  passed as parameter subtracted from the current value of the variable name to be considered.
831  *
832  *  \param src The name of the source host for get route.
833  *  \param dst The name of the destination host for get route.
834  *  \param variable The name of the variable to be considered.
835  *  \param value The value to be subtracted from the variable.
836  *
837  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_add
838  */
839 void TRACE_link_srcdst_variable_sub (const char *src, const char *dst, const char *variable, double value)
840 {
841   TRACE_link_srcdst_variable_sub_with_time (MSG_get_clock(), src, dst, variable, value);
842 }
843
844 /** \ingroup TRACE_user_variables
845  *  \brief Set the value of the variable present in the links connecting source and destination at a given timestamp.
846  *
847  *  Same as #TRACE_link_srcdst_variable_set, but let user specify the time used to trace it. Users can specify a time
848  *  that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
849  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
850  *  also traced.
851  *
852  *  \param time The timestamp to be used to tag this change of value.
853  *  \param src The name of the source host for get route.
854  *  \param dst The name of the destination host for get route.
855  *  \param variable The name of the variable to be considered.
856  *  \param value The new value of the variable.
857  *
858  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add_with_time, TRACE_link_srcdst_variable_sub_with_time
859  */
860 void TRACE_link_srcdst_variable_set_with_time (double time, const char *src, const char *dst, const char *variable,
861                                                double value)
862 {
863   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SET);
864 }
865
866 /** \ingroup TRACE_user_variables
867  *  \brief Add a value to the variable present in the links connecting source and destination at a given timestamp.
868  *
869  *  Same as #TRACE_link_srcdst_variable_add, but let user specify the time used to trace it. Users can specify a time
870  *  that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
871  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
872  *  also traced.
873  *
874  *  \param time The timestamp to be used to tag this change of value.
875  *  \param src The name of the source host for get route.
876  *  \param dst The name of the destination host for get route.
877  *  \param variable The name of the variable to be considered.
878  *  \param value The value to be added to the variable.
879  *
880  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_sub_with_time
881  */
882 void TRACE_link_srcdst_variable_add_with_time (double time, const char *src, const char *dst, const char *variable,
883                                                double value)
884 {
885   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_ADD);
886 }
887
888 /** \ingroup TRACE_user_variables
889  *  \brief Subtract a value from the variable present in the links connecting source and dest. at a given timestamp.
890  *
891  *  Same as #TRACE_link_srcdst_variable_sub, but let user specify the time used to trace it. Users can specify a time
892  *  that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
893  *  definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
894  *  also traced.
895  *
896  *  \param time The timestamp to be used to tag this change of value.
897  *  \param src The name of the source host for get route.
898  *  \param dst The name of the destination host for get route.
899  *  \param variable The name of the variable to be considered.
900  *  \param value The value to be subtracted from the variable.
901  *
902  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_add_with_time
903  */
904 void TRACE_link_srcdst_variable_sub_with_time (double time, const char *src, const char *dst, const char *variable,
905                                                double value)
906 {
907   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SUB);
908 }
909
910 /** \ingroup TRACE_user_variables
911  *  \brief Get declared user link variables
912  *
913  * This function should be used to get link variables that were already declared with #TRACE_link_variable_declare or
914  * with #TRACE_link_variable_declare_with_color.
915  *
916  * \return A dynar with the declared link variables, must be freed with xbt_dynar_free.
917  */
918 xbt_dynar_t TRACE_get_link_variables ()
919 {
920   return instr_dict_to_dynar (user_link_variables);
921 }
922
923 /** \ingroup TRACE_user_variables
924  *  \brief Declare a new user state associated to hosts.
925  *
926  *  Declare a user state that will be associated to hosts.
927  *  A user host state can be used to trace application states.
928  *
929  *  \param state The name of the new state to be declared.
930  *
931  *  \see TRACE_host_state_declare_value
932  */
933 void TRACE_host_state_declare (const char *state)
934 {
935   instr_new_user_state_type("HOST", state);
936 }
937
938 /** \ingroup TRACE_user_variables
939  *  \brief Declare a new value for a user state associated to hosts.
940  *
941  *  Declare a value for a state. The color needs to be a string with 3 numbers separated by spaces in the range [0,1].
942  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
943  *
944  *  \param state The name of the new state to be declared.
945  *  \param value The name of the value
946  *  \param color The color of the value
947  *
948  *  \see TRACE_host_state_declare
949  */
950 void TRACE_host_state_declare_value (const char *state, const char *value, const char *color)
951 {
952   instr_new_value_for_user_state_type (state, value, color);
953 }
954
955 /** \ingroup TRACE_user_variables
956  *  \brief Set the user state to the given value.
957  *
958  *  Change a user state previously declared to the given value.
959  *
960  *  \param host The name of the host to be considered.
961  *  \param state The name of the state previously declared.
962  *  \param value The new value of the state.
963  *
964  *  \see TRACE_host_state_declare, TRACE_host_push_state, TRACE_host_pop_state, TRACE_host_reset_state
965  */
966 void TRACE_host_set_state (const char *host, const char *state, const char *value)
967 {
968   container_t container = PJ_container_get(host);
969   type_t type = PJ_type_get (state, container->type);
970   val_t val = PJ_value_get_or_new (value, nullptr, type); /* if user didn't declare a value with a color, use nullptr color */
971   new_pajeSetState(MSG_get_clock(), container, type, val);
972 }
973
974 /** \ingroup TRACE_user_variables
975  *  \brief Push a new value for a state of a given host.
976  *
977  *  Change a user state previously declared by pushing the new value to the state.
978  *
979  *  \param host The name of the host to be considered.
980  *  \param state The name of the state previously declared.
981  *  \param value The value to be pushed.
982  *
983  *  \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_pop_state, TRACE_host_reset_state
984  */
985 void TRACE_host_push_state (const char *host, const char *state, const char *value)
986 {
987   container_t container = PJ_container_get(host);
988   type_t type = PJ_type_get (state, container->type);
989   val_t val = PJ_value_get_or_new (value, nullptr, type); /* if user didn't declare a value with a color, use nullptr color */
990   new_pajePushState(MSG_get_clock(), container, type, val);
991 }
992
993 /** \ingroup TRACE_user_variables
994  *  \brief Pop the last value of a state of a given host.
995  *
996  *  Change a user state previously declared by removing the last value of the state.
997  *
998  *  \param host The name of the host to be considered.
999  *  \param state The name of the state to be popped.
1000  *
1001  *  \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state, TRACE_host_reset_state
1002  */
1003 void TRACE_host_pop_state (const char *host, const char *state)
1004 {
1005   container_t container = PJ_container_get(host);
1006   type_t type = PJ_type_get (state, container->type);
1007   new_pajePopState(MSG_get_clock(), container, type);
1008 }
1009
1010 /** \ingroup TRACE_user_variables
1011  *  \brief Reset the state of a given host.
1012  *
1013  *  Clear all previous values of a user state.
1014  *
1015  *  \param host The name of the host to be considered.
1016  *  \param state The name of the state to be cleared.
1017  *
1018  *  \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state, TRACE_host_pop_state
1019  */
1020 void TRACE_host_reset_state (const char *host, const char *state)
1021 {
1022   container_t container = PJ_container_get(host);
1023   type_t type = PJ_type_get (state, container->type);
1024   new_pajeResetState(MSG_get_clock(), container, type);
1025 }
1026
1027 /** \ingroup TRACE_API
1028  *  \brief Get Paje container types that can be mapped to the nodes of a graph.
1029  *
1030  *  This function can be used to create a user made  graph configuration file for Triva. Normally, it is used with the
1031  *  functions defined in \ref TRACE_user_variables.
1032  *
1033  *  \return A dynar with the types, must be freed with xbt_dynar_free.
1034  */
1035 xbt_dynar_t TRACE_get_node_types ()
1036 {
1037   return instr_dict_to_dynar (trivaNodeTypes);
1038 }
1039
1040 /** \ingroup TRACE_API
1041  *  \brief Get Paje container types that can be mapped to the edges of a graph.
1042  *
1043  *  This function can be used to create a user made graph configuration file for Triva. Normally, it is used with the
1044  *  functions defined in \ref TRACE_user_variables.
1045  *
1046  *  \return A dynar with the types, must be freed with xbt_dynar_free.
1047  */
1048 xbt_dynar_t TRACE_get_edge_types ()
1049 {
1050   return instr_dict_to_dynar (trivaEdgeTypes);
1051 }
1052
1053 /** \ingroup TRACE_API
1054  *  \brief Pauses all tracing activities.
1055  *  \see TRACE_resume
1056  */
1057 void TRACE_pause ()
1058 {
1059   instr_pause_tracing();
1060 }
1061
1062 /** \ingroup TRACE_API
1063  *  \brief Resumes all tracing activities.
1064  *  \see TRACE_pause
1065  */
1066 void TRACE_resume ()
1067 {
1068   instr_resume_tracing();
1069 }