Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
[trace] move categories dictionary declaration to interface file
[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 /** \ingroup TRACE_category
24  *  \brief Declare a new category with a random color.
25  *
26  *  This function should be used to define a user category. The
27  *  category can be used to differentiate the tasks that are created
28  *  during the simulation (for example, tasks from server1, server2,
29  *  or request tasks, computation tasks, communication tasks). All
30  *  resource utilization (host power and link bandwidth) will be
31  *  classified according to the task category. Tasks that do not
32  *  belong to a category are not traced. The color for the category
33  *  that is being declared is random. This function has no effect
34  *  if a category with the same name has been already declared.
35  *
36  * See \ref tracing_tracing for details on how to trace
37  * the (categorized) resource utilization.
38  *
39  *  \param category The name of the new tracing category to be created.
40  *
41  *  \see TRACE_category_with_color, MSG_task_set_category, SD_task_set_category
42  */
43 void TRACE_category(const char *category)
44 {
45   TRACE_category_with_color (category, NULL);
46 }
47
48 /** \ingroup TRACE_category
49  *  \brief Declare a new category with a color.
50  *
51  *  Same as #TRACE_category, but let user specify a color encoded as a
52  *  RGB-like string with three floats from 0 to 1. So, to specify a
53  *  red color, pass "1 0 0" as color parameter. A light-gray color
54  *  can be specified using "0.7 0.7 0.7" as color. This function has
55  *  no effect if a category with the same name has been already declared.
56  *
57  * See \ref tracing_tracing for details on how to trace
58  * the (categorized) resource utilization.
59  *
60  *  \param category The name of the new tracing category to be created.
61  *  \param color The color of the category (see \ref tracing_tracing to
62  *  know how to correctly specify the color)
63  *
64  *  \see MSG_task_set_category, SD_task_set_category
65  */
66 void TRACE_category_with_color (const char *category, const char *color)
67 {
68   /* safe switch */
69   if (!TRACE_is_enabled()) return;
70
71   if (!(TRACE_categorized() && category != NULL)) return;
72
73   /* if platform is not traced, we can't deal with categories */
74   if (!TRACE_needs_platform()) return;
75
76   //check if category is already created
77   char *created = xbt_dict_get_or_null(created_categories, category);
78   if (created) return;
79   xbt_dict_set (created_categories, category, xbt_strdup("1"), NULL);
80
81   //define final_color
82   char final_color[INSTR_DEFAULT_STR_SIZE];
83   if (!color){
84     //generate a random color
85     double red = drand48();
86     double green = drand48();
87     double blue = drand48();
88     snprintf (final_color, INSTR_DEFAULT_STR_SIZE, "%f %f %f", red, green, blue);
89   }else{
90     snprintf (final_color, INSTR_DEFAULT_STR_SIZE, "%s", color);
91   }
92
93   XBT_DEBUG("CAT,declare %s, %s", category, final_color);
94
95   //define the type of this category on top of hosts and links
96   instr_new_variable_type (category, final_color);
97 }
98
99
100 /** \ingroup TRACE_category
101  *  \brief Get declared categories
102  *
103  * This function should be used to get categories that were already
104  * declared with #TRACE_category or with #TRACE_category_with_color.
105  *
106  * See \ref tracing_tracing for details on how to trace
107  * the (categorized) resource utilization.
108  *
109  * \return A dynar with the declared categories, must be freed with xbt_dynar_free.
110  *
111  *  \see MSG_task_set_category, SD_task_set_category
112  */
113 xbt_dynar_t TRACE_get_categories (void)
114 {
115   if (!TRACE_is_enabled()) return NULL;
116   if (!TRACE_categorized()) return NULL;
117
118   xbt_dynar_t ret = xbt_dynar_new (sizeof(char*), &xbt_free_ref);
119   xbt_dict_cursor_t cursor = NULL;
120   char *name, *value;
121   xbt_dict_foreach(created_categories, cursor, name, value) {
122     xbt_dynar_push_as (ret, char*, xbt_strdup(name));
123   }
124   return ret;
125 }
126
127 /** \ingroup TRACE_mark
128  * \brief Declare a new type for tracing mark.
129  *
130  * This function declares a new Paje event
131  * type in the trace file that can be used by
132  * simulators to declare application-level
133  * marks. This function is independent of
134  * which API is used in SimGrid.
135  *
136  * \param mark_type The name of the new type.
137  *
138  * \see TRACE_mark
139  */
140 void TRACE_declare_mark(const char *mark_type)
141 {
142   /* safe switch */
143   if (!TRACE_is_enabled()) return;
144
145   if (!mark_type) return;
146
147   XBT_DEBUG("MARK,declare %s", mark_type);
148   PJ_type_event_new(mark_type, NULL, PJ_type_get_root());
149 }
150
151 /**
152  * \ingroup TRACE_mark
153  * \brief Create a new instance of a tracing mark type.
154  *
155  * This function creates a mark in the trace file. The
156  * first parameter had to be previously declared using
157  * #TRACE_declare_mark, the second is the identifier
158  * for this mark instance. We recommend that the
159  * mark_value is a unique value for the whole simulation.
160  * Nevertheless, this is not a strong requirement: the
161  * trace will be valid even if there are multiple mark
162  * identifiers for the same trace.
163  *
164  * \param mark_type The name of the type for which the new instance will belong.
165  * \param mark_value The name of the new instance mark.
166  *
167  * \see TRACE_declare_mark
168  */
169 void TRACE_mark(const char *mark_type, const char *mark_value)
170 {
171   /* safe switch */
172   if (!TRACE_is_enabled()) return;
173
174   if (!mark_type || !mark_value) return;
175
176   XBT_DEBUG("MARK %s %s", mark_type, mark_value);
177   type_t type = PJ_type_get (mark_type, PJ_type_get_root());
178   if (type == NULL){
179     THROWF (tracing_error, 1, "mark_type with name (%s) not declared before", mark_type);
180   }
181   val_t value = PJ_value_get (mark_value, type);
182   if (value == NULL){
183     value = PJ_value_new (mark_value, NULL, type);
184   }
185   new_pajeNewEvent (MSG_get_clock(), PJ_container_get_root(), type, value);
186 }
187
188 static void instr_user_variable(double time,
189                          const char *resource,
190                          const char *variable,
191                          const char *father_type,
192                          double value,
193                          InstrUserVariable what,
194                          const char *color)
195 {
196   /* safe switch */
197   if (!TRACE_is_enabled()) return;
198
199   /* if platform is not traced, we can't deal user variables */
200   if (!TRACE_needs_platform()) return;
201
202   char valuestr[100];
203   snprintf(valuestr, 100, "%g", value);
204
205   switch (what){
206   case INSTR_US_DECLARE:
207     instr_new_user_variable_type (father_type, variable, color);
208     break;
209   case INSTR_US_SET:
210   {
211     container_t container = PJ_container_get(resource);
212     type_t type = PJ_type_get (variable, container->type);
213     new_pajeSetVariable(time, container, type, value);
214     break;
215   }
216   case INSTR_US_ADD:
217   {
218     container_t container = PJ_container_get(resource);
219     type_t type = PJ_type_get (variable, container->type);
220     new_pajeAddVariable(time, container, type, value);
221     break;
222   }
223   case INSTR_US_SUB:
224   {
225     container_t container = PJ_container_get(resource);
226     type_t type = PJ_type_get (variable, container->type);
227     new_pajeSubVariable(time, container, type, value);
228     break;
229   }
230   default:
231     //TODO: launch exception
232     break;
233   }
234 }
235
236 static void instr_user_srcdst_variable(double time,
237                               const char *src,
238                               const char *dst,
239                               const char *variable,
240                               const char *father_type,
241                               double value,
242                               InstrUserVariable what)
243 {
244   xbt_dynar_t route=NULL;
245   network_element_t src_elm = xbt_lib_get_or_null(host_lib,src,ROUTING_HOST_LEVEL);
246   if(!src_elm) src_elm = xbt_lib_get_or_null(as_router_lib,src,ROUTING_ASR_LEVEL);
247   if(!src_elm) xbt_die("Element '%s' not found!",src);
248
249   network_element_t dst_elm = xbt_lib_get_or_null(host_lib,dst,ROUTING_HOST_LEVEL);
250   if(!dst_elm) dst_elm = xbt_lib_get_or_null(as_router_lib,dst,ROUTING_ASR_LEVEL);
251   if(!dst_elm) xbt_die("Element '%s' not found!",dst);
252
253   routing_get_route_and_latency (src_elm, dst_elm, &route,NULL);
254   unsigned int i;
255   void *link;
256   xbt_dynar_foreach (route, i, link) {
257     char *link_name = ((link_CM02_t)link)->lmm_resource.generic_resource.name;
258     instr_user_variable (time, link_name, variable, father_type, value, what, NULL);
259   }
260 }
261
262 /** \ingroup TRACE_API
263  *  \brief Creates a file with the topology of the platform file used for the simulator.
264  *
265  *  The graph topology will have the following properties: all hosts, links and routers
266  *  of the platform file are mapped to graph nodes; routes are mapped to edges.
267  *  The platform's AS are not represented in the output.
268  *
269  *  \param filename The name of the file that will hold the graph.
270  *
271  *  \return 1 of successful, 0 otherwise.
272  */
273 int TRACE_platform_graph_export_graphviz (const char *filename)
274 {
275   /* returns 1 if successful, 0 otherwise */
276   if (!TRACE_is_enabled()) return 0;
277   xbt_graph_t g = instr_routing_platform_graph();
278   if (g == NULL) return 0;
279   instr_routing_platform_graph_export_graphviz (g, filename);
280   xbt_graph_free_graph (g, xbt_free, xbt_free, NULL);
281   return 1;
282 }
283
284 /*
285  * Derived functions that use instr_user_variable and TRACE_user_srcdst_variable.
286  * They were previously defined as pre-processors directives, but were transformed
287  * into functions so the user can track them using gdb.
288  */
289
290 /* for host variables */
291 /** \ingroup TRACE_user_variables
292  *  \brief Declare a new user variable associated to hosts.
293  *
294  *  Declare a user variable that will be associated to hosts.
295  *  A user host variable can be used to trace user variables
296  *  such as the number of tasks in a server, the number of
297  *  clients in an application (for hosts), and so on. The color
298  *  associated to this new variable will be random.
299  *
300  *  \param variable The name of the new variable to be declared.
301  *
302  *  \see TRACE_host_variable_declare_with_color
303  */
304 void TRACE_host_variable_declare (const char *variable)
305 {
306   instr_user_variable(0, NULL, variable, "HOST", 0, INSTR_US_DECLARE, NULL);
307 }
308
309 /** \ingroup TRACE_user_variables
310  *  \brief Declare a new user variable associated to hosts with a color.
311  *
312  *  Same as #TRACE_host_variable_declare, but associated a color
313  *  to the newly created user host variable. The color needs to be
314  *  a string with three numbers separated by spaces in the range [0,1].
315  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
316  *
317  *  \param variable The name of the new variable to be declared.
318  *  \param color The color for the new variable.
319  *
320  */
321 void TRACE_host_variable_declare_with_color (const char *variable, const char *color)
322 {
323   instr_user_variable(0, NULL, variable, "HOST", 0, INSTR_US_DECLARE, color);
324 }
325
326 /** \ingroup TRACE_user_variables
327  *  \brief Set the value of a variable of a host.
328  *
329  *  \param host The name of the host to be considered.
330  *  \param variable The name of the variable to be considered.
331  *  \param value The new value of the variable.
332  *
333  *  \see TRACE_host_variable_declare, TRACE_host_variable_add, TRACE_host_variable_sub
334  */
335 void TRACE_host_variable_set (const char *host, const char *variable, double value)
336 {
337   TRACE_host_variable_set_with_time (MSG_get_clock(), host, variable, value);
338 }
339
340 /** \ingroup TRACE_user_variables
341  *  \brief Add a value to a variable of a host.
342  *
343  *  \param host The name of the host to be considered.
344  *  \param variable The name of the variable to be considered.
345  *  \param value The value to be added to the variable.
346  *
347  *  \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_sub
348  */
349 void TRACE_host_variable_add (const char *host, const char *variable, double value)
350 {
351   TRACE_host_variable_add_with_time (MSG_get_clock(), host, variable, value);
352 }
353
354 /** \ingroup TRACE_user_variables
355  *  \brief Subtract a value from a variable of a host.
356  *
357  *  \param host The name of the host to be considered.
358  *  \param variable The name of the variable to be considered.
359  *  \param value The value to be subtracted from the variable.
360  *
361  *  \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_add
362  */
363 void TRACE_host_variable_sub (const char *host, const char *variable, double value)
364 {
365   TRACE_host_variable_sub_with_time (MSG_get_clock(), host, variable, value);
366 }
367
368 /** \ingroup TRACE_user_variables
369  *  \brief Set the value of a variable of a host at a given timestamp.
370  *
371  *  Same as #TRACE_host_variable_set, but let user specify
372  *  the time used to trace it. Users can specify a time that
373  *  is not the simulated clock time as defined by the core
374  *  simulator. This allows a fine-grain control of time
375  *  definition, but should be used with caution since the trace
376  *  can be inconsistent if resource utilization traces are also traced.
377  *
378  *  \param time The timestamp to be used to tag this change of value.
379  *  \param host The name of the host to be considered.
380  *  \param variable The name of the variable to be considered.
381  *  \param value The new value of the variable.
382  *
383  *  \see TRACE_host_variable_declare, TRACE_host_variable_add_with_time, TRACE_host_variable_sub_with_time
384  */
385 void TRACE_host_variable_set_with_time (double time, const char *host, const char *variable, double value)
386 {
387   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_SET, NULL);
388 }
389
390 /** \ingroup TRACE_user_variables
391  *  \brief Add a value to a variable of a host at a given timestamp.
392  *
393  *  Same as #TRACE_host_variable_add, but let user specify
394  *  the time used to trace it. Users can specify a time that
395  *  is not the simulated clock time as defined by the core
396  *  simulator. This allows a fine-grain control of time
397  *  definition, but should be used with caution since the trace
398  *  can be inconsistent if resource utilization traces are also traced.
399  *
400  *  \param time The timestamp to be used to tag this change of value.
401  *  \param host The name of the host to be considered.
402  *  \param variable The name of the variable to be considered.
403  *  \param value The value to be added to the variable.
404  *
405  *  \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_sub_with_time
406  */
407 void TRACE_host_variable_add_with_time (double time, const char *host, const char *variable, double value)
408 {
409   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_ADD, NULL);
410 }
411
412 /** \ingroup TRACE_user_variables
413  *  \brief Subtract a value from a variable of a host at a given timestamp.
414  *
415  *  Same as #TRACE_host_variable_sub, but let user specify
416  *  the time used to trace it. Users can specify a time that
417  *  is not the simulated clock time as defined by the core
418  *  simulator. This allows a fine-grain control of time
419  *  definition, but should be used with caution since the trace
420  *  can be inconsistent if resource utilization traces are also traced.
421  *
422  *  \param time The timestamp to be used to tag this change of value.
423  *  \param host The name of the host to be considered.
424  *  \param variable The name of the variable to be considered.
425  *  \param value The value to be subtracted from the variable.
426  *
427  *  \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_add_with_time
428  */
429 void TRACE_host_variable_sub_with_time (double time, const char *host, const char *variable, double value)
430 {
431   instr_user_variable(time, host, variable, "HOST", value, INSTR_US_SUB, NULL);
432 }
433
434 /* for link variables */
435 /** \ingroup TRACE_user_variables
436  *  \brief Declare a new user variable associated to links.
437  *
438  *  Declare a user variable that will be associated to links.
439  *  A user link variable can be used, for example, to trace
440  *  user variables such as the number of messages being
441  *  transferred through network links. The color
442  *  associated to this new variable will be random.
443  *
444  *  \param variable The name of the new variable to be declared.
445  *
446  *  \see TRACE_link_variable_declare_with_color
447  */
448 void TRACE_link_variable_declare (const char *variable)
449 {
450   instr_user_variable (0, NULL, variable, "LINK", 0, INSTR_US_DECLARE, NULL);
451 }
452
453 /** \ingroup TRACE_user_variables
454  *  \brief Declare a new user variable associated to links with a color.
455  *
456  *  Same as #TRACE_link_variable_declare, but associated a color
457  *  to the newly created user link variable. The color needs to be
458  *  a string with three numbers separated by spaces in the range [0,1].
459  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
460  *
461  *  \param variable The name of the new variable to be declared.
462  *  \param color The color for the new variable.
463  *
464  */
465 void TRACE_link_variable_declare_with_color (const char *variable, const char *color)
466 {
467   instr_user_variable (0, NULL, variable, "LINK", 0, INSTR_US_DECLARE, color);
468 }
469
470 /** \ingroup TRACE_user_variables
471  *  \brief Set the value of a variable of a link.
472  *
473  *  \param link The name of the link to be considered.
474  *  \param variable The name of the variable to be considered.
475  *  \param value The new value of the variable.
476  *
477  *  \see TRACE_link_variable_declare, TRACE_link_variable_add, TRACE_link_variable_sub
478  */
479 void TRACE_link_variable_set (const char *link, const char *variable, double value)
480 {
481   TRACE_link_variable_set_with_time (MSG_get_clock(), link, variable, value);
482 }
483
484 /** \ingroup TRACE_user_variables
485  *  \brief Add a value to a variable of a link.
486  *
487  *  \param link The name of the link to be considered.
488  *  \param variable The name of the variable to be considered.
489  *  \param value The value to be added to the variable.
490  *
491  *  \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_sub
492  */
493 void TRACE_link_variable_add (const char *link, const char *variable, double value)
494 {
495   TRACE_link_variable_add_with_time (MSG_get_clock(), link, variable, value);
496 }
497
498 /** \ingroup TRACE_user_variables
499  *  \brief Subtract a value from a variable of a link.
500  *
501  *  \param link The name of the link to be considered.
502  *  \param variable The name of the variable to be considered.
503  *  \param value The value to be subtracted from the variable.
504  *
505  *  \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_add
506  */
507 void TRACE_link_variable_sub (const char *link, const char *variable, double value)
508 {
509   TRACE_link_variable_sub_with_time (MSG_get_clock(), link, variable, value);
510 }
511
512 /** \ingroup TRACE_user_variables
513  *  \brief Set the value of a variable of a link at a given timestamp.
514  *
515  *  Same as #TRACE_link_variable_set, but let user specify
516  *  the time used to trace it. Users can specify a time that
517  *  is not the simulated clock time as defined by the core
518  *  simulator. This allows a fine-grain control of time
519  *  definition, but should be used with caution since the trace
520  *  can be inconsistent if resource utilization traces are also traced.
521  *
522  *  \param time The timestamp to be used to tag this change of value.
523  *  \param link The name of the link to be considered.
524  *  \param variable The name of the variable to be considered.
525  *  \param value The new value of the variable.
526  *
527  *  \see TRACE_link_variable_declare, TRACE_link_variable_add_with_time, TRACE_link_variable_sub_with_time
528  */
529 void TRACE_link_variable_set_with_time (double time, const char *link, const char *variable, double value)
530 {
531   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SET, NULL);
532 }
533
534 /** \ingroup TRACE_user_variables
535  *  \brief Add a value to a variable of a link at a given timestamp.
536  *
537  *  Same as #TRACE_link_variable_add, but let user specify
538  *  the time used to trace it. Users can specify a time that
539  *  is not the simulated clock time as defined by the core
540  *  simulator. This allows a fine-grain control of time
541  *  definition, but should be used with caution since the trace
542  *  can be inconsistent if resource utilization traces are also traced.
543  *
544  *  \param time The timestamp to be used to tag this change of value.
545  *  \param link The name of the link to be considered.
546  *  \param variable The name of the variable to be considered.
547  *  \param value The value to be added to the variable.
548  *
549  *  \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_sub_with_time
550  */
551 void TRACE_link_variable_add_with_time (double time, const char *link, const char *variable, double value)
552 {
553   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_ADD, NULL);
554 }
555
556 /** \ingroup TRACE_user_variables
557  *  \brief Subtract a value from a variable of a link at a given timestamp.
558  *
559  *  Same as #TRACE_link_variable_sub, but let user specify
560  *  the time used to trace it. Users can specify a time that
561  *  is not the simulated clock time as defined by the core
562  *  simulator. This allows a fine-grain control of time
563  *  definition, but should be used with caution since the trace
564  *  can be inconsistent if resource utilization traces are also traced.
565  *
566  *  \param time The timestamp to be used to tag this change of value.
567  *  \param link The name of the link to be considered.
568  *  \param variable The name of the variable to be considered.
569  *  \param value The value to be subtracted from the variable.
570  *
571  *  \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_add_with_time
572  */
573 void TRACE_link_variable_sub_with_time (double time, const char *link, const char *variable, double value)
574 {
575   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SUB, NULL);
576 }
577
578 /* for link variables, but with src and dst used for get_route */
579 /** \ingroup TRACE_user_variables
580  *  \brief Set the value of the variable present in the links connecting source and destination.
581  *
582  *  Same as #TRACE_link_variable_set, but instead of providing the
583  *  name of link to be considered, provide the source and destination
584  *  hosts. All links that are part of the route between source and
585  *  destination will have the variable set to the provided value.
586  *
587  *  \param src The name of the source host for get route.
588  *  \param dst The name of the destination host for get route.
589  *  \param variable The name of the variable to be considered.
590  *  \param value The new value of the variable.
591  *
592  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add, TRACE_link_srcdst_variable_sub
593  */
594 void TRACE_link_srcdst_variable_set (const char *src, const char *dst, const char *variable, double value)
595 {
596   TRACE_link_srcdst_variable_set_with_time (MSG_get_clock(), src, dst, variable, value);
597 }
598
599 /** \ingroup TRACE_user_variables
600  *  \brief Add a value to the variable present in the links connecting source and destination.
601  *
602  *  Same as #TRACE_link_variable_add, but instead of providing the
603  *  name of link to be considered, provide the source and destination
604  *  hosts. All links that are part of the route between source and
605  *  destination will have the value passed as parameter added to
606  *  the current value of the variable name to be considered.
607  *
608  *  \param src The name of the source host for get route.
609  *  \param dst The name of the destination host for get route.
610  *  \param variable The name of the variable to be considered.
611  *  \param value The value to be added to the variable.
612  *
613  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_sub
614  */
615 void TRACE_link_srcdst_variable_add (const char *src, const char *dst, const char *variable, double value)
616 {
617   TRACE_link_srcdst_variable_add_with_time (MSG_get_clock(), src, dst, variable, value);
618 }
619
620 /** \ingroup TRACE_user_variables
621  *  \brief Subtract a value from the variable present in the links connecting source and destination.
622  *
623  *  Same as #TRACE_link_variable_sub, but instead of providing the
624  *  name of link to be considered, provide the source and destination
625  *  hosts. All links that are part of the route between source and
626  *  destination will have the value passed as parameter subtracted from
627  *  the current value of the variable name to be considered.
628  *
629  *  \param src The name of the source host for get route.
630  *  \param dst The name of the destination host for get route.
631  *  \param variable The name of the variable to be considered.
632  *  \param value The value to be subtracted from the variable.
633  *
634  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_add
635  */
636 void TRACE_link_srcdst_variable_sub (const char *src, const char *dst, const char *variable, double value)
637 {
638   TRACE_link_srcdst_variable_sub_with_time (MSG_get_clock(), src, dst, variable, value);
639 }
640
641 /** \ingroup TRACE_user_variables
642  *  \brief Set the value of the variable present in the links connecting source and destination at a given timestamp.
643  *
644  *  Same as #TRACE_link_srcdst_variable_set, but let user specify
645  *  the time used to trace it. Users can specify a time that
646  *  is not the simulated clock time as defined by the core
647  *  simulator. This allows a fine-grain control of time
648  *  definition, but should be used with caution since the trace
649  *  can be inconsistent if resource utilization traces are also traced.
650  *
651  *  \param time The timestamp to be used to tag this change of value.
652  *  \param src The name of the source host for get route.
653  *  \param dst The name of the destination host for get route.
654  *  \param variable The name of the variable to be considered.
655  *  \param value The new value of the variable.
656  *
657  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add_with_time, TRACE_link_srcdst_variable_sub_with_time
658  */
659 void TRACE_link_srcdst_variable_set_with_time (double time, const char *src, const char *dst, const char *variable, double value)
660 {
661   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SET);
662 }
663
664 /** \ingroup TRACE_user_variables
665  *  \brief Add a value to the variable present in the links connecting source and destination at a given timestamp.
666  *
667  *  Same as #TRACE_link_srcdst_variable_add, but let user specify
668  *  the time used to trace it. Users can specify a time that
669  *  is not the simulated clock time as defined by the core
670  *  simulator. This allows a fine-grain control of time
671  *  definition, but should be used with caution since the trace
672  *  can be inconsistent if resource utilization traces are also traced.
673  *
674  *  \param time The timestamp to be used to tag this change of value.
675  *  \param src The name of the source host for get route.
676  *  \param dst The name of the destination host for get route.
677  *  \param variable The name of the variable to be considered.
678  *  \param value The value to be added to the variable.
679  *
680  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_sub_with_time
681  */
682 void TRACE_link_srcdst_variable_add_with_time (double time, const char *src, const char *dst, const char *variable, double value)
683 {
684   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_ADD);
685 }
686
687 /** \ingroup TRACE_user_variables
688  *  \brief Subtract a value from the variable present in the links connecting source and destination at a given timestamp.
689  *
690  *  Same as #TRACE_link_srcdst_variable_sub, but let user specify
691  *  the time used to trace it. Users can specify a time that
692  *  is not the simulated clock time as defined by the core
693  *  simulator. This allows a fine-grain control of time
694  *  definition, but should be used with caution since the trace
695  *  can be inconsistent if resource utilization traces are also traced.
696  *
697  *  \param time The timestamp to be used to tag this change of value.
698  *  \param src The name of the source host for get route.
699  *  \param dst The name of the destination host for get route.
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_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_add_with_time
704  */
705 void TRACE_link_srcdst_variable_sub_with_time (double time, const char *src, const char *dst, const char *variable, double value)
706 {
707   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SUB);
708 }
709
710 #endif /* HAVE_TRACING */