src/instr/instr_interface.cpp

   1 /* Copyright (c) 2010-2022. 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/Exception.hpp>
   7 #include <simgrid/kernel/routing/NetPoint.hpp>
   8 #include <simgrid/s4u/Engine.hpp>
   9 #include <xbt/random.hpp>
  10
  11 #include "src/instr/instr_private.hpp"
  12 #include "src/kernel/resource/StandardLinkImpl.hpp"
  13 #include <algorithm>
  14 #include <cmath>
  15
  16 enum class InstrUserVariable { DECLARE, SET, ADD, SUB };
  17
  18 XBT_LOG_NEW_DEFAULT_SUBCATEGORY (instr_api, instr, "API");
  19
  20 std::set<std::string, std::less<>> created_categories;
  21 std::set<std::string, std::less<>> declared_marks;
  22 std::set<std::string, std::less<>> user_host_variables;
  23 std::set<std::string, std::less<>> user_vm_variables;
  24 std::set<std::string, std::less<>> user_link_variables;
  25
  26 static void instr_user_variable(double time, const std::string& resource, const std::string& variable_name,
  27                                 const std::string& parent_type, double value, InstrUserVariable what,
  28                                 const std::string& color, std::set<std::string, std::less<>>* filter)
  29 {
  30   /* safe switches. tracing has to be activated and if platform is not traced, we don't allow user variables */
  31   if (not TRACE_is_enabled() || not TRACE_needs_platform())
  32     return;
  33
  34   // check if variable is already declared
  35   auto created = filter->find(variable_name);
  36   if (what == InstrUserVariable::DECLARE) {
  37     if (created == filter->end()) { // not declared yet
  38       filter->insert(variable_name);
  39       instr_new_user_variable_type(parent_type, variable_name, color);
  40     }
  41   } else {
  42     if (created != filter->end()) { // declared, let's work
  43       simgrid::instr::VariableType* variable =
  44           simgrid::instr::Container::by_name(resource)->get_variable(variable_name);
  45       switch (what) {
  46         case InstrUserVariable::SET:
  47           variable->set_event(time, value);
  48           break;
  49         case InstrUserVariable::ADD:
  50           variable->add_event(time, value);
  51           break;
  52         case InstrUserVariable::SUB:
  53           variable->sub_event(time, value);
  54           break;
  55         default:
  56           THROW_IMPOSSIBLE;
  57       }
  58     }
  59   }
  60 }
  61
  62 static void instr_user_srcdst_variable(double time, const std::string& src, const std::string& dst,
  63                                        const std::string& variable, double value, InstrUserVariable what)
  64 {
  65   const auto* engine  = simgrid::s4u::Engine::get_instance();
  66   const auto* src_elm = engine->netpoint_by_name_or_null(src);
  67   xbt_assert(src_elm, "Element '%s' not found!", src.c_str());
  68
  69   const auto* dst_elm = engine->netpoint_by_name_or_null(dst);
  70   xbt_assert(dst_elm, "Element '%s' not found!", dst.c_str());
  71
  72   std::vector<simgrid::kernel::resource::StandardLinkImpl*> route;
  73   simgrid::kernel::routing::NetZoneImpl::get_global_route(src_elm, dst_elm, route, nullptr);
  74   for (auto const& link : route)
  75     instr_user_variable(time, link->get_cname(), variable, "LINK", value, what, "", &user_link_variables);
  76 }
  77
  78 namespace simgrid::instr {
  79 /* for host variables */
  80 /** @brief Declare a new user variable associated to hosts.
  81  *
  82  *  Declare a user variable that will be associated to hosts.
  83  *  A user host variable can be used to trace user variables such as the number of tasks in a server, the number of
  84  *  clients in an application (for hosts), and so on. The color associated to this new variable will be random if
  85  *  not given as parameter.
  86  */
  87 void declare_host_variable(const std::string& variable, const std::string& color)
  88 {
  89   instr_user_variable(0, "", variable, "HOST", 0, InstrUserVariable::DECLARE, color, &user_host_variables);
  90 }
  91
  92 void set_host_variable(const std::string& host, const std::string& variable, double value, double time)
  93 {
  94   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SET, "", &user_host_variables);
  95 }
  96
  97 /** @brief Add a value to a variable of a host */
  98 void add_host_variable(const std::string& host, const std::string& variable, double value, double time)
  99 {
 100   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::ADD, "", &user_host_variables);
 101 }
 102
 103 /** @brief Subtract a value to a variable of a host */
 104 void sub_host_variable(const std::string& host, const std::string& variable, double value, double time)
 105 {
 106   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SUB, "", &user_host_variables);
 107 }
 108
 109 /** @brief Get host variables that were already declared with #declare_host_variable. */
 110 const std::set<std::string, std::less<>>& get_host_variables()
 111 {
 112   return user_host_variables;
 113 }
 114
 115 /* for link variables */
 116 /** @brief Declare a new user variable associated to links.
 117  *
 118  *  Declare a user variable that will be associated to links.
 119  *  A user link variable can be used, for example, to trace user variables such as the number of messages being
 120  *  transferred through network links. The color associated to this new variable will be random if not given as
 121  *  parameter.
 122  */
 123 void declare_link_variable(const std::string& variable, const std::string& color)
 124 {
 125   instr_user_variable(0, "", variable, "LINK", 0, InstrUserVariable::DECLARE, color, &user_link_variables);
 126 }
 127
 128 /** @brief Set the value of a variable of a link */
 129 void set_link_variable(const std::string& link, const std::string& variable, double value, double time)
 130 {
 131   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SET, "", &user_link_variables);
 132 }
 133
 134 void set_link_variable(const std::string& src, const std::string& dst, const std::string& variable, double value,
 135                        double time)
 136 {
 137   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::SET);
 138 }
 139
 140 /** @brief Add a value to a variable of a link */
 141 void add_link_variable(const std::string& link, const std::string& variable, double value, double time)
 142 {
 143   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::ADD, "", &user_link_variables);
 144 }
 145
 146 /** @brief Add a value to a variable of a link */
 147 void add_link_variable(const std::string& src, const std::string& dst, const std::string& variable, double value,
 148                        double time)
 149 {
 150   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::ADD);
 151 }
 152
 153 /** @brief Subtract a value to a variable of a link */
 154 void sub_link_variable(const std::string& link, const std::string& variable, double value, double time)
 155 {
 156   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SUB, "", &user_link_variables);
 157 }
 158
 159 /** @brief Subtract a value to a variable of a link */
 160 void sub_link_variable(const std::string& src, const std::string& dst, const std::string& variable, double value,
 161                        double time)
 162 {
 163   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::SUB);
 164 }
 165
 166 /** @brief Get link variables that were already declared with #declare_link_variable. */
 167 const std::set<std::string, std::less<>>& get_link_variables()
 168 {
 169   return user_link_variables;
 170 }
 171
 172 /* for VM variables */
 173 /** @brief Declare a new user variable associated to VMs.
 174  *
 175  *  Declare a user variable that will be associated to VMs. A user host variable can be used to trace user variables
 176  *  such as the number of tasks in a VM, the number of clients in an application (for hosts), and so on. The color
 177  *  associated to this new variable will be random if not given as parameter.
 178  */
 179 void declare_vm_variable(const std::string& variable, const std::string& color)
 180 {
 181   instr_user_variable(0, "", variable, "VM", 0, InstrUserVariable::DECLARE, color, &user_vm_variables);
 182 }
 183
 184 /** @brief Set the value of a variable of a vm */
 185 void set_vm_variable(const std::string& vm, const std::string& variable, double value, double time)
 186 {
 187   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SET, "", &user_vm_variables);
 188 }
 189
 190 /** @brief Add a value to a variable of a VM */
 191 void add_vm_variable(const std::string& vm, const std::string& variable, double value, double time)
 192 {
 193   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::ADD, "", &user_vm_variables);
 194 }
 195
 196 /** @brief Subtract a value from a variable of a VM */
 197 void sub_vm_variable(const std::string& vm, const std::string& variable, double value, double time)
 198 {
 199   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SUB, "", &user_vm_variables);
 200 }
 201
 202 /** @brief Get VM variables that were already declared with #declare_vm_variable. */
 203 const std::set<std::string, std::less<>>& get_vm_variables()
 204 {
 205   return user_vm_variables;
 206 }
 207
 208 /**@brief Declare a new type for tracing mark.
 209  *
 210  * This function declares a new Paje event type in the trace file that can be used by simulators to declare
 211  * application-level marks. This function is independent of which API is used in SimGrid.
 212  */
 213 void declare_mark(const std::string& mark_type)
 214 {
 215   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
 216   if (not TRACE_is_enabled() || not TRACE_needs_platform())
 217     return;
 218
 219   // check if mark_type is already declared
 220   if (declared_marks.find(mark_type) != declared_marks.end()) {
 221     throw TracingError(XBT_THROW_POINT,
 222                        xbt::string_printf("mark_type with name (%s) is already declared", mark_type.c_str()));
 223   }
 224
 225   XBT_DEBUG("MARK,declare %s", mark_type.c_str());
 226   Container::get_root()->get_type()->by_name_or_create<EventType>(mark_type);
 227   declared_marks.emplace(mark_type);
 228 }
 229
 230 /** @brief Declare a new colored value for a previously declared mark type.
 231  *
 232  * This function declares a new colored value for a Paje event type in the trace file that can be used by simulators to
 233  * declare application-level marks. This function is independent of which API is used in SimGrid. The color needs to be
 234  * a string with three numbers separated by spaces in the range [0,1].
 235  * A light-gray color can be specified using "0.7 0.7 0.7" as color. If no color is provided, the default color used
 236  * will be white ("1 1 1").
 237  */
 238 void declare_mark_value(const std::string& mark_type, const std::string& mark_value, const std::string& mark_color)
 239 {
 240   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
 241   if (not TRACE_is_enabled() || not TRACE_needs_platform())
 242     return;
 243
 244   auto* type = static_cast<EventType*>(Container::get_root()->get_type()->by_name(mark_type));
 245   if (not type) {
 246     throw TracingError(XBT_THROW_POINT,
 247                        xbt::string_printf("mark_type with name (%s) is not declared", mark_type.c_str()));
 248   } else {
 249     XBT_DEBUG("MARK, declare_value %s %s %s", mark_type.c_str(), mark_value.c_str(), mark_color.c_str());
 250     type->add_entity_value(mark_value, mark_color);
 251   }
 252 }
 253
 254 /** @brief Create a new instance of a tracing mark type.
 255  *
 256  * This function creates a mark in the trace file. The first parameter had to be previously declared using
 257  * #declare_mark, the second is the identifier for this mark instance. We recommend that the mark_value is a
 258  * unique value for the whole simulation. Nevertheless, this is not a strong requirement: the trace will be valid even
 259  * if there are multiple mark identifiers for the same trace.
 260  */
 261 void mark(const std::string& mark_type, const std::string& mark_value)
 262 {
 263   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
 264   if (not TRACE_is_enabled() || not TRACE_needs_platform())
 265     return;
 266
 267   // check if mark_type is already declared
 268   auto* type = static_cast<EventType*>(Container::get_root()->get_type()->by_name(mark_type));
 269   if (not type) {
 270     throw TracingError(XBT_THROW_POINT,
 271                        xbt::string_printf("mark_type with name (%s) is not declared", mark_type.c_str()));
 272   } else {
 273     XBT_DEBUG("MARK %s %s", mark_type.c_str(), mark_value.c_str());
 274     new NewEvent(simgrid_get_clock(), Container::get_root(), type, type->get_entity_value(mark_value));
 275   }
 276 }
 277
 278 /** @brief Get marks that were already declared with #declare_mark. */
 279 const std::set<std::string, std::less<>>& get_marks()
 280 {
 281   return declared_marks;
 282 }
 283
 284 /** @brief Declare a new category.
 285  *
 286  *  This function should be used to define a user category. The category can be used to differentiate the tasks that
 287  *  are created during the simulation (for example, tasks from server1, server2, or request tasks, computation tasks,
 288  *  communication tasks). All resource utilization (host power and link bandwidth) will be classified according to the
 289  *  task category. Tasks that do not belong to a category are not traced. The color for the category that is being
 290  *  declared is random. This function has no effect if a category with the same name has been already declared.
 291  *
 292  * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
 293  */
 294 void declare_tracing_category(const std::string& name, const std::string& color)
 295 {
 296   /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with categories */
 297   if (not TRACE_is_enabled() || not TRACE_needs_platform() || not TRACE_categorized())
 298     return;
 299
 300   // check if category is already created
 301   if (created_categories.find(name) != created_categories.end())
 302     return;
 303
 304   created_categories.emplace(name);
 305
 306   // define final_color
 307   std::string final_color;
 308   if (color.empty()) {
 309     // generate a random color
 310     double red   = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
 311     double green = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
 312     double blue  = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
 313     final_color  = std::to_string(red) + " " + std::to_string(green) + " " + std::to_string(blue);
 314   } else {
 315     final_color = std::string(color);
 316   }
 317
 318   XBT_DEBUG("CAT,declare %s, \"%s\" \"%s\"", name.c_str(), color.c_str(), final_color.c_str());
 319
 320   // define the type of this category on top of hosts and links
 321   instr_new_variable_type(name, final_color);
 322 }
 323
 324 /** @brief Get categories that were already declared with #declare_tracing_category.
 325  *
 326  * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
 327  */
 328 const std::set<std::string, std::less<>>& get_tracing_categories()
 329 {
 330   return created_categories;
 331 }
 332
 333 } // namespace simgrid::instr
 334
 335 static xbt_dynar_t instr_set_to_dynar(const std::set<std::string, std::less<>>& filter) // XBT_ATTRIB_DEPRECATED_v334
 336 {
 337   if (not TRACE_is_enabled() || not TRACE_needs_platform())
 338     return nullptr;
 339
 340   xbt_dynar_t ret = xbt_dynar_new (sizeof(char*), &xbt_free_ref);
 341   for (auto const& name : filter)
 342     xbt_dynar_push_as(ret, char*, xbt_strdup(name.c_str()));
 343
 344   return ret;
 345 }
 346
 347 void TRACE_category(const char* category) // XBT_ATTRIB_DEPRECATED_v334
 348 {
 349   simgrid::instr::declare_tracing_category(category);
 350 }
 351
 352 void TRACE_category_with_color(const char* category, const char* color) // XBT_ATTRIB_DEPRECATED_v334
 353 {
 354   simgrid::instr::declare_tracing_category(category, color);
 355 }
 356
 357 xbt_dynar_t TRACE_get_categories() // XBT_ATTRIB_DEPRECATED_v334
 358 {
 359   if (not TRACE_is_enabled() || not TRACE_categorized())
 360     return nullptr;
 361   return instr_set_to_dynar(created_categories);
 362 }
 363
 364 void TRACE_declare_mark(const char* mark_type) // XBT_ATTRIB_DEPRECATED_v334
 365 {
 366   simgrid::instr::declare_mark(mark_type);
 367 }
 368
 369 void TRACE_declare_mark_value_with_color(const char* mark_type, const char* mark_value,
 370                                          const char* mark_color) // XBT_ATTRIB_DEPRECATED_v334
 371 {
 372   simgrid::instr::declare_mark_value(mark_type, mark_value, mark_color);
 373 }
 374
 375 void TRACE_declare_mark_value(const char* mark_type, const char* mark_value) // XBT_ATTRIB_DEPRECATED_v334
 376 {
 377   simgrid::instr::declare_mark_value(mark_type, mark_value);
 378 }
 379
 380 void TRACE_mark(const char* mark_type, const char* mark_value) // XBT_ATTRIB_DEPRECATED_v334
 381 {
 382   simgrid::instr::mark(mark_type, mark_value);
 383 }
 384
 385 xbt_dynar_t TRACE_get_marks() // XBT_ATTRIB_DEPRECATED_v334
 386 {
 387   if (not TRACE_is_enabled())
 388     return nullptr;
 389
 390   return instr_set_to_dynar(declared_marks);
 391 }
 392
 393 int TRACE_platform_graph_export_graphviz(const char* filename) // XBT_ATTRIB_DEPRECATED_v334
 394 {
 395   simgrid::instr::platform_graph_export_graphviz(filename);
 396   return 1;
 397 }
 398
 399 void TRACE_vm_variable_declare(const char* variable) // XBT_ATTRIB_DEPRECATED_v334
 400 {
 401   instr_user_variable(0, "", variable, "VM", 0, InstrUserVariable::DECLARE, "", &user_vm_variables);
 402 }
 403 void TRACE_vm_variable_declare_with_color(const char* variable, const char* color) // XBT_ATTRIB_DEPRECATED_v334
 404 {
 405   instr_user_variable(0, "", variable, "VM", 0, InstrUserVariable::DECLARE, color, &user_vm_variables);
 406 }
 407
 408 void TRACE_vm_variable_set(const char* vm, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 409 {
 410   instr_user_variable(simgrid_get_clock(), vm, variable, "VM", value, InstrUserVariable::SET, "", &user_vm_variables);
 411 }
 412
 413 void TRACE_vm_variable_add(const char* vm, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 414 {
 415   instr_user_variable(simgrid_get_clock(), vm, variable, "VM", value, InstrUserVariable::ADD, "", &user_vm_variables);
 416 }
 417 void TRACE_vm_variable_sub(const char* vm, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 418 {
 419   instr_user_variable(simgrid_get_clock(), vm, variable, "VM", value, InstrUserVariable::SUB, "", &user_vm_variables);
 420 }
 421
 422 void TRACE_vm_variable_set_with_time(double time, const char* vm, const char* variable,
 423                                      double value) // XBT_ATTRIB_DEPRECATED_v334
 424 {
 425   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SET, "", &user_vm_variables);
 426 }
 427
 428 void TRACE_vm_variable_add_with_time(double time, const char* vm, const char* variable,
 429                                      double value) // XBT_ATTRIB_DEPRECATED_v334
 430 {
 431   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::ADD, "", &user_vm_variables);
 432 }
 433 void TRACE_vm_variable_sub_with_time(double time, const char* vm, const char* variable,
 434                                      double value) // XBT_ATTRIB_DEPRECATED_v334
 435 {
 436   instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SUB, "", &user_vm_variables);
 437 }
 438
 439 void TRACE_host_variable_declare(const char* variable) // XBT_ATTRIB_DEPRECATED_v334
 440 {
 441   simgrid::instr::declare_host_variable(variable);
 442 }
 443
 444 void TRACE_host_variable_declare_with_color(const char* variable, const char* color) // XBT_ATTRIB_DEPRECATED_v334
 445 {
 446   simgrid::instr::declare_host_variable(variable, color);
 447 }
 448
 449 void TRACE_host_variable_set(const char* host, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 450 {
 451   instr_user_variable(simgrid_get_clock(), host, variable, "HOST", value, InstrUserVariable::SET, "",
 452                       &user_host_variables);
 453 }
 454
 455 void TRACE_host_variable_add(const char* host, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 456 {
 457   instr_user_variable(simgrid_get_clock(), host, variable, "HOST", value, InstrUserVariable::ADD, "",
 458                       &user_host_variables);
 459 }
 460
 461 void TRACE_host_variable_sub(const char* host, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 462 {
 463   instr_user_variable(simgrid_get_clock(), host, variable, "HOST", value, InstrUserVariable::SUB, "",
 464                       &user_host_variables);
 465 }
 466
 467 void TRACE_host_variable_set_with_time(double time, const char* host, const char* variable,
 468                                        double value) // XBT_ATTRIB_DEPRECATED_v334
 469 {
 470   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SET, "", &user_host_variables);
 471 }
 472
 473 void TRACE_host_variable_add_with_time(double time, const char* host, const char* variable,
 474                                        double value) // XBT_ATTRIB_DEPRECATED_v334
 475 {
 476   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::ADD, "", &user_host_variables);
 477 }
 478
 479 void TRACE_host_variable_sub_with_time(double time, const char* host, const char* variable,
 480                                        double value) // XBT_ATTRIB_DEPRECATED_v334
 481 {
 482   instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SUB, "", &user_host_variables);
 483 }
 484
 485 xbt_dynar_t TRACE_get_host_variables() // XBT_ATTRIB_DEPRECATED_v334
 486 {
 487   return instr_set_to_dynar(user_host_variables);
 488 }
 489
 490 void TRACE_link_variable_declare(const char* variable) // XBT_ATTRIB_DEPRECATED_v334
 491 {
 492   simgrid::instr::declare_link_variable(variable);
 493 }
 494
 495 void TRACE_link_variable_declare_with_color(const char* variable, const char* color) // XBT_ATTRIB_DEPRECATED_v334
 496 {
 497   simgrid::instr::declare_link_variable(variable, color);
 498 }
 499
 500 void TRACE_link_variable_set(const char* link, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 501 {
 502   instr_user_variable(simgrid_get_clock(), link, variable, "LINK", value, InstrUserVariable::SET, "",
 503                       &user_link_variables);
 504 }
 505
 506 void TRACE_link_variable_add(const char* link, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 507 {
 508   instr_user_variable(simgrid_get_clock(), link, variable, "LINK", value, InstrUserVariable::ADD, "",
 509                       &user_link_variables);
 510 }
 511
 512 void TRACE_link_variable_sub(const char* link, const char* variable, double value) // XBT_ATTRIB_DEPRECATED_v334
 513 {
 514   instr_user_variable(simgrid_get_clock(), link, variable, "LINK", value, InstrUserVariable::SUB, "",
 515                       &user_link_variables);
 516 }
 517
 518 void TRACE_link_variable_set_with_time(double time, const char* link, const char* variable,
 519                                        double value) // XBT_ATTRIB_DEPRECATED_v334
 520 {
 521   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SET, "", &user_link_variables);
 522 }
 523
 524 void TRACE_link_variable_add_with_time(double time, const char* link, const char* variable,
 525                                        double value) // XBT_ATTRIB_DEPRECATED_v334
 526 {
 527   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::ADD, "", &user_link_variables);
 528 }
 529
 530 void TRACE_link_variable_sub_with_time(double time, const char* link, const char* variable,
 531                                        double value) // XBT_ATTRIB_DEPRECATED_v334
 532 {
 533   instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SUB, "", &user_link_variables);
 534 }
 535
 536 void TRACE_link_srcdst_variable_set(const char* src, const char* dst, const char* variable,
 537                                     double value) // XBT_ATTRIB_DEPRECATED_v334
 538 {
 539   instr_user_srcdst_variable(simgrid_get_clock(), src, dst, variable, value, InstrUserVariable::SET);
 540 }
 541
 542 void TRACE_link_srcdst_variable_add(const char* src, const char* dst, const char* variable,
 543                                     double value) // XBT_ATTRIB_DEPRECATED_v334
 544 {
 545   instr_user_srcdst_variable(simgrid_get_clock(), src, dst, variable, value, InstrUserVariable::ADD);
 546 }
 547
 548 void TRACE_link_srcdst_variable_sub(const char* src, const char* dst, const char* variable,
 549                                     double value) // XBT_ATTRIB_DEPRECATED_v334
 550 {
 551   instr_user_srcdst_variable(simgrid_get_clock(), src, dst, variable, value, InstrUserVariable::SUB);
 552 }
 553
 554 void TRACE_link_srcdst_variable_set_with_time(double time, const char* src, const char* dst, const char* variable,
 555                                               double value) // XBT_ATTRIB_DEPRECATED_v334
 556 {
 557   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::SET);
 558 }
 559
 560 void TRACE_link_srcdst_variable_add_with_time(double time, const char* src, const char* dst, const char* variable,
 561                                               double value) // XBT_ATTRIB_DEPRECATED_v334
 562 {
 563   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::ADD);
 564 }
 565
 566 void TRACE_link_srcdst_variable_sub_with_time(double time, const char* src, const char* dst, const char* variable,
 567                                               double value) // XBT_ATTRIB_DEPRECATED_v334
 568 {
 569   instr_user_srcdst_variable(time, src, dst, variable, value, InstrUserVariable::SUB);
 570 }
 571
 572 xbt_dynar_t TRACE_get_link_variables() // XBT_ATTRIB_DEPRECATED_v334
 573 {
 574   return instr_set_to_dynar(user_link_variables);
 575 }
 576
 577 /** @ingroup TRACE_user_variables
 578  *  @brief Declare a new user state associated to hosts.
 579  *
 580  *  Declare a user state that will be associated to hosts.
 581  *  A user host state can be used to trace application states.
 582  *
 583  *  @param state The name of the new state to be declared.
 584  *
 585  *  @see TRACE_host_state_declare_value
 586  */
 587 void TRACE_host_state_declare (const char *state)
 588 {
 589   instr_new_user_state_type("HOST", state);
 590 }
 591
 592 /** @ingroup TRACE_user_variables
 593  *  @brief Declare a new value for a user state associated to hosts.
 594  *
 595  *  Declare a value for a state. The color needs to be a string with 3 numbers separated by spaces in the range [0,1].
 596  *  A light-gray color can be specified using "0.7 0.7 0.7" as color.
 597  *
 598  *  @param state The name of the new state to be declared.
 599  *  @param value The name of the value
 600  *  @param color The color of the value
 601  *
 602  *  @see TRACE_host_state_declare
 603  */
 604 void TRACE_host_state_declare_value (const char *state, const char *value, const char *color)
 605 {
 606   instr_new_value_for_user_state_type (state, value, color);
 607 }
 608
 609 /** @ingroup TRACE_user_variables
 610  *  @brief Set the user state to the given value.
 611  *
 612  *  Change a user state previously declared to the given value.
 613  *
 614  *  @param host The name of the host to be considered.
 615  *  @param state_name The name of the state previously declared.
 616  *  @param value_name The new value of the state.
 617  *
 618  *  @see TRACE_host_state_declare, TRACE_host_push_state, TRACE_host_pop_state
 619  */
 620 void TRACE_host_set_state(const char* host, const char* state_name, const char* value_name)
 621 {
 622   simgrid::instr::StateType* state = simgrid::instr::Container::by_name(host)->get_state(state_name);
 623   state->add_entity_value(value_name);
 624   state->set_event(value_name);
 625 }
 626
 627 /** @ingroup TRACE_user_variables
 628  *  @brief Push a new value for a state of a given host.
 629  *
 630  *  Change a user state previously declared by pushing the new value to the state.
 631  *
 632  *  @param host The name of the host to be considered.
 633  *  @param state_name The name of the state previously declared.
 634  *  @param value_name The value to be pushed.
 635  *
 636  *  @see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_pop_state
 637  */
 638 void TRACE_host_push_state(const char* host, const char* state_name, const char* value_name)
 639 {
 640   simgrid::instr::Container::by_name(host)->get_state(state_name)->push_event(value_name);
 641 }
 642
 643 /** @ingroup TRACE_user_variables
 644  *  @brief Pop the last value of a state of a given host.
 645  *
 646  *  Change a user state previously declared by removing the last value of the state.
 647  *
 648  *  @param host The name of the host to be considered.
 649  *  @param state_name The name of the state to be popped.
 650  *
 651  *  @see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state
 652  */
 653 void TRACE_host_pop_state(const char* host, const char* state_name)
 654 {
 655   simgrid::instr::Container::by_name(host)->get_state(state_name)->pop_event();
 656 }