src/instr/instr_interface.cpp

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