Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
simplifications
[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/surf/network_interface.hpp"
9 #include "src/instr/instr_private.h"
10 #include "surf/surf.h"
11 #include "src/surf/surf_private.h"
12
13 typedef enum {
14   INSTR_US_DECLARE,
15   INSTR_US_SET,
16   INSTR_US_ADD,
17   INSTR_US_SUB
18 } InstrUserVariable;
19
20 XBT_LOG_NEW_DEFAULT_SUBCATEGORY (instr_api, instr, "API");
21
22 xbt_dict_t created_categories = nullptr;
23 xbt_dict_t declared_marks = nullptr;
24 xbt_dict_t user_host_variables = nullptr;
25 xbt_dict_t user_vm_variables = nullptr;
26 xbt_dict_t user_link_variables = nullptr;
27 extern xbt_dict_t trivaNodeTypes;
28 extern xbt_dict_t trivaEdgeTypes;
29
30 static xbt_dynar_t instr_dict_to_dynar (xbt_dict_t filter)
31 {
32   if (!TRACE_is_enabled() || !TRACE_needs_platform())
33     return nullptr;
34
35   xbt_dynar_t ret = xbt_dynar_new (sizeof(char*), &xbt_free_ref);
36   xbt_dict_cursor_t cursor = nullptr;
37   char *name;
38   char *value;
39   xbt_dict_foreach(filter, cursor, name, value) {
40     xbt_dynar_push_as (ret, char*, xbt_strdup(name));
41   }
42   return ret;
43 }
44
45 /** \ingroup TRACE_category
46  *  \brief Declare a new category with a random color.
47  *
48  *  This function should be used to define a user category. The category can be used to differentiate the tasks that
49  *  are created during the simulation (for example, tasks from server1, server2, or request tasks, computation tasks,
50  *  communication tasks). All resource utilization (host power and link bandwidth) will be classified according to the
51  *  task category. Tasks that do not belong to a category are not traced. The color for the category that is being
52  *  declared is random. This function has no effect if a category with the same name has been already declared.
53  *
54  * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
55  *
56  *  \param category The name of the new tracing category to be created.
57  *
58  *  \see TRACE_category_with_color, MSG_task_set_category, SD_task_set_category
59  */
60 void TRACE_category(const char *category)
61 {
62   TRACE_category_with_color (category, nullptr);
63 }
64
65 /** \ingroup TRACE_category
66  *  \brief Declare a new category with a color.
67  *
68  *  Same as #TRACE_category, but let user specify a color encoded as a RGB-like string with three floats from 0 to 1.
69  *  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"
70  *   as color. This function has no effect if a category with the same name has been already declared.
71  *
72  * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
73  *
74  *  \param category The name of the new tracing category to be created.
75  *  \param color The color of the category (see \ref outcomes_vizu to
76  *  know how to correctly specify the color)
77  *
78  *  \see MSG_task_set_category, SD_task_set_category
79  */
80 void TRACE_category_with_color (const char *category, const char *color)
81 {
82   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with categories */
83   if (!TRACE_is_enabled() || !TRACE_needs_platform())
84     return;
85
86   if (!(TRACE_categorized() && category != nullptr))
87     return;
88
89   //check if category is already created
90   if (xbt_dict_get_or_null(created_categories, category) != nullptr)
91     return;
92
93   xbt_dict_set (created_categories, category, xbt_strdup("1"), nullptr);
94
95   //define final_color
96   char final_color[INSTR_DEFAULT_STR_SIZE];
97   if (!color){
98     //generate a random color
99     double red = drand48();
100     double green = drand48();
101     double blue = drand48();
102     snprintf (final_color, INSTR_DEFAULT_STR_SIZE, "%f %f %f", red, green, blue);
103   }else{
104     snprintf (final_color, INSTR_DEFAULT_STR_SIZE, "%s", color);
105   }
106
107   XBT_DEBUG("CAT,declare %s, \"%s\" \"%s\"", category, color, final_color);
108
109   //define the type of this category on top of hosts and links
110   instr_new_variable_type (category, final_color);
111 }
112
113 /** \ingroup TRACE_category
114  *  \brief Get declared categories
115  *
116  * This function should be used to get categories that were already declared with #TRACE_category or with
117  * #TRACE_category_with_color.
118  *
119  * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
120  *
121  * \return A dynar with the declared categories, must be freed with xbt_dynar_free.
122  *
123  *  \see MSG_task_set_category, SD_task_set_category
124  */
125 xbt_dynar_t TRACE_get_categories ()
126 {
127   if (!TRACE_is_enabled() || !TRACE_categorized())
128     return nullptr;
129
130   return instr_dict_to_dynar (created_categories);
131 }
132
133 /** \ingroup TRACE_mark
134  * \brief Declare a new type for tracing mark.
135  *
136  * This function declares a new Paje event type in the trace file that can be used by simulators to declare
137  * application-level marks. This function is independent of which API is used in SimGrid.
138  *
139  * \param mark_type The name of the new type.
140  *
141  * \see TRACE_mark
142  */
143 void TRACE_declare_mark(const char *mark_type)
144 {
145   /* safe switchs. tracing has to be activated and if platform is not traced, we can't deal with marks */
146   if (!TRACE_is_enabled() || !TRACE_needs_platform())
147     return;
148
149   if (!mark_type)
150     THROWF (tracing_error, 1, "mark_type is nullptr");
151
152   //check if mark_type is already declared
153   if (xbt_dict_get_or_null(declared_marks, mark_type) != nullptr) {
154     THROWF (tracing_error, 1, "mark_type with name (%s) is already declared", mark_type);
155   }
156
157   XBT_DEBUG("MARK,declare %s", mark_type);
158   PJ_type_event_new(mark_type, PJ_type_get_root());
159   xbt_dict_set (declared_marks, mark_type, xbt_strdup("1"), nullptr);
160 }
161
162 /** \ingroup TRACE_mark
163  * \brief Declare a new colored value for a previously declared mark type.
164  *
165  * This function declares a new colored value for a Paje event type in the trace file that can be used by simulators to
166  * declare application-level marks. This function is independent of which API is used in SimGrid. The color needs to be
167  * a string with three numbers separated by spaces in the range [0,1].
168  * 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
169  * be white ("1 1 1").
170  *
171  * \param mark_type The name of the new type.
172  * \param mark_value The name of the new value for this type.
173  * \param mark_color The color of the new value for this type.
174  *
175  * \see TRACE_mark
176  */
177 void TRACE_declare_mark_value_with_color (const char *mark_type, const char *mark_value, const char *mark_color)
178 {
179   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
180   if (!TRACE_is_enabled() || !TRACE_needs_platform())
181     return;
182
183   if (!mark_type)
184     THROWF (tracing_error, 1, "mark_type is nullptr");
185   if (!mark_value)
186     THROWF (tracing_error, 1, "mark_value is nullptr");
187
188   type_t type = PJ_type_get (mark_type, PJ_type_get_root());
189   if (!type){
190     THROWF (tracing_error, 1, "mark_type with name (%s) is not declared", mark_type);
191   }
192
193   char white[INSTR_DEFAULT_STR_SIZE] = "1.0 1.0 1.0";
194   if (!mark_color)
195     mark_color = white;
196
197   XBT_DEBUG("MARK,declare_value %s %s %s", mark_type, mark_value, mark_color);
198   PJ_value_new (mark_value, mark_color, type);
199 }
200
201 /** \ingroup TRACE_mark
202  * \brief Declare a new value for a previously declared mark type.
203  *
204  * This function declares a new value for a Paje event type in the trace file that can be used by simulators to declare
205  * application-level marks. This function is independent of which API is used in SimGrid. Calling this function is the
206  * same as calling \ref TRACE_declare_mark_value_with_color with a nullptr color.
207  *
208  * \param mark_type The name of the new type.
209  * \param mark_value The name of the new value for this type.
210  *
211  * \see TRACE_mark
212  */
213 void TRACE_declare_mark_value (const char *mark_type, const char *mark_value)
214 {
215   TRACE_declare_mark_value_with_color (mark_type, mark_value, nullptr);
216 }
217
218 /**
219  * \ingroup TRACE_mark
220  * \brief Create a new instance of a tracing mark type.
221  *
222  * This function creates a mark in the trace file. The first parameter had to be previously declared using
223  * #TRACE_declare_mark, the second is the identifier for this mark instance. We recommend that the mark_value is a
224  * unique value for the whole simulation. Nevertheless, this is not a strong requirement: the trace will be valid even
225  * if there are multiple mark identifiers for the same trace.
226  *
227  * \param mark_type The name of the type for which the new instance will belong.
228  * \param mark_value The name of the new instance mark.
229  *
230  * \see TRACE_declare_mark
231  */
232 void TRACE_mark(const char *mark_type, const char *mark_value)
233 {
234   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
235   if (!TRACE_is_enabled() || !TRACE_needs_platform())
236     return;
237
238   if (!mark_type)
239     THROWF (tracing_error, 1, "mark_type is nullptr");
240   if (!mark_value)
241     THROWF (tracing_error, 1, "mark_value is nullptr");
242
243   //check if mark_type is already declared
244   type_t type = PJ_type_get (mark_type, PJ_type_get_root());
245   if (!type){
246     THROWF (tracing_error, 1, "mark_type with name (%s) is not declared", mark_type);
247   }
248
249   val_t value = PJ_value_get (mark_value, type);
250   XBT_DEBUG("MARK %s %s", mark_type, mark_value);
251   new_pajeNewEvent (MSG_get_clock(), PJ_container_get_root(), type, value);
252 }
253
254 /** \ingroup TRACE_mark
255  *  \brief Get declared marks
256  *
257  * This function should be used to get marks that were already declared with #TRACE_declare_mark.
258  *
259  * \return A dynar with the declared marks, must be freed with xbt_dynar_free.
260  */
261 xbt_dynar_t TRACE_get_marks ()
262 {
263   if (!TRACE_is_enabled())
264     return nullptr;
265
266   return instr_dict_to_dynar (declared_marks);
267 }
268
269 static void instr_user_variable(double time, const char *resource, const char *variable, const char *father_type,
270                          double value, InstrUserVariable what, const char *color, xbt_dict_t filter)
271 {
272   /* safe switches. tracing has to be activated and if platform is not traced, we don't allow user variables */
273   if (!TRACE_is_enabled() || !TRACE_needs_platform())
274     return;
275
276   //check if variable is already declared
277   char *created = (char*)xbt_dict_get_or_null(filter, variable);
278   if (what == INSTR_US_DECLARE){
279     if (created){//already declared
280       return;
281     }else{
282       xbt_dict_set (filter, variable, xbt_strdup("1"), nullptr);
283       instr_new_user_variable_type (father_type, variable, color);
284     }
285   }else{
286     if (!created){//not declared, ignore
287       return;
288     } else {
289       char valuestr[100];
290       snprintf(valuestr, 100, "%g", value);
291       container_t container = PJ_container_get(resource);
292       type_t type = PJ_type_get (variable, container->type);
293       switch (what){
294       case INSTR_US_SET:
295         new_pajeSetVariable(time, container, type, value);
296         break;
297       case INSTR_US_ADD:
298         new_pajeAddVariable(time, container, type, value);
299         break;
300       case INSTR_US_SUB:
301         new_pajeSubVariable(time, container, type, value);
302         break;
303       default:
304         THROW_IMPOSSIBLE;
305         break;
306       }
307     }
308   }
309 }
310
311 static void instr_user_srcdst_variable(double time, const char *src, const char *dst, const char *variable,
312                               const char *father_type, double value, InstrUserVariable what)
313 {
314   sg_netcard_t src_elm = sg_netcard_by_name_or_null(src);
315   if(!src_elm)
316     xbt_die("Element '%s' not found!",src);
317
318   sg_netcard_t dst_elm = sg_netcard_by_name_or_null(dst);
319   if(!dst_elm)
320     xbt_die("Element '%s' not found!",dst);
321
322   std::vector<Link*> *route = new std::vector<Link*>();
323   routing_platf->getRouteAndLatency (src_elm, dst_elm, route,nullptr);
324   for (auto link : *route)
325     instr_user_variable (time, link->getName(), variable, father_type, value, what, nullptr, user_link_variables);
326   delete route;
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 }