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