1 /* Copyright (c) 2010-2021. The SimGrid Team. All rights reserved. */
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. */
6 #include <simgrid/Exception.hpp>
7 #include <simgrid/kernel/routing/NetPoint.hpp>
8 #include <xbt/random.hpp>
10 #include "src/instr/instr_private.hpp"
11 #include "src/kernel/resource/StandardLinkImpl.hpp"
15 enum class InstrUserVariable { DECLARE, SET, ADD, SUB };
17 XBT_LOG_NEW_DEFAULT_SUBCATEGORY (instr_api, instr, "API");
19 std::set<std::string, std::less<>> created_categories;
20 std::set<std::string, std::less<>> declared_marks;
21 std::set<std::string, std::less<>> user_host_variables;
22 std::set<std::string, std::less<>> user_vm_variables;
23 std::set<std::string, std::less<>> user_link_variables;
25 static xbt_dynar_t instr_set_to_dynar(const std::set<std::string, std::less<>>& filter)
27 if (not TRACE_is_enabled() || not TRACE_needs_platform())
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()));
37 /** @ingroup TRACE_category
38 * @brief Declare a new category with a random color.
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.
46 * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
48 * @param category The name of the new tracing category to be created.
50 * @see TRACE_category_with_color, MSG_task_set_category, SD_task_set_category
52 void TRACE_category(const char *category)
54 TRACE_category_with_color (category, nullptr);
57 /** @ingroup TRACE_category
58 * @brief Declare a new category with a color.
60 * Same as #TRACE_category, but let user specify a color encoded as an 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.
64 * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
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)
70 * @see MSG_task_set_category, SD_task_set_category
72 void TRACE_category_with_color (const char *category, const char *color)
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())
78 if (not(TRACE_categorized() && category != nullptr))
81 //check if category is already created
82 if (created_categories.find(category) != created_categories.end())
85 created_categories.emplace(category);
88 std::string final_color;
90 //generate a random color
91 double red = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
92 double green = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
93 double blue = simgrid::xbt::random::uniform_real(0.0, std::nextafter(1.0, 2.0));
94 final_color = std::to_string(red) + " " + std::to_string(green) + " " + std::to_string(blue);
96 final_color = std::string(color);
99 XBT_DEBUG("CAT,declare %s, \"%s\" \"%s\"", category, color, final_color.c_str());
101 //define the type of this category on top of hosts and links
102 instr_new_variable_type (category, final_color);
105 /** @ingroup TRACE_category
106 * @brief Get declared categories
108 * This function should be used to get categories that were already declared with #TRACE_category or with
109 * #TRACE_category_with_color.
111 * See @ref outcomes_vizu for details on how to trace the (categorized) resource utilization.
113 * @return A dynar with the declared categories, must be freed with xbt_dynar_free.
115 * @see MSG_task_set_category, SD_task_set_category
117 xbt_dynar_t TRACE_get_categories ()
119 if (not TRACE_is_enabled() || not TRACE_categorized())
121 return instr_set_to_dynar(created_categories);
124 /** @ingroup TRACE_mark
125 * @brief Declare a new type for tracing mark.
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.
130 * @param mark_type The name of the new type.
134 void TRACE_declare_mark(const char *mark_type)
136 /* safe switches. 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())
140 xbt_assert(mark_type, "mark_type is nullptr");
142 //check if mark_type is already declared
143 if (declared_marks.find(mark_type) != declared_marks.end()) {
144 throw simgrid::TracingError(XBT_THROW_POINT,
145 simgrid::xbt::string_printf("mark_type with name (%s) is already declared", mark_type));
148 XBT_DEBUG("MARK,declare %s", mark_type);
149 simgrid::instr::Container::get_root()->get_type()->by_name_or_create<simgrid::instr::EventType>(mark_type);
150 declared_marks.emplace(mark_type);
153 /** @ingroup TRACE_mark
154 * @brief Declare a new colored value for a previously declared mark type.
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").
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.
168 void TRACE_declare_mark_value_with_color (const char *mark_type, const char *mark_value, const char *mark_color)
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())
174 xbt_assert(mark_type, "mark_type is nullptr");
175 xbt_assert(mark_value, "mark_value is nullptr");
178 static_cast<simgrid::instr::EventType*>(simgrid::instr::Container::get_root()->get_type()->by_name(mark_type));
180 throw simgrid::TracingError(XBT_THROW_POINT,
181 simgrid::xbt::string_printf("mark_type with name (%s) is not declared", mark_type));
184 mark_color = "1.0 1.0 1.0" /*white*/;
186 XBT_DEBUG("MARK,declare_value %s %s %s", mark_type, mark_value, mark_color);
187 type->add_entity_value(mark_value, mark_color);
191 /** @ingroup TRACE_mark
192 * @brief Declare a new value for a previously declared mark type.
194 * This function declares a new value for a Paje event type in the trace file that can be used by simulators to declare
195 * application-level marks. This function is independent of which API is used in SimGrid. Calling this function is the
196 * same as calling @ref TRACE_declare_mark_value_with_color with a nullptr color.
198 * @param mark_type The name of the new type.
199 * @param mark_value The name of the new value for this type.
203 void TRACE_declare_mark_value (const char *mark_type, const char *mark_value)
205 TRACE_declare_mark_value_with_color (mark_type, mark_value, nullptr);
209 * @ingroup TRACE_mark
210 * @brief Create a new instance of a tracing mark type.
212 * This function creates a mark in the trace file. The first parameter had to be previously declared using
213 * #TRACE_declare_mark, the second is the identifier for this mark instance. We recommend that the mark_value is a
214 * unique value for the whole simulation. Nevertheless, this is not a strong requirement: the trace will be valid even
215 * if there are multiple mark identifiers for the same trace.
217 * @param mark_type The name of the type for which the new instance will belong.
218 * @param mark_value The name of the new instance mark.
220 * @see TRACE_declare_mark
222 void TRACE_mark(const char *mark_type, const char *mark_value)
224 /* safe switches. tracing has to be activated and if platform is not traced, we can't deal with marks */
225 if (not TRACE_is_enabled() || not TRACE_needs_platform())
228 xbt_assert(mark_type, "mark_type is nullptr");
229 xbt_assert(mark_value, "mark_value is nullptr");
231 //check if mark_type is already declared
233 static_cast<simgrid::instr::EventType*>(simgrid::instr::Container::get_root()->get_type()->by_name(mark_type));
235 throw simgrid::TracingError(XBT_THROW_POINT,
236 simgrid::xbt::string_printf("mark_type with name (%s) is not declared", mark_type));
238 XBT_DEBUG("MARK %s %s", mark_type, mark_value);
239 new simgrid::instr::NewEvent(simgrid_get_clock(), simgrid::instr::Container::get_root(), type,
240 type->get_entity_value(mark_value));
244 /** @ingroup TRACE_mark
245 * @brief Get declared marks
247 * This function should be used to get marks that were already declared with #TRACE_declare_mark.
249 * @return A dynar with the declared marks, must be freed with xbt_dynar_free.
251 xbt_dynar_t TRACE_get_marks ()
253 if (not TRACE_is_enabled())
256 return instr_set_to_dynar(declared_marks);
259 static void instr_user_variable(double time, const char* resource, const char* variable_name, const char* parent_type,
260 double value, InstrUserVariable what, const char* color,
261 std::set<std::string, std::less<>>* filter)
263 /* safe switches. tracing has to be activated and if platform is not traced, we don't allow user variables */
264 if (not TRACE_is_enabled() || not TRACE_needs_platform())
267 //check if variable is already declared
268 auto created = filter->find(variable_name);
269 if (what == InstrUserVariable::DECLARE) {
270 if (created == filter->end()) { // not declared yet
271 filter->insert(variable_name);
272 instr_new_user_variable_type(parent_type, variable_name, color == nullptr ? "" : color);
275 if (created != filter->end()) { // declared, let's work
276 simgrid::instr::VariableType* variable =
277 simgrid::instr::Container::by_name(resource)->get_variable(variable_name);
279 case InstrUserVariable::SET:
280 variable->set_event(time, value);
282 case InstrUserVariable::ADD:
283 variable->add_event(time, value);
285 case InstrUserVariable::SUB:
286 variable->sub_event(time, value);
295 static void instr_user_srcdst_variable(double time, const char* src, const char* dst, const char* variable,
296 const char* parent_type, double value, InstrUserVariable what)
298 const simgrid::kernel::routing::NetPoint* src_elm = sg_netpoint_by_name_or_null(src);
299 xbt_assert(src_elm, "Element '%s' not found!", src);
301 const simgrid::kernel::routing::NetPoint* dst_elm = sg_netpoint_by_name_or_null(dst);
302 xbt_assert(dst_elm, "Element '%s' not found!", dst);
304 std::vector<simgrid::kernel::resource::StandardLinkImpl*> route;
305 simgrid::kernel::routing::NetZoneImpl::get_global_route(src_elm, dst_elm, route, nullptr);
306 for (auto const& link : route)
307 instr_user_variable(time, link->get_cname(), variable, parent_type, value, what, nullptr, &user_link_variables);
310 /** @ingroup TRACE_API
311 * @brief Creates a file with the topology of the platform file used for the simulator.
313 * The graph topology will have the following properties: all hosts, links and routers of the platform file are mapped
314 * to graph nodes; routes are mapped to edges.
315 * The platform's zones are not represented in the output.
317 * @param filename The name of the file that will hold the graph.
319 * @return 1 of successful, 0 otherwise.
321 int TRACE_platform_graph_export_graphviz (const char *filename)
323 simgrid::instr::platform_graph_export_graphviz(filename);
328 * Derived functions that use instr_user_variable and TRACE_user_srcdst_variable. They were previously defined as
329 * pre-processors directives, but were transformed into functions so the user can track them using gdb.
332 /* for VM variables */
333 /** @ingroup TRACE_user_variables
334 * @brief Declare a new user variable associated to VMs.
336 * Declare a user variable that will be associated to VMs. A user vm variable can be used to trace user variables
337 * such as the number of tasks in a VM, the number of clients in an application (for VMs), and so on. The color
338 * associated to this new variable will be random.
340 * @param variable The name of the new variable to be declared.
342 * @see TRACE_vm_variable_declare_with_color
344 void TRACE_vm_variable_declare (const char *variable)
346 instr_user_variable(0, nullptr, variable, "VM", 0, InstrUserVariable::DECLARE, nullptr, &user_vm_variables);
349 /** @ingroup TRACE_user_variables
350 * @brief Declare a new user variable associated to VMs with a color.
352 * Same as #TRACE_vm_variable_declare, but associated a color to the newly created user host variable. The color needs
353 * to be a string with three numbers separated by spaces in the range [0,1].
354 * A light-gray color can be specified using "0.7 0.7 0.7" as color.
356 * @param variable The name of the new variable to be declared.
357 * @param color The color for the new variable.
359 void TRACE_vm_variable_declare_with_color (const char *variable, const char *color)
361 instr_user_variable(0, nullptr, variable, "VM", 0, InstrUserVariable::DECLARE, color, &user_vm_variables);
364 /** @ingroup TRACE_user_variables
365 * @brief Set the value of a variable of a host.
367 * @param vm The name of the VM to be considered.
368 * @param variable The name of the variable to be considered.
369 * @param value The new value of the variable.
371 * @see TRACE_vm_variable_declare, TRACE_vm_variable_add, TRACE_vm_variable_sub
373 void TRACE_vm_variable_set (const char *vm, const char *variable, double value)
375 TRACE_vm_variable_set_with_time(simgrid_get_clock(), vm, variable, value);
378 /** @ingroup TRACE_user_variables
379 * @brief Add a value to a variable of a VM.
381 * @param vm The name of the VM to be considered.
382 * @param variable The name of the variable to be considered.
383 * @param value The value to be added to the variable.
385 * @see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_sub
387 void TRACE_vm_variable_add (const char *vm, const char *variable, double value)
389 TRACE_vm_variable_add_with_time(simgrid_get_clock(), vm, variable, value);
392 /** @ingroup TRACE_user_variables
393 * @brief Subtract a value from a variable of a VM.
395 * @param vm The name of the vm to be considered.
396 * @param variable The name of the variable to be considered.
397 * @param value The value to be subtracted from the variable.
399 * @see TRACE_vm_variable_declare, TRACE_vm_variable_set, TRACE_vm_variable_add
401 void TRACE_vm_variable_sub (const char *vm, const char *variable, double value)
403 TRACE_vm_variable_sub_with_time(simgrid_get_clock(), vm, variable, value);
406 /** @ingroup TRACE_user_variables
407 * @brief Set the value of a variable of a VM at a given timestamp.
409 * Same as #TRACE_vm_variable_set, but let user specify the time used to trace it. Users can specify a time that
410 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
411 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
414 * @param time The timestamp to be used to tag this change of value.
415 * @param vm The name of the VM to be considered.
416 * @param variable The name of the variable to be considered.
417 * @param value The new value of the variable.
419 * @see TRACE_vm_variable_declare, TRACE_vm_variable_add_with_time, TRACE_vm_variable_sub_with_time
421 void TRACE_vm_variable_set_with_time (double time, const char *vm, const char *variable, double value)
423 instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SET, nullptr, &user_vm_variables);
426 /** @ingroup TRACE_user_variables
427 * @brief Add a value to a variable of a VM at a given timestamp.
429 * Same as #TRACE_vm_variable_add, but let user specify the time used to trace it. Users can specify a time that
430 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
431 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
434 * @param time The timestamp to be used to tag this change of value.
435 * @param vm The name of the VM to be considered.
436 * @param variable The name of the variable to be considered.
437 * @param value The value to be added to the variable.
439 * @see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_sub_with_time
441 void TRACE_vm_variable_add_with_time (double time, const char *vm, const char *variable, double value)
443 instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::ADD, nullptr, &user_vm_variables);
446 /** @ingroup TRACE_user_variables
447 * @brief Subtract a value from a variable of a VM at a given timestamp.
449 * Same as #TRACE_vm_variable_sub, but let user specify the time used to trace it. Users can specify a time that
450 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
451 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
454 * @param time The timestamp to be used to tag this change of value.
455 * @param vm The name of the VM to be considered.
456 * @param variable The name of the variable to be considered.
457 * @param value The value to be subtracted from the variable.
459 * @see TRACE_vm_variable_declare, TRACE_vm_variable_set_with_time, TRACE_vm_variable_add_with_time
461 void TRACE_vm_variable_sub_with_time (double time, const char *vm, const char *variable, double value)
463 instr_user_variable(time, vm, variable, "VM", value, InstrUserVariable::SUB, nullptr, &user_vm_variables);
466 /* for host variables */
467 /** @ingroup TRACE_user_variables
468 * @brief Declare a new user variable associated to hosts.
470 * Declare a user variable that will be associated to hosts.
471 * A user host variable can be used to trace user variables such as the number of tasks in a server, the number of
472 * clients in an application (for hosts), and so on. The color associated to this new variable will be random.
474 * @param variable The name of the new variable to be declared.
476 * @see TRACE_host_variable_declare_with_color
478 void TRACE_host_variable_declare (const char *variable)
480 instr_user_variable(0, nullptr, variable, "HOST", 0, InstrUserVariable::DECLARE, nullptr, &user_host_variables);
483 /** @ingroup TRACE_user_variables
484 * @brief Declare a new user variable associated to hosts with a color.
486 * Same as #TRACE_host_variable_declare, but associated a color to the newly created user host variable. The color
487 * needs to be a string with three numbers separated by spaces in the range [0,1].
488 * A light-gray color can be specified using "0.7 0.7 0.7" as color.
490 * @param variable The name of the new variable to be declared.
491 * @param color The color for the new variable.
493 void TRACE_host_variable_declare_with_color (const char *variable, const char *color)
495 instr_user_variable(0, nullptr, variable, "HOST", 0, InstrUserVariable::DECLARE, color, &user_host_variables);
498 /** @ingroup TRACE_user_variables
499 * @brief Set the value of a variable of a host.
501 * @param host The name of the host to be considered.
502 * @param variable The name of the variable to be considered.
503 * @param value The new value of the variable.
505 * @see TRACE_host_variable_declare, TRACE_host_variable_add, TRACE_host_variable_sub
507 void TRACE_host_variable_set (const char *host, const char *variable, double value)
509 TRACE_host_variable_set_with_time(simgrid_get_clock(), host, variable, value);
512 /** @ingroup TRACE_user_variables
513 * @brief Add a value to a variable of a host.
515 * @param host The name of the host to be considered.
516 * @param variable The name of the variable to be considered.
517 * @param value The value to be added to the variable.
519 * @see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_sub
521 void TRACE_host_variable_add (const char *host, const char *variable, double value)
523 TRACE_host_variable_add_with_time(simgrid_get_clock(), host, variable, value);
526 /** @ingroup TRACE_user_variables
527 * @brief Subtract a value from a variable of a host.
529 * @param host The name of the host to be considered.
530 * @param variable The name of the variable to be considered.
531 * @param value The value to be subtracted from the variable.
533 * @see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_add
535 void TRACE_host_variable_sub (const char *host, const char *variable, double value)
537 TRACE_host_variable_sub_with_time(simgrid_get_clock(), host, variable, value);
540 /** @ingroup TRACE_user_variables
541 * @brief Set the value of a variable of a host at a given timestamp.
543 * Same as #TRACE_host_variable_set, but let user specify the time used to trace it. Users can specify a time that
544 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
545 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
548 * @param time The timestamp to be used to tag this change of value.
549 * @param host The name of the host to be considered.
550 * @param variable The name of the variable to be considered.
551 * @param value The new value of the variable.
553 * @see TRACE_host_variable_declare, TRACE_host_variable_add_with_time, TRACE_host_variable_sub_with_time
555 void TRACE_host_variable_set_with_time (double time, const char *host, const char *variable, double value)
557 instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SET, nullptr, &user_host_variables);
560 /** @ingroup TRACE_user_variables
561 * @brief Add a value to a variable of a host at a given timestamp.
563 * Same as #TRACE_host_variable_add, but let user specify the time used to trace it. Users can specify a time that
564 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
565 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
568 * @param time The timestamp to be used to tag this change of value.
569 * @param host The name of the host to be considered.
570 * @param variable The name of the variable to be considered.
571 * @param value The value to be added to the variable.
573 * @see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_sub_with_time
575 void TRACE_host_variable_add_with_time (double time, const char *host, const char *variable, double value)
577 instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::ADD, nullptr, &user_host_variables);
580 /** @ingroup TRACE_user_variables
581 * @brief Subtract a value from a variable of a host at a given timestamp.
583 * Same as #TRACE_host_variable_sub, but let user specify the time used to trace it. Users can specify a time that
584 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
585 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
588 * @param time The timestamp to be used to tag this change of value.
589 * @param host The name of the host to be considered.
590 * @param variable The name of the variable to be considered.
591 * @param value The value to be subtracted from the variable.
593 * @see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_add_with_time
595 void TRACE_host_variable_sub_with_time (double time, const char *host, const char *variable, double value)
597 instr_user_variable(time, host, variable, "HOST", value, InstrUserVariable::SUB, nullptr, &user_host_variables);
600 /** @ingroup TRACE_user_variables
601 * @brief Get declared user host variables
603 * This function should be used to get host variables that were already declared with #TRACE_host_variable_declare or
604 * with #TRACE_host_variable_declare_with_color.
606 * @return A dynar with the declared host variables, must be freed with xbt_dynar_free.
608 xbt_dynar_t TRACE_get_host_variables ()
610 return instr_set_to_dynar(user_host_variables);
613 /* for link variables */
614 /** @ingroup TRACE_user_variables
615 * @brief Declare a new user variable associated to links.
617 * Declare a user variable that will be associated to links.
618 * A user link variable can be used, for example, to trace user variables such as the number of messages being
619 * transferred through network links. The color associated to this new variable will be random.
621 * @param variable The name of the new variable to be declared.
623 * @see TRACE_link_variable_declare_with_color
625 void TRACE_link_variable_declare (const char *variable)
627 instr_user_variable(0, nullptr, variable, "LINK", 0, InstrUserVariable::DECLARE, nullptr, &user_link_variables);
630 /** @ingroup TRACE_user_variables
631 * @brief Declare a new user variable associated to links with a color.
633 * Same as #TRACE_link_variable_declare, but associated a color to the newly created user link variable. The color
634 * needs to be a string with three numbers separated by spaces in the range [0,1].
635 * A light-gray color can be specified using "0.7 0.7 0.7" as color.
637 * @param variable The name of the new variable to be declared.
638 * @param color The color for the new variable.
640 void TRACE_link_variable_declare_with_color (const char *variable, const char *color)
642 instr_user_variable(0, nullptr, variable, "LINK", 0, InstrUserVariable::DECLARE, color, &user_link_variables);
645 /** @ingroup TRACE_user_variables
646 * @brief Set the value of a variable of a link.
648 * @param link The name of the link to be considered.
649 * @param variable The name of the variable to be considered.
650 * @param value The new value of the variable.
652 * @see TRACE_link_variable_declare, TRACE_link_variable_add, TRACE_link_variable_sub
654 void TRACE_link_variable_set (const char *link, const char *variable, double value)
656 TRACE_link_variable_set_with_time(simgrid_get_clock(), link, variable, value);
659 /** @ingroup TRACE_user_variables
660 * @brief Add a value to a variable of a link.
662 * @param link The name of the link to be considered.
663 * @param variable The name of the variable to be considered.
664 * @param value The value to be added to the variable.
666 * @see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_sub
668 void TRACE_link_variable_add (const char *link, const char *variable, double value)
670 TRACE_link_variable_add_with_time(simgrid_get_clock(), link, variable, value);
673 /** @ingroup TRACE_user_variables
674 * @brief Subtract a value from a variable of a link.
676 * @param link The name of the link to be considered.
677 * @param variable The name of the variable to be considered.
678 * @param value The value to be subtracted from the variable.
680 * @see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_add
682 void TRACE_link_variable_sub (const char *link, const char *variable, double value)
684 TRACE_link_variable_sub_with_time(simgrid_get_clock(), link, variable, value);
687 /** @ingroup TRACE_user_variables
688 * @brief Set the value of a variable of a link at a given timestamp.
690 * Same as #TRACE_link_variable_set, but let user specify the time used to trace it. Users can specify a time that
691 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
692 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
695 * @param time The timestamp to be used to tag this change of value.
696 * @param link The name of the link to be considered.
697 * @param variable The name of the variable to be considered.
698 * @param value The new value of the variable.
700 * @see TRACE_link_variable_declare, TRACE_link_variable_add_with_time, TRACE_link_variable_sub_with_time
702 void TRACE_link_variable_set_with_time (double time, const char *link, const char *variable, double value)
704 instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SET, nullptr, &user_link_variables);
707 /** @ingroup TRACE_user_variables
708 * @brief Add a value to a variable of a link at a given timestamp.
710 * Same as #TRACE_link_variable_add, but let user specify the time used to trace it. Users can specify a time that
711 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
712 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
715 * @param time The timestamp to be used to tag this change of value.
716 * @param link The name of the link to be considered.
717 * @param variable The name of the variable to be considered.
718 * @param value The value to be added to the variable.
720 * @see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_sub_with_time
722 void TRACE_link_variable_add_with_time (double time, const char *link, const char *variable, double value)
724 instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::ADD, nullptr, &user_link_variables);
727 /** @ingroup TRACE_user_variables
728 * @brief Subtract a value from a variable of a link at a given timestamp.
730 * Same as #TRACE_link_variable_sub, but let user specify the time used to trace it. Users can specify a time that
731 * is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
732 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
735 * @param time The timestamp to be used to tag this change of value.
736 * @param link The name of the link to be considered.
737 * @param variable The name of the variable to be considered.
738 * @param value The value to be subtracted from the variable.
740 * @see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_add_with_time
742 void TRACE_link_variable_sub_with_time (double time, const char *link, const char *variable, double value)
744 instr_user_variable(time, link, variable, "LINK", value, InstrUserVariable::SUB, nullptr, &user_link_variables);
747 /* for link variables, but with src and dst used for get_route */
748 /** @ingroup TRACE_user_variables
749 * @brief Set the value of the variable present in the links connecting source and destination.
751 * Same as #TRACE_link_variable_set, but instead of providing the name of link to be considered, provide the source
752 * and destination hosts. All links that are part of the route between source and destination will have the variable
753 * set to the provided value.
755 * @param src The name of the source host for get route.
756 * @param dst The name of the destination host for get route.
757 * @param variable The name of the variable to be considered.
758 * @param value The new value of the variable.
760 * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add, TRACE_link_srcdst_variable_sub
762 void TRACE_link_srcdst_variable_set (const char *src, const char *dst, const char *variable, double value)
764 TRACE_link_srcdst_variable_set_with_time(simgrid_get_clock(), src, dst, variable, value);
767 /** @ingroup TRACE_user_variables
768 * @brief Add a value to the variable present in the links connecting source and destination.
770 * Same as #TRACE_link_variable_add, but instead of providing the name of link to be considered, provide the source
771 * and destination hosts. All links that are part of the route between source and destination will have the value
772 * passed as parameter added to the current value of the variable name to be considered.
774 * @param src The name of the source host for get route.
775 * @param dst The name of the destination host for get route.
776 * @param variable The name of the variable to be considered.
777 * @param value The value to be added to the variable.
779 * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_sub
781 void TRACE_link_srcdst_variable_add (const char *src, const char *dst, const char *variable, double value)
783 TRACE_link_srcdst_variable_add_with_time(simgrid_get_clock(), src, dst, variable, value);
786 /** @ingroup TRACE_user_variables
787 * @brief Subtract a value from the variable present in the links connecting source and destination.
789 * Same as #TRACE_link_variable_sub, 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 value
791 * passed as parameter subtracted from the current value of the variable name to be considered.
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 value to be subtracted from the variable.
798 * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_add
800 void TRACE_link_srcdst_variable_sub (const char *src, const char *dst, const char *variable, double value)
802 TRACE_link_srcdst_variable_sub_with_time(simgrid_get_clock(), src, dst, variable, value);
805 /** @ingroup TRACE_user_variables
806 * @brief Set the value of the variable present in the links connecting source and destination at a given timestamp.
808 * Same as #TRACE_link_srcdst_variable_set, but let user specify the time used to trace it. Users can specify a time
809 * that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
810 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
813 * @param time The timestamp to be used to tag this change of value.
814 * @param src The name of the source host for get route.
815 * @param dst The name of the destination host for get route.
816 * @param variable The name of the variable to be considered.
817 * @param value The new value of the variable.
819 * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add_with_time, TRACE_link_srcdst_variable_sub_with_time
821 void TRACE_link_srcdst_variable_set_with_time (double time, const char *src, const char *dst, const char *variable,
824 instr_user_srcdst_variable(time, src, dst, variable, "LINK", value, InstrUserVariable::SET);
827 /** @ingroup TRACE_user_variables
828 * @brief Add a value to the variable present in the links connecting source and destination at a given timestamp.
830 * Same as #TRACE_link_srcdst_variable_add, but let user specify the time used to trace it. Users can specify a time
831 * that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
832 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
835 * @param time The timestamp to be used to tag this change of value.
836 * @param src The name of the source host for get route.
837 * @param dst The name of the destination host for get route.
838 * @param variable The name of the variable to be considered.
839 * @param value The value to be added to the variable.
841 * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_sub_with_time
843 void TRACE_link_srcdst_variable_add_with_time (double time, const char *src, const char *dst, const char *variable,
846 instr_user_srcdst_variable(time, src, dst, variable, "LINK", value, InstrUserVariable::ADD);
849 /** @ingroup TRACE_user_variables
850 * @brief Subtract a value from the variable present in the links connecting source and dest. at a given timestamp.
852 * Same as #TRACE_link_srcdst_variable_sub, but let user specify the time used to trace it. Users can specify a time
853 * that is not the simulated clock time as defined by the core simulator. This allows a fine-grain control of time
854 * definition, but should be used with caution since the trace can be inconsistent if resource utilization traces are
857 * @param time The timestamp to be used to tag this change of value.
858 * @param src The name of the source host for get route.
859 * @param dst The name of the destination host for get route.
860 * @param variable The name of the variable to be considered.
861 * @param value The value to be subtracted from the variable.
863 * @see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_add_with_time
865 void TRACE_link_srcdst_variable_sub_with_time (double time, const char *src, const char *dst, const char *variable,
868 instr_user_srcdst_variable(time, src, dst, variable, "LINK", value, InstrUserVariable::SUB);
871 /** @ingroup TRACE_user_variables
872 * @brief Get declared user link variables
874 * This function should be used to get link variables that were already declared with #TRACE_link_variable_declare or
875 * with #TRACE_link_variable_declare_with_color.
877 * @return A dynar with the declared link variables, must be freed with xbt_dynar_free.
879 xbt_dynar_t TRACE_get_link_variables ()
881 return instr_set_to_dynar(user_link_variables);
884 /** @ingroup TRACE_user_variables
885 * @brief Declare a new user state associated to hosts.
887 * Declare a user state that will be associated to hosts.
888 * A user host state can be used to trace application states.
890 * @param state The name of the new state to be declared.
892 * @see TRACE_host_state_declare_value
894 void TRACE_host_state_declare (const char *state)
896 instr_new_user_state_type("HOST", state);
899 /** @ingroup TRACE_user_variables
900 * @brief Declare a new value for a user state associated to hosts.
902 * Declare a value for a state. The color needs to be a string with 3 numbers separated by spaces in the range [0,1].
903 * A light-gray color can be specified using "0.7 0.7 0.7" as color.
905 * @param state The name of the new state to be declared.
906 * @param value The name of the value
907 * @param color The color of the value
909 * @see TRACE_host_state_declare
911 void TRACE_host_state_declare_value (const char *state, const char *value, const char *color)
913 instr_new_value_for_user_state_type (state, value, color);
916 /** @ingroup TRACE_user_variables
917 * @brief Set the user state to the given value.
919 * Change a user state previously declared to the given value.
921 * @param host The name of the host to be considered.
922 * @param state_name The name of the state previously declared.
923 * @param value_name The new value of the state.
925 * @see TRACE_host_state_declare, TRACE_host_push_state, TRACE_host_pop_state, TRACE_host_reset_state
927 void TRACE_host_set_state(const char* host, const char* state_name, const char* value_name)
929 simgrid::instr::StateType* state = simgrid::instr::Container::by_name(host)->get_state(state_name);
930 state->add_entity_value(value_name);
931 state->set_event(value_name);
934 /** @ingroup TRACE_user_variables
935 * @brief Push a new value for a state of a given host.
937 * Change a user state previously declared by pushing the new value to the state.
939 * @param host The name of the host to be considered.
940 * @param state_name The name of the state previously declared.
941 * @param value_name The value to be pushed.
943 * @see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_pop_state, TRACE_host_reset_state
945 void TRACE_host_push_state(const char* host, const char* state_name, const char* value_name)
947 simgrid::instr::Container::by_name(host)->get_state(state_name)->push_event(value_name);
950 /** @ingroup TRACE_user_variables
951 * @brief Pop the last value of a state of a given host.
953 * Change a user state previously declared by removing the last value of the state.
955 * @param host The name of the host to be considered.
956 * @param state_name The name of the state to be popped.
958 * @see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state, TRACE_host_reset_state
960 void TRACE_host_pop_state(const char* host, const char* state_name)
962 simgrid::instr::Container::by_name(host)->get_state(state_name)->pop_event();