ltt/branches/poly/lttv/attribute.h

   1 #ifndef ATTRIBUTE_H
   2 #define ATTRIBUTE_H
   3
   4
   5 #include <glib.h>
   6 #include <time.h>
   7
   8 /* Attributes are used to store any value identified by a key. They are
   9    typically used to store state information or accumulated statistics for
  10    some object. Each value is accessed through a multi-component key, which
  11    resembles hierarchical pathnames in filesystems.
  12
  13    The attributes may store integers, doubles or time values, in which case
  14    the values are created upon first access of a key and with a default
  15    value of 0. Pointer values are also available with a default value of NULL
  16    and must thus be set explicitely to user managed (statically or dynamically
  17    allocated) memory.  */
  18
  19
  20 typedef guint32 lttv_string_id;
  21
  22 typedef GArray _lttv_key;
  23
  24 typedef _lttv_key lttv_key;
  25
  26 typedef struct timespec lttv_time;
  27
  28
  29 typedef struct _lttv_attributes {
  30   GHashTable *ints;
  31   GHashTable *times;
  32   GHashTable *doubles;
  33   GHashTable *pointers;
  34 } lttv_attributes;
  35
  36
  37 /* A unique integer identifier represents each different string
  38    used as a key component. A single copy of each different string is
  39    stored but its usage count is incremented each time the corresponding id
  40    is returned by lttv_string_id_from_string. The usage count is decremented
  41    each time an id is released. */
  42
  43 lttv_string_id lttv_string_id_from_string(const char *s);
  44
  45 void lttv_string_id_release(lttv_string_id i);
  46
  47 const char *lttv_string_id_to_string(lttv_string_id i);
  48
  49
  50 /* Keys are created and subsequently filled with key components */
  51
  52 lttv_key *lttv_key_new();
  53
  54 void lttv_key_destroy(lttv_key *k);
  55
  56 /* macro to access/replace a the i th component of key k */
  57
  58 #define lttv_key_index(k,i) _lttv_key_index(k,i)
  59
  60
  61 /* Append a new component */
  62
  63 void lttv_key_append(lttv_key *k, lttv_string_id i);
  64
  65
  66 /* Number of components in a key */
  67
  68 unsigned int lttv_key_number(lttv_key *k);
  69
  70
  71 /* It is also possible to create a key directly from a pathname,
  72    key components separated by /, (e.g., "/hooks/options/before"). */
  73
  74 lttv_key *lttv_key_new_pathname(const char *pathname);
  75
  76
  77 /* Create a new set of attributes */
  78
  79 lttv_attributes *lttv_attributes_new();
  80
  81
  82 /* Destroy the set of attributes including all the memory allocated
  83    internally for it (copies of keys, and integer, double and time
  84    values...). */
  85
  86 void lttv_attributes_destroy(lttv_attributes *a);
  87
  88
  89 /* Total number of attributes in a lttv_attributes. */
  90
  91 unsigned int lttv_attributes_number(lttv_attributes *a);
  92
  93
  94 /* Obtain a pointer to the value of the corresponding type associated with
  95    the specified key. New values are created on demand with 0 as initial
  96    value. These values are freed when the attributes set is destroyed. */
  97
  98 int *lttv_attributes_get_integer(lttv_attributes *a, lttv_key *k);
  99
 100 lttv_time *lttv_attributes_get_time(lttv_attributes *a, lttv_key *k);
 101
 102 double *lttv_attributes_get_double(lttv_attributes *a, lttv_key *k);
 103
 104
 105 /* Set or get the pointer value associated with the specified key.
 106    NULL is returned if no pointer was set for the key. */
 107
 108 void *lttv_attributes_get_pointer(lttv_attributes *a, lttv_key *k);
 109
 110 void lttv_attributes_set_pointer(lttv_attributes *a, lttv_key *k, void *p);
 111
 112 void *lttv_attributes_get_pointer_pathname(lttv_attributes *a, char *pn);
 113
 114 void lttv_attributes_set_pointer_pathname(lttv_attributes *a,char *pn,void *p);
 115
 116
 117 typedef int (*lttv_key_select)(lttv_key *in, lttv_key *out, void *user_data);
 118
 119 typedef enum _lttv_key_select_action
 120 { LTTV_KEEP, LTTV_KEEP_EQUAL, LTTV_KEEP_SMALLER, LTTV_KEEP_GREATER, LTTV_IGNORE
 121 } lttv_key_select_action;
 122
 123 typedef struct _lttv_key_select_spec_data
 124 {
 125   unsigned length;
 126   lttv_key_select_action *spec;
 127   lttv_key *match;
 128 } lttv_key_select_spec_data;
 129
 130 int lttv_key_select_spec(lttv_key *in, lttv_key *out, void *user_data);
 131
 132 lttv_attributes *lttv_attributes_select(lttv_attributes *a, lttv_key_select f,
 133     void *user_data);
 134
 135
 136 /* Sometimes the attributes must be accessed in bulk, sorted in different
 137    ways. For this purpose they may be converted to arrays and sorted
 138    multiple times. The keys used in the array belong to the lttv_attributes
 139    object from which the array was obtained and are freed when it is
 140    destroyed. Each element in the array is an lttv_attribute, a structure
 141    containing the key, the value type, and a union containing a value of
 142    that type. Multiple attributes with equal keys may be possible in some
 143    implementations if their type differs. */
 144
 145
 146 typedef enum _lttv_attribute_type
 147 { LTTV_INTEGER, LTTV_TIME, LTTV_DOUBLE, LTTV_POINTER }
 148 lttv_attribute_type;
 149
 150 typedef union _lttv_value_any
 151 { int i;
 152   lttv_time t;
 153   double d;
 154   void *p;
 155 } lttv_value_any;
 156
 157 typedef struct _lttv_attribute {
 158   lttv_key *key;
 159   lttv_attribute_type t;
 160   lttv_value_any v;
 161 } lttv_attribute;
 162
 163
 164 /* User defined function used to compare keys in the sort. It returns
 165    a negative value if a < b, 0 if a = b, and a positive if a > b. */
 166
 167 typedef int (*lttv_key_compare)(lttv_key *a, lttv_key *b, void *user_data);
 168
 169 int lttv_key_compare_priority(lttv_key *a, lttv_key *b, void *compare_data);
 170
 171
 172 /* Obtain all the attributes in an array */
 173
 174 lttv_attribute *lttv_attributes_array_get(lttv_attributes *a);
 175
 176 lttv_attribute *lttv_attribute_array_destroy(lttv_attribute *a);
 177
 178 void lttv_attribute_array_sort(lttv_attribute *a, unsigned size,
 179     lttv_key_compare f, void *user_data);
 180
 181 #endif // ATTRIBUTE_H