Logo AND Algorithmique Numérique Distribuée

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