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 static xbt_dynar_t instr_get_user_variables (xbt_dict_t filter)
 487 {
 488   if (!TRACE_is_enabled()) return NULL;
 489   if (!TRACE_needs_platform()) return NULL;
 490
 491   xbt_dynar_t ret = xbt_dynar_new (sizeof(char*), &xbt_free_ref);
 492   xbt_dict_cursor_t cursor = NULL;
 493   char *name, *value;
 494   xbt_dict_foreach(filter, cursor, name, value) {
 495     xbt_dynar_push_as (ret, char*, xbt_strdup(name));
 496   }
 497   return ret;
 498 }
 499
 500 /** \ingroup TRACE_user_variables
 501  *  \brief Get declared user host variables
 502  *
 503  * This function should be used to get host variables that were already
 504  * declared with #TRACE_host_variable_declare or with #TRACE_host_variable_declare_with_color.
 505  *
 506  * \return A dynar with the declared host variables, must be freed with xbt_dynar_free.
 507  */
 508 xbt_dynar_t TRACE_get_host_variables (void)
 509 {
 510   return instr_get_user_variables (user_host_variables);
 511 }
 512
 513 /* for link variables */
 514 /** \ingroup TRACE_user_variables
 515  *  \brief Declare a new user variable associated to links.
 516  *
 517  *  Declare a user variable that will be associated to links.
 518  *  A user link variable can be used, for example, to trace
 519  *  user variables such as the number of messages being
 520  *  transferred through network links. The color
 521  *  associated to this new variable will be random.
 522  *
 523  *  \param variable The name of the new variable to be declared.
 524  *
 525  *  \see TRACE_link_variable_declare_with_color
 526  */
 527 void TRACE_link_variable_declare (const char *variable)
 528 {
 529   instr_user_variable (0, NULL, variable, "LINK", 0, INSTR_US_DECLARE, NULL, user_link_variables);
 530 }
 531
 532 /** \ingroup TRACE_user_variables
 533  *  \brief Declare a new user variable associated to links with a color.
 534  *
 535  *  Same as #TRACE_link_variable_declare, but associated a color
 536  *  to the newly created user link variable. The color needs to be
 537  *  a string with three numbers separated by spaces in the range [0,1].
 538  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
 539  *
 540  *  \param variable The name of the new variable to be declared.
 541  *  \param color The color for the new variable.
 542  *
 543  */
 544 void TRACE_link_variable_declare_with_color (const char *variable, const char *color)
 545 {
 546   instr_user_variable (0, NULL, variable, "LINK", 0, INSTR_US_DECLARE, color, user_link_variables);
 547 }
 548
 549 /** \ingroup TRACE_user_variables
 550  *  \brief Set the value of a variable of a link.
 551  *
 552  *  \param link The name of the link to be considered.
 553  *  \param variable The name of the variable to be considered.
 554  *  \param value The new value of the variable.
 555  *
 556  *  \see TRACE_link_variable_declare, TRACE_link_variable_add, TRACE_link_variable_sub
 557  */
 558 void TRACE_link_variable_set (const char *link, const char *variable, double value)
 559 {
 560   TRACE_link_variable_set_with_time (MSG_get_clock(), link, variable, value);
 561 }
 562
 563 /** \ingroup TRACE_user_variables
 564  *  \brief Add a value to a variable of a link.
 565  *
 566  *  \param link The name of the link to be considered.
 567  *  \param variable The name of the variable to be considered.
 568  *  \param value The value to be added to the variable.
 569  *
 570  *  \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_sub
 571  */
 572 void TRACE_link_variable_add (const char *link, const char *variable, double value)
 573 {
 574   TRACE_link_variable_add_with_time (MSG_get_clock(), link, variable, value);
 575 }
 576
 577 /** \ingroup TRACE_user_variables
 578  *  \brief Subtract a value from a variable of a link.
 579  *
 580  *  \param link The name of the link to be considered.
 581  *  \param variable The name of the variable to be considered.
 582  *  \param value The value to be subtracted from the variable.
 583  *
 584  *  \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_add
 585  */
 586 void TRACE_link_variable_sub (const char *link, const char *variable, double value)
 587 {
 588   TRACE_link_variable_sub_with_time (MSG_get_clock(), link, variable, value);
 589 }
 590
 591 /** \ingroup TRACE_user_variables
 592  *  \brief Set the value of a variable of a link at a given timestamp.
 593  *
 594  *  Same as #TRACE_link_variable_set, but let user specify
 595  *  the time used to trace it. Users can specify a time that
 596  *  is not the simulated clock time as defined by the core
 597  *  simulator. This allows a fine-grain control of time
 598  *  definition, but should be used with caution since the trace
 599  *  can be inconsistent if resource utilization traces are also traced.
 600  *
 601  *  \param time The timestamp to be used to tag this change of value.
 602  *  \param link The name of the link to be considered.
 603  *  \param variable The name of the variable to be considered.
 604  *  \param value The new value of the variable.
 605  *
 606  *  \see TRACE_link_variable_declare, TRACE_link_variable_add_with_time, TRACE_link_variable_sub_with_time
 607  */
 608 void TRACE_link_variable_set_with_time (double time, const char *link, const char *variable, double value)
 609 {
 610   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SET, NULL, user_link_variables);
 611 }
 612
 613 /** \ingroup TRACE_user_variables
 614  *  \brief Add a value to a variable of a link at a given timestamp.
 615  *
 616  *  Same as #TRACE_link_variable_add, but let user specify
 617  *  the time used to trace it. Users can specify a time that
 618  *  is not the simulated clock time as defined by the core
 619  *  simulator. This allows a fine-grain control of time
 620  *  definition, but should be used with caution since the trace
 621  *  can be inconsistent if resource utilization traces are also traced.
 622  *
 623  *  \param time The timestamp to be used to tag this change of value.
 624  *  \param link The name of the link to be considered.
 625  *  \param variable The name of the variable to be considered.
 626  *  \param value The value to be added to the variable.
 627  *
 628  *  \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_sub_with_time
 629  */
 630 void TRACE_link_variable_add_with_time (double time, const char *link, const char *variable, double value)
 631 {
 632   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_ADD, NULL, user_link_variables);
 633 }
 634
 635 /** \ingroup TRACE_user_variables
 636  *  \brief Subtract a value from a variable of a link at a given timestamp.
 637  *
 638  *  Same as #TRACE_link_variable_sub, but let user specify
 639  *  the time used to trace it. Users can specify a time that
 640  *  is not the simulated clock time as defined by the core
 641  *  simulator. This allows a fine-grain control of time
 642  *  definition, but should be used with caution since the trace
 643  *  can be inconsistent if resource utilization traces are also traced.
 644  *
 645  *  \param time The timestamp to be used to tag this change of value.
 646  *  \param link The name of the link to be considered.
 647  *  \param variable The name of the variable to be considered.
 648  *  \param value The value to be subtracted from the variable.
 649  *
 650  *  \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_add_with_time
 651  */
 652 void TRACE_link_variable_sub_with_time (double time, const char *link, const char *variable, double value)
 653 {
 654   instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SUB, NULL, user_link_variables);
 655 }
 656
 657 /* for link variables, but with src and dst used for get_route */
 658 /** \ingroup TRACE_user_variables
 659  *  \brief Set the value of the variable present in the links connecting source and destination.
 660  *
 661  *  Same as #TRACE_link_variable_set, but instead of providing the
 662  *  name of link to be considered, provide the source and destination
 663  *  hosts. All links that are part of the route between source and
 664  *  destination will have the variable set to the provided value.
 665  *
 666  *  \param src The name of the source host for get route.
 667  *  \param dst The name of the destination host for get route.
 668  *  \param variable The name of the variable to be considered.
 669  *  \param value The new value of the variable.
 670  *
 671  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add, TRACE_link_srcdst_variable_sub
 672  */
 673 void TRACE_link_srcdst_variable_set (const char *src, const char *dst, const char *variable, double value)
 674 {
 675   TRACE_link_srcdst_variable_set_with_time (MSG_get_clock(), src, dst, variable, value);
 676 }
 677
 678 /** \ingroup TRACE_user_variables
 679  *  \brief Add a value to the variable present in the links connecting source and destination.
 680  *
 681  *  Same as #TRACE_link_variable_add, but instead of providing the
 682  *  name of link to be considered, provide the source and destination
 683  *  hosts. All links that are part of the route between source and
 684  *  destination will have the value passed as parameter added to
 685  *  the current value of the variable name to be considered.
 686  *
 687  *  \param src The name of the source host for get route.
 688  *  \param dst The name of the destination host for get route.
 689  *  \param variable The name of the variable to be considered.
 690  *  \param value The value to be added to the variable.
 691  *
 692  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_sub
 693  */
 694 void TRACE_link_srcdst_variable_add (const char *src, const char *dst, const char *variable, double value)
 695 {
 696   TRACE_link_srcdst_variable_add_with_time (MSG_get_clock(), src, dst, variable, value);
 697 }
 698
 699 /** \ingroup TRACE_user_variables
 700  *  \brief Subtract a value from the variable present in the links connecting source and destination.
 701  *
 702  *  Same as #TRACE_link_variable_sub, but instead of providing the
 703  *  name of link to be considered, provide the source and destination
 704  *  hosts. All links that are part of the route between source and
 705  *  destination will have the value passed as parameter subtracted from
 706  *  the current value of the variable name to be considered.
 707  *
 708  *  \param src The name of the source host for get route.
 709  *  \param dst The name of the destination host for get route.
 710  *  \param variable The name of the variable to be considered.
 711  *  \param value The value to be subtracted from the variable.
 712  *
 713  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_add
 714  */
 715 void TRACE_link_srcdst_variable_sub (const char *src, const char *dst, const char *variable, double value)
 716 {
 717   TRACE_link_srcdst_variable_sub_with_time (MSG_get_clock(), src, dst, variable, value);
 718 }
 719
 720 /** \ingroup TRACE_user_variables
 721  *  \brief Set the value of the variable present in the links connecting source and destination at a given timestamp.
 722  *
 723  *  Same as #TRACE_link_srcdst_variable_set, but let user specify
 724  *  the time used to trace it. Users can specify a time that
 725  *  is not the simulated clock time as defined by the core
 726  *  simulator. This allows a fine-grain control of time
 727  *  definition, but should be used with caution since the trace
 728  *  can be inconsistent if resource utilization traces are also traced.
 729  *
 730  *  \param time The timestamp to be used to tag this change of value.
 731  *  \param src The name of the source host for get route.
 732  *  \param dst The name of the destination host for get route.
 733  *  \param variable The name of the variable to be considered.
 734  *  \param value The new value of the variable.
 735  *
 736  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add_with_time, TRACE_link_srcdst_variable_sub_with_time
 737  */
 738 void TRACE_link_srcdst_variable_set_with_time (double time, const char *src, const char *dst, const char *variable, double value)
 739 {
 740   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SET);
 741 }
 742
 743 /** \ingroup TRACE_user_variables
 744  *  \brief Add a value to the variable present in the links connecting source and destination at a given timestamp.
 745  *
 746  *  Same as #TRACE_link_srcdst_variable_add, but let user specify
 747  *  the time used to trace it. Users can specify a time that
 748  *  is not the simulated clock time as defined by the core
 749  *  simulator. This allows a fine-grain control of time
 750  *  definition, but should be used with caution since the trace
 751  *  can be inconsistent if resource utilization traces are also traced.
 752  *
 753  *  \param time The timestamp to be used to tag this change of value.
 754  *  \param src The name of the source host for get route.
 755  *  \param dst The name of the destination host for get route.
 756  *  \param variable The name of the variable to be considered.
 757  *  \param value The value to be added to the variable.
 758  *
 759  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_sub_with_time
 760  */
 761 void TRACE_link_srcdst_variable_add_with_time (double time, const char *src, const char *dst, const char *variable, double value)
 762 {
 763   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_ADD);
 764 }
 765
 766 /** \ingroup TRACE_user_variables
 767  *  \brief Subtract a value from the variable present in the links connecting source and destination at a given timestamp.
 768  *
 769  *  Same as #TRACE_link_srcdst_variable_sub, but let user specify
 770  *  the time used to trace it. Users can specify a time that
 771  *  is not the simulated clock time as defined by the core
 772  *  simulator. This allows a fine-grain control of time
 773  *  definition, but should be used with caution since the trace
 774  *  can be inconsistent if resource utilization traces are also traced.
 775  *
 776  *  \param time The timestamp to be used to tag this change of value.
 777  *  \param src The name of the source host for get route.
 778  *  \param dst The name of the destination host for get route.
 779  *  \param variable The name of the variable to be considered.
 780  *  \param value The value to be subtracted from the variable.
 781  *
 782  *  \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_add_with_time
 783  */
 784 void TRACE_link_srcdst_variable_sub_with_time (double time, const char *src, const char *dst, const char *variable, double value)
 785 {
 786   instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SUB);
 787 }
 788
 789 /** \ingroup TRACE_user_variables
 790  *  \brief Get declared user link variables
 791  *
 792  * This function should be used to get link variables that were already
 793  * declared with #TRACE_link_variable_declare or with #TRACE_link_variable_declare_with_color.
 794  *
 795  * \return A dynar with the declared link variables, must be freed with xbt_dynar_free.
 796  */
 797 xbt_dynar_t TRACE_get_link_variables (void)
 798 {
 799   return instr_get_user_variables (user_link_variables);
 800 }
 801
 802 #endif /* HAVE_TRACING */