Logo AND Algorithmique Numérique Distribuée

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