1 /* Copyright (c) 2010. The SimGrid Team.
2 * All rights reserved. */
4 /* This program is free software; you can redistribute it and/or modify it
5 * under the terms of the license (GNU LGPL) which comes with this package. */
7 #include "simgrid_config.h"
10 #include "instr/instr_private.h"
11 #include "surf/network_private.h"
20 XBT_LOG_NEW_DEFAULT_SUBCATEGORY (instr_api, instr, "API");
22 xbt_dict_t created_categories = NULL;
23 xbt_dict_t declared_marks = NULL;
24 xbt_dict_t user_host_variables = NULL;
25 xbt_dict_t user_link_variables = NULL;
26 extern xbt_dict_t trivaNodeTypes;
27 extern xbt_dict_t trivaEdgeTypes;
29 static xbt_dynar_t instr_dict_to_dynar (xbt_dict_t filter)
31 if (!TRACE_is_enabled()) return NULL;
32 if (!TRACE_needs_platform()) return NULL;
34 xbt_dynar_t ret = xbt_dynar_new (sizeof(char*), &xbt_free_ref);
35 xbt_dict_cursor_t cursor = NULL;
37 xbt_dict_foreach(filter, cursor, name, value) {
38 xbt_dynar_push_as (ret, char*, xbt_strdup(name));
43 /** \ingroup TRACE_category
44 * \brief Declare a new category with a random color.
46 * This function should be used to define a user category. The
47 * category can be used to differentiate the tasks that are created
48 * during the simulation (for example, tasks from server1, server2,
49 * or request tasks, computation tasks, communication tasks). All
50 * resource utilization (host power and link bandwidth) will be
51 * classified according to the task category. Tasks that do not
52 * belong to a category are not traced. The color for the category
53 * that is being declared is random. This function has no effect
54 * if a category with the same name has been already declared.
56 * See \ref tracing_tracing for details on how to trace
57 * the (categorized) resource utilization.
59 * \param category The name of the new tracing category to be created.
61 * \see TRACE_category_with_color, MSG_task_set_category, SD_task_set_category
63 void TRACE_category(const char *category)
65 TRACE_category_with_color (category, NULL);
68 /** \ingroup TRACE_category
69 * \brief Declare a new category with a color.
71 * Same as #TRACE_category, but let user specify a color encoded as a
72 * RGB-like string with three floats from 0 to 1. So, to specify a
73 * red color, pass "1 0 0" as color parameter. A light-gray color
74 * can be specified using "0.7 0.7 0.7" as color. This function has
75 * no effect if a category with the same name has been already declared.
77 * See \ref tracing_tracing for details on how to trace
78 * the (categorized) resource utilization.
80 * \param category The name of the new tracing category to be created.
81 * \param color The color of the category (see \ref tracing_tracing to
82 * know how to correctly specify the color)
84 * \see MSG_task_set_category, SD_task_set_category
86 void TRACE_category_with_color (const char *category, const char *color)
89 if (!TRACE_is_enabled()) return;
91 if (!(TRACE_categorized() && category != NULL)) return;
93 /* if platform is not traced, we can't deal with categories */
94 if (!TRACE_needs_platform()) return;
96 //check if category is already created
97 char *created = xbt_dict_get_or_null(created_categories, category);
99 xbt_dict_set (created_categories, category, xbt_strdup("1"), NULL);
102 char final_color[INSTR_DEFAULT_STR_SIZE];
104 //generate a random color
105 double red = drand48();
106 double green = drand48();
107 double blue = drand48();
108 snprintf (final_color, INSTR_DEFAULT_STR_SIZE, "%f %f %f", red, green, blue);
110 snprintf (final_color, INSTR_DEFAULT_STR_SIZE, "%s", color);
113 XBT_DEBUG("CAT,declare %s, %s", category, final_color);
115 //define the type of this category on top of hosts and links
116 instr_new_variable_type (category, final_color);
120 /** \ingroup TRACE_category
121 * \brief Get declared categories
123 * This function should be used to get categories that were already
124 * declared with #TRACE_category or with #TRACE_category_with_color.
126 * See \ref tracing_tracing for details on how to trace
127 * the (categorized) resource utilization.
129 * \return A dynar with the declared categories, must be freed with xbt_dynar_free.
131 * \see MSG_task_set_category, SD_task_set_category
133 xbt_dynar_t TRACE_get_categories (void)
135 if (!TRACE_is_enabled()) return NULL;
136 if (!TRACE_categorized()) return NULL;
138 return instr_dict_to_dynar (created_categories);
141 /** \ingroup TRACE_mark
142 * \brief Declare a new type for tracing mark.
144 * This function declares a new Paje event
145 * type in the trace file that can be used by
146 * simulators to declare application-level
147 * marks. This function is independent of
148 * which API is used in SimGrid.
150 * \param mark_type The name of the new type.
154 void TRACE_declare_mark(const char *mark_type)
157 if (!TRACE_is_enabled()) return;
159 /* if platform is not traced, we don't allow marks */
160 if (!TRACE_needs_platform()) return;
162 if (!mark_type) return;
164 //check if mark_type is already declared
165 char *created = xbt_dict_get_or_null(declared_marks, mark_type);
167 xbt_dict_set (declared_marks, mark_type, xbt_strdup("1"), NULL);
169 XBT_DEBUG("MARK,declare %s", mark_type);
170 PJ_type_event_new(mark_type, NULL, PJ_type_get_root());
174 * \ingroup TRACE_mark
175 * \brief Create a new instance of a tracing mark type.
177 * This function creates a mark in the trace file. The
178 * first parameter had to be previously declared using
179 * #TRACE_declare_mark, the second is the identifier
180 * for this mark instance. We recommend that the
181 * mark_value is a unique value for the whole simulation.
182 * Nevertheless, this is not a strong requirement: the
183 * trace will be valid even if there are multiple mark
184 * identifiers for the same trace.
186 * \param mark_type The name of the type for which the new instance will belong.
187 * \param mark_value The name of the new instance mark.
189 * \see TRACE_declare_mark
191 void TRACE_mark(const char *mark_type, const char *mark_value)
194 if (!TRACE_is_enabled()) return;
196 /* if platform is not traced, we don't allow marks */
197 if (!TRACE_needs_platform()) return;
199 if (!mark_type || !mark_value) return;
201 //check if mark_type is already declared
202 char *created = xbt_dict_get_or_null(declared_marks, mark_type);
205 XBT_DEBUG("MARK %s %s", mark_type, mark_value);
206 type_t type = PJ_type_get (mark_type, PJ_type_get_root());
208 THROWF (tracing_error, 1, "mark_type with name (%s) not declared before", mark_type);
210 val_t value = PJ_value_get_or_new (mark_value, NULL, type);
211 new_pajeNewEvent (MSG_get_clock(), PJ_container_get_root(), type, value);
214 /** \ingroup TRACE_mark
215 * \brief Get declared marks
217 * This function should be used to get marks that were already
218 * declared with #TRACE_declare_mark.
220 * \return A dynar with the declared marks, must be freed with xbt_dynar_free.
223 xbt_dynar_t TRACE_get_marks (void)
225 if (!TRACE_is_enabled()) return NULL;
227 return instr_dict_to_dynar (declared_marks);
230 static void instr_user_variable(double time,
231 const char *resource,
232 const char *variable,
233 const char *father_type,
235 InstrUserVariable what,
240 if (!TRACE_is_enabled()) return;
242 /* if platform is not traced, we don't allow user variables */
243 if (!TRACE_needs_platform()) return;
245 //check if variable is already declared
246 char *created = xbt_dict_get_or_null(filter, variable);
247 if (what == INSTR_US_DECLARE){
252 xbt_dict_set (filter, variable, xbt_strdup("1"), NULL);
256 //not declared, ignore
262 snprintf(valuestr, 100, "%g", value);
265 case INSTR_US_DECLARE:
266 instr_new_user_variable_type (father_type, variable, color);
270 container_t container = PJ_container_get(resource);
271 type_t type = PJ_type_get (variable, container->type);
272 new_pajeSetVariable(time, container, type, value);
277 container_t container = PJ_container_get(resource);
278 type_t type = PJ_type_get (variable, container->type);
279 new_pajeAddVariable(time, container, type, value);
284 container_t container = PJ_container_get(resource);
285 type_t type = PJ_type_get (variable, container->type);
286 new_pajeSubVariable(time, container, type, value);
290 //TODO: launch exception
295 static void instr_user_srcdst_variable(double time,
298 const char *variable,
299 const char *father_type,
301 InstrUserVariable what)
303 xbt_dynar_t route=NULL;
304 sg_routing_edge_t src_elm = sg_routing_edge_by_name_or_null(src);
305 if(!src_elm) xbt_die("Element '%s' not found!",src);
307 sg_routing_edge_t dst_elm = sg_routing_edge_by_name_or_null(dst);
308 if(!dst_elm) xbt_die("Element '%s' not found!",dst);
310 routing_get_route_and_latency (src_elm, dst_elm, &route,NULL);
313 xbt_dynar_foreach (route, i, link) {
314 char *link_name = ((link_CM02_t)link)->lmm_resource.generic_resource.name;
315 instr_user_variable (time, link_name, variable, father_type, value, what, NULL, user_link_variables);
319 /** \ingroup TRACE_API
320 * \brief Creates a file with the topology of the platform file used for the simulator.
322 * The graph topology will have the following properties: all hosts, links and routers
323 * of the platform file are mapped to graph nodes; routes are mapped to edges.
324 * The platform's AS are not represented in the output.
326 * \param filename The name of the file that will hold the graph.
328 * \return 1 of successful, 0 otherwise.
330 int TRACE_platform_graph_export_graphviz (const char *filename)
332 /* returns 1 if successful, 0 otherwise */
333 if (!TRACE_is_enabled()) return 0;
334 xbt_graph_t g = instr_routing_platform_graph();
335 if (g == NULL) return 0;
336 instr_routing_platform_graph_export_graphviz (g, filename);
337 xbt_graph_free_graph (g, xbt_free, xbt_free, NULL);
342 * Derived functions that use instr_user_variable and TRACE_user_srcdst_variable.
343 * They were previously defined as pre-processors directives, but were transformed
344 * into functions so the user can track them using gdb.
347 /* for host variables */
348 /** \ingroup TRACE_user_variables
349 * \brief Declare a new user variable associated to hosts.
351 * Declare a user variable that will be associated to hosts.
352 * A user host variable can be used to trace user variables
353 * such as the number of tasks in a server, the number of
354 * clients in an application (for hosts), and so on. The color
355 * associated to this new variable will be random.
357 * \param variable The name of the new variable to be declared.
359 * \see TRACE_host_variable_declare_with_color
361 void TRACE_host_variable_declare (const char *variable)
363 instr_user_variable(0, NULL, variable, "HOST", 0, INSTR_US_DECLARE, NULL, user_host_variables);
366 /** \ingroup TRACE_user_variables
367 * \brief Declare a new user variable associated to hosts with a color.
369 * Same as #TRACE_host_variable_declare, but associated a color
370 * to the newly created user host variable. The color needs to be
371 * a string with three numbers separated by spaces in the range [0,1].
372 * A light-gray color can be specified using "0.7 0.7 0.7" as color.
374 * \param variable The name of the new variable to be declared.
375 * \param color The color for the new variable.
378 void TRACE_host_variable_declare_with_color (const char *variable, const char *color)
380 instr_user_variable(0, NULL, variable, "HOST", 0, INSTR_US_DECLARE, color, user_host_variables);
383 /** \ingroup TRACE_user_variables
384 * \brief Set the value of a variable of a host.
386 * \param host The name of the host to be considered.
387 * \param variable The name of the variable to be considered.
388 * \param value The new value of the variable.
390 * \see TRACE_host_variable_declare, TRACE_host_variable_add, TRACE_host_variable_sub
392 void TRACE_host_variable_set (const char *host, const char *variable, double value)
394 TRACE_host_variable_set_with_time (MSG_get_clock(), host, variable, value);
397 /** \ingroup TRACE_user_variables
398 * \brief Add a value to a variable of a host.
400 * \param host The name of the host to be considered.
401 * \param variable The name of the variable to be considered.
402 * \param value The value to be added to the variable.
404 * \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_sub
406 void TRACE_host_variable_add (const char *host, const char *variable, double value)
408 TRACE_host_variable_add_with_time (MSG_get_clock(), host, variable, value);
411 /** \ingroup TRACE_user_variables
412 * \brief Subtract a value from a variable of a host.
414 * \param host The name of the host to be considered.
415 * \param variable The name of the variable to be considered.
416 * \param value The value to be subtracted from the variable.
418 * \see TRACE_host_variable_declare, TRACE_host_variable_set, TRACE_host_variable_add
420 void TRACE_host_variable_sub (const char *host, const char *variable, double value)
422 TRACE_host_variable_sub_with_time (MSG_get_clock(), host, variable, value);
425 /** \ingroup TRACE_user_variables
426 * \brief Set the value of a variable of a host at a given timestamp.
428 * Same as #TRACE_host_variable_set, but let user specify
429 * the time used to trace it. Users can specify a time that
430 * is not the simulated clock time as defined by the core
431 * simulator. This allows a fine-grain control of time
432 * definition, but should be used with caution since the trace
433 * can be inconsistent if resource utilization traces are also traced.
435 * \param time The timestamp to be used to tag this change of value.
436 * \param host The name of the host to be considered.
437 * \param variable The name of the variable to be considered.
438 * \param value The new value of the variable.
440 * \see TRACE_host_variable_declare, TRACE_host_variable_add_with_time, TRACE_host_variable_sub_with_time
442 void TRACE_host_variable_set_with_time (double time, const char *host, const char *variable, double value)
444 instr_user_variable(time, host, variable, "HOST", value, INSTR_US_SET, NULL, user_host_variables);
447 /** \ingroup TRACE_user_variables
448 * \brief Add a value to a variable of a host at a given timestamp.
450 * Same as #TRACE_host_variable_add, but let user specify
451 * the time used to trace it. Users can specify a time that
452 * is not the simulated clock time as defined by the core
453 * simulator. This allows a fine-grain control of time
454 * definition, but should be used with caution since the trace
455 * can be inconsistent if resource utilization traces are also traced.
457 * \param time The timestamp to be used to tag this change of value.
458 * \param host The name of the host to be considered.
459 * \param variable The name of the variable to be considered.
460 * \param value The value to be added to the variable.
462 * \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_sub_with_time
464 void TRACE_host_variable_add_with_time (double time, const char *host, const char *variable, double value)
466 instr_user_variable(time, host, variable, "HOST", value, INSTR_US_ADD, NULL, user_host_variables);
469 /** \ingroup TRACE_user_variables
470 * \brief Subtract a value from a variable of a host at a given timestamp.
472 * Same as #TRACE_host_variable_sub, but let user specify
473 * the time used to trace it. Users can specify a time that
474 * is not the simulated clock time as defined by the core
475 * simulator. This allows a fine-grain control of time
476 * definition, but should be used with caution since the trace
477 * can be inconsistent if resource utilization traces are also traced.
479 * \param time The timestamp to be used to tag this change of value.
480 * \param host The name of the host to be considered.
481 * \param variable The name of the variable to be considered.
482 * \param value The value to be subtracted from the variable.
484 * \see TRACE_host_variable_declare, TRACE_host_variable_set_with_time, TRACE_host_variable_add_with_time
486 void TRACE_host_variable_sub_with_time (double time, const char *host, const char *variable, double value)
488 instr_user_variable(time, host, variable, "HOST", value, INSTR_US_SUB, NULL, user_host_variables);
491 /** \ingroup TRACE_user_variables
492 * \brief Get declared user host variables
494 * This function should be used to get host variables that were already
495 * declared with #TRACE_host_variable_declare or with #TRACE_host_variable_declare_with_color.
497 * \return A dynar with the declared host variables, must be freed with xbt_dynar_free.
499 xbt_dynar_t TRACE_get_host_variables (void)
501 return instr_dict_to_dynar (user_host_variables);
504 /* for link variables */
505 /** \ingroup TRACE_user_variables
506 * \brief Declare a new user variable associated to links.
508 * Declare a user variable that will be associated to links.
509 * A user link variable can be used, for example, to trace
510 * user variables such as the number of messages being
511 * transferred through network links. The color
512 * associated to this new variable will be random.
514 * \param variable The name of the new variable to be declared.
516 * \see TRACE_link_variable_declare_with_color
518 void TRACE_link_variable_declare (const char *variable)
520 instr_user_variable (0, NULL, variable, "LINK", 0, INSTR_US_DECLARE, NULL, user_link_variables);
523 /** \ingroup TRACE_user_variables
524 * \brief Declare a new user variable associated to links with a color.
526 * Same as #TRACE_link_variable_declare, but associated a color
527 * to the newly created user link variable. The color needs to be
528 * a string with three numbers separated by spaces in the range [0,1].
529 * A light-gray color can be specified using "0.7 0.7 0.7" as color.
531 * \param variable The name of the new variable to be declared.
532 * \param color The color for the new variable.
535 void TRACE_link_variable_declare_with_color (const char *variable, const char *color)
537 instr_user_variable (0, NULL, variable, "LINK", 0, INSTR_US_DECLARE, color, user_link_variables);
540 /** \ingroup TRACE_user_variables
541 * \brief Set the value of a variable of a link.
543 * \param link The name of the link to be considered.
544 * \param variable The name of the variable to be considered.
545 * \param value The new value of the variable.
547 * \see TRACE_link_variable_declare, TRACE_link_variable_add, TRACE_link_variable_sub
549 void TRACE_link_variable_set (const char *link, const char *variable, double value)
551 TRACE_link_variable_set_with_time (MSG_get_clock(), link, variable, value);
554 /** \ingroup TRACE_user_variables
555 * \brief Add a value to a variable of a link.
557 * \param link The name of the link to be considered.
558 * \param variable The name of the variable to be considered.
559 * \param value The value to be added to the variable.
561 * \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_sub
563 void TRACE_link_variable_add (const char *link, const char *variable, double value)
565 TRACE_link_variable_add_with_time (MSG_get_clock(), link, variable, value);
568 /** \ingroup TRACE_user_variables
569 * \brief Subtract a value from a variable of a link.
571 * \param link The name of the link to be considered.
572 * \param variable The name of the variable to be considered.
573 * \param value The value to be subtracted from the variable.
575 * \see TRACE_link_variable_declare, TRACE_link_variable_set, TRACE_link_variable_add
577 void TRACE_link_variable_sub (const char *link, const char *variable, double value)
579 TRACE_link_variable_sub_with_time (MSG_get_clock(), link, variable, value);
582 /** \ingroup TRACE_user_variables
583 * \brief Set the value of a variable of a link at a given timestamp.
585 * Same as #TRACE_link_variable_set, but let user specify
586 * the time used to trace it. Users can specify a time that
587 * is not the simulated clock time as defined by the core
588 * simulator. This allows a fine-grain control of time
589 * definition, but should be used with caution since the trace
590 * can be inconsistent if resource utilization traces are also traced.
592 * \param time The timestamp to be used to tag this change of value.
593 * \param link The name of the link to be considered.
594 * \param variable The name of the variable to be considered.
595 * \param value The new value of the variable.
597 * \see TRACE_link_variable_declare, TRACE_link_variable_add_with_time, TRACE_link_variable_sub_with_time
599 void TRACE_link_variable_set_with_time (double time, const char *link, const char *variable, double value)
601 instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SET, NULL, user_link_variables);
604 /** \ingroup TRACE_user_variables
605 * \brief Add a value to a variable of a link at a given timestamp.
607 * Same as #TRACE_link_variable_add, but let user specify
608 * the time used to trace it. Users can specify a time that
609 * is not the simulated clock time as defined by the core
610 * simulator. This allows a fine-grain control of time
611 * definition, but should be used with caution since the trace
612 * can be inconsistent if resource utilization traces are also traced.
614 * \param time The timestamp to be used to tag this change of value.
615 * \param link The name of the link to be considered.
616 * \param variable The name of the variable to be considered.
617 * \param value The value to be added to the variable.
619 * \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_sub_with_time
621 void TRACE_link_variable_add_with_time (double time, const char *link, const char *variable, double value)
623 instr_user_variable (time, link, variable, "LINK", value, INSTR_US_ADD, NULL, user_link_variables);
626 /** \ingroup TRACE_user_variables
627 * \brief Subtract a value from a variable of a link at a given timestamp.
629 * Same as #TRACE_link_variable_sub, but let user specify
630 * the time used to trace it. Users can specify a time that
631 * is not the simulated clock time as defined by the core
632 * simulator. This allows a fine-grain control of time
633 * definition, but should be used with caution since the trace
634 * can be inconsistent if resource utilization traces are also traced.
636 * \param time The timestamp to be used to tag this change of value.
637 * \param link The name of the link to be considered.
638 * \param variable The name of the variable to be considered.
639 * \param value The value to be subtracted from the variable.
641 * \see TRACE_link_variable_declare, TRACE_link_variable_set_with_time, TRACE_link_variable_add_with_time
643 void TRACE_link_variable_sub_with_time (double time, const char *link, const char *variable, double value)
645 instr_user_variable (time, link, variable, "LINK", value, INSTR_US_SUB, NULL, user_link_variables);
648 /* for link variables, but with src and dst used for get_route */
649 /** \ingroup TRACE_user_variables
650 * \brief Set the value of the variable present in the links connecting source and destination.
652 * Same as #TRACE_link_variable_set, but instead of providing the
653 * name of link to be considered, provide the source and destination
654 * hosts. All links that are part of the route between source and
655 * destination will have the variable set to the provided value.
657 * \param src The name of the source host for get route.
658 * \param dst The name of the destination host for get route.
659 * \param variable The name of the variable to be considered.
660 * \param value The new value of the variable.
662 * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add, TRACE_link_srcdst_variable_sub
664 void TRACE_link_srcdst_variable_set (const char *src, const char *dst, const char *variable, double value)
666 TRACE_link_srcdst_variable_set_with_time (MSG_get_clock(), src, dst, variable, value);
669 /** \ingroup TRACE_user_variables
670 * \brief Add a value to the variable present in the links connecting source and destination.
672 * Same as #TRACE_link_variable_add, but instead of providing the
673 * name of link to be considered, provide the source and destination
674 * hosts. All links that are part of the route between source and
675 * destination will have the value passed as parameter added to
676 * the current value of the variable name to be considered.
678 * \param src The name of the source host for get route.
679 * \param dst The name of the destination host for get route.
680 * \param variable The name of the variable to be considered.
681 * \param value The value to be added to the variable.
683 * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_sub
685 void TRACE_link_srcdst_variable_add (const char *src, const char *dst, const char *variable, double value)
687 TRACE_link_srcdst_variable_add_with_time (MSG_get_clock(), src, dst, variable, value);
690 /** \ingroup TRACE_user_variables
691 * \brief Subtract a value from the variable present in the links connecting source and destination.
693 * Same as #TRACE_link_variable_sub, but instead of providing the
694 * name of link to be considered, provide the source and destination
695 * hosts. All links that are part of the route between source and
696 * destination will have the value passed as parameter subtracted from
697 * the current value of the variable name to be considered.
699 * \param src The name of the source host for get route.
700 * \param dst The name of the destination host for get route.
701 * \param variable The name of the variable to be considered.
702 * \param value The value to be subtracted from the variable.
704 * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set, TRACE_link_srcdst_variable_add
706 void TRACE_link_srcdst_variable_sub (const char *src, const char *dst, const char *variable, double value)
708 TRACE_link_srcdst_variable_sub_with_time (MSG_get_clock(), src, dst, variable, value);
711 /** \ingroup TRACE_user_variables
712 * \brief Set the value of the variable present in the links connecting source and destination at a given timestamp.
714 * Same as #TRACE_link_srcdst_variable_set, but let user specify
715 * the time used to trace it. Users can specify a time that
716 * is not the simulated clock time as defined by the core
717 * simulator. This allows a fine-grain control of time
718 * definition, but should be used with caution since the trace
719 * can be inconsistent if resource utilization traces are also traced.
721 * \param time The timestamp to be used to tag this change of value.
722 * \param src The name of the source host for get route.
723 * \param dst The name of the destination host for get route.
724 * \param variable The name of the variable to be considered.
725 * \param value The new value of the variable.
727 * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_add_with_time, TRACE_link_srcdst_variable_sub_with_time
729 void TRACE_link_srcdst_variable_set_with_time (double time, const char *src, const char *dst, const char *variable, double value)
731 instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SET);
734 /** \ingroup TRACE_user_variables
735 * \brief Add a value to the variable present in the links connecting source and destination at a given timestamp.
737 * Same as #TRACE_link_srcdst_variable_add, but let user specify
738 * the time used to trace it. Users can specify a time that
739 * is not the simulated clock time as defined by the core
740 * simulator. This allows a fine-grain control of time
741 * definition, but should be used with caution since the trace
742 * can be inconsistent if resource utilization traces are also traced.
744 * \param time The timestamp to be used to tag this change of value.
745 * \param src The name of the source host for get route.
746 * \param dst The name of the destination host for get route.
747 * \param variable The name of the variable to be considered.
748 * \param value The value to be added to the variable.
750 * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_sub_with_time
752 void TRACE_link_srcdst_variable_add_with_time (double time, const char *src, const char *dst, const char *variable, double value)
754 instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_ADD);
757 /** \ingroup TRACE_user_variables
758 * \brief Subtract a value from the variable present in the links connecting source and destination at a given timestamp.
760 * Same as #TRACE_link_srcdst_variable_sub, but let user specify
761 * the time used to trace it. Users can specify a time that
762 * is not the simulated clock time as defined by the core
763 * simulator. This allows a fine-grain control of time
764 * definition, but should be used with caution since the trace
765 * can be inconsistent if resource utilization traces are also traced.
767 * \param time The timestamp to be used to tag this change of value.
768 * \param src The name of the source host for get route.
769 * \param dst The name of the destination host for get route.
770 * \param variable The name of the variable to be considered.
771 * \param value The value to be subtracted from the variable.
773 * \see TRACE_link_variable_declare, TRACE_link_srcdst_variable_set_with_time, TRACE_link_srcdst_variable_add_with_time
775 void TRACE_link_srcdst_variable_sub_with_time (double time, const char *src, const char *dst, const char *variable, double value)
777 instr_user_srcdst_variable (time, src, dst, variable, "LINK", value, INSTR_US_SUB);
780 /** \ingroup TRACE_user_variables
781 * \brief Get declared user link variables
783 * This function should be used to get link variables that were already
784 * declared with #TRACE_link_variable_declare or with #TRACE_link_variable_declare_with_color.
786 * \return A dynar with the declared link variables, must be freed with xbt_dynar_free.
788 xbt_dynar_t TRACE_get_link_variables (void)
790 return instr_dict_to_dynar (user_link_variables);
793 /** \ingroup TRACE_user_variables
794 * \brief Declare a new user state associated to hosts.
796 * Declare a user state that will be associated to hosts.
797 * A user host state can be used to trace application states.
799 * \param state The name of the new state to be declared.
801 * \see TRACE_host_state_declare_value
803 void TRACE_host_state_declare (const char *state)
805 instr_new_user_state_type("HOST", state);
808 /** \ingroup TRACE_user_variables
809 * \brief Declare a new value for a user state associated to hosts.
811 * Declare a value for a state. The color needs to be
812 * a string with three numbers separated by spaces in the range [0,1].
813 * A light-gray color can be specified using "0.7 0.7 0.7" as color.
815 * \param state The name of the new state to be declared.
816 * \param value The name of the value
817 * \param color The color of the value
819 * \see TRACE_host_state_declare
821 void TRACE_host_state_declare_value (const char *state, const char *value, const char *color)
823 instr_new_value_for_user_state_type (state, value, color);
826 /** \ingroup TRACE_user_variables
827 * \brief Set the user state to the given value.
829 * Change a user state previously declared to the given value.
831 * \param host The name of the host to be considered.
832 * \param state The name of the state previously declared.
833 * \param value The new value of the state.
835 * \see TRACE_host_state_declare, TRACE_host_push_state, TRACE_host_pop_state, TRACE_host_reset_state
837 void TRACE_host_set_state (const char *host, const char *state, const char *value)
839 container_t container = PJ_container_get(host);
840 type_t type = PJ_type_get (state, container->type);
841 val_t val = PJ_value_get_or_new (value, NULL, type); /* if user didn't declare a value with a color, user a NULL color */
842 new_pajeSetState(MSG_get_clock(), container, type, val);
845 /** \ingroup TRACE_user_variables
846 * \brief Push a new value for a state of a given host.
848 * Change a user state previously declared by pushing the new value to the state.
850 * \param host The name of the host to be considered.
851 * \param state The name of the state previously declared.
852 * \param value The value to be pushed.
854 * \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_pop_state, TRACE_host_reset_state
856 void TRACE_host_push_state (const char *host, const char *state, const char *value)
858 container_t container = PJ_container_get(host);
859 type_t type = PJ_type_get (state, container->type);
860 val_t val = PJ_value_get_or_new (value, NULL, type); /* if user didn't declare a value with a color, user a NULL color */
861 new_pajePushState(MSG_get_clock(), container, type, val);
864 /** \ingroup TRACE_user_variables
865 * \brief Pop the last value of a state of a given host.
867 * Change a user state previously declared by removing the last value of the state.
869 * \param host The name of the host to be considered.
870 * \param state The name of the state to be popped.
872 * \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state, TRACE_host_reset_state
874 void TRACE_host_pop_state (const char *host, const char *state)
876 container_t container = PJ_container_get(host);
877 type_t type = PJ_type_get (state, container->type);
878 new_pajePopState(MSG_get_clock(), container, type);
881 /** \ingroup TRACE_user_variables
882 * \brief Reset the state of a given host.
884 * Clear all previous values of a user state.
886 * \param host The name of the host to be considered.
887 * \param state The name of the state to be cleared.
889 * \see TRACE_host_state_declare, TRACE_host_set_state, TRACE_host_push_state, TRACE_host_pop_state
891 void TRACE_host_reset_state (const char *host, const char *state)
893 container_t container = PJ_container_get(host);
894 type_t type = PJ_type_get (state, container->type);
895 new_pajeResetState(MSG_get_clock(), container, type);
898 /** \ingroup TRACE_API
899 * \brief Get Paje container types that can be mapped to the nodes of a graph.
901 * This function can be used to create a user made
902 * graph configuration file for Triva. Normally, it is
903 * used with the functions defined in \ref TRACE_user_variables.
905 * \return A dynar with the types, must be freed with xbt_dynar_free.
907 xbt_dynar_t TRACE_get_node_types (void)
909 return instr_dict_to_dynar (trivaNodeTypes);
912 /** \ingroup TRACE_API
913 * \brief Get Paje container types that can be mapped to the edges of a graph.
915 * This function can be used to create a user made
916 * graph configuration file for Triva. Normally, it is
917 * used with the functions defined in \ref TRACE_user_variables.
919 * \return A dynar with the types, must be freed with xbt_dynar_free.
921 xbt_dynar_t TRACE_get_edge_types (void)
923 return instr_dict_to_dynar (trivaEdgeTypes);
926 #endif /* HAVE_TRACING */