src/instr/instr_interface.cpp

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