1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
/** @addtogroup maps Maps (Associative Arrays)
Maps are implemented as hash lists. In order to efficiently handle maps with up to five keys of any combination
of int64s and strings, the functions to create maps, set keys, and set and get values
are all generated as needed. To do this, you must simply do some defines and
include the proper files. For example, if you need a map with 3 keys, int64, int64, and string
that stores strings, you need to do
@code
#define KEY1_TYPE INT64
#define KEY2_TYPE INT64
#define KEY3_TYPE STRING
#include "map-keys.c"
#include "map.c"
@endcode
In the above example, maps are created with _stp_map_new_int64_int64_str(). All the
generated functions start with a base name (such as _stp_map_new) and add the key types separated
by underscores.
Each map can hold only one type of data; int64, string, or statistics. Each element belonging to a map can have up to
5 keys and a value. Implemented key types are strings and int64.
To simplify the implementation, the functions to set the key and the functions to set the data are separated.
The map remembers what the current key is.
For example, to continue our previous example,
@code
/* create a map with a max of 100 elements containing strings */
MAP mymap = _stp_map_new_int64_int64_str(100, STRING);
/* mymap[100, 300, "Ohio"] = "Columbus" */
_stp_map_key_int64_int64_str (mymap, 100, 300, "Ohio");
_stp_map_set_str (mymap, "Columbus");
@endcode
All elements have a default value of 0 (or NULL). Elements are only saved to the map when their value is set
to something nonzero.
For good examples, see the runtime/tests/maps directory or the example probes.
*/
/** @addtogroup maps
*
* @{
*/
#include "map.h"
/** @defgroup map_create Creating Maps
* This documents the _stp_map_new_ functions that are
* dynamically created based on the needed keys and values.
* @{
*/
/** Create a new map.
* The exact name of this function depends on the defined key types.
* See the map overview.
* This functions accepts a variable number of arguments depending on
* the value of valtype.
* @param num_entries The maximum number of entries. Space for these
* entries are allocated when the SystemTap module is loaded.
* @param valtype Valid values are INT64, STRING, and STAT.
*/
MAP _stp_map_new_KEY1 (int num_entries, int valtype){}
/** Create a new map with values of stats with log histograms.
* When valtype is HSTAT_LOG, the following parameters are expected.
* @param num_entries The maximum number of entries. Space for these
* entries are allocated when the SystemTap module is loaded.
* @param buckets Number of buckets in the histogram. The maximum values
* for each bucket are 0, 1, 2, 4, 8, 16, 32, ... So if buckets is 8 the
* histogram will go from 0 - 64.
*/
MAP _stp_map_new_KEY1_ (int num_entries, HSTAT_LOG, int buckets){}
/** Create a new map with values of stats with linear histograms.
* When valtype is HSTAT_LOG, the following parameters are expected.
* @param num_entries The maximum number of entries. Space for these
* entries are allocated when the SystemTap module is loaded.
* @param start The starting value of the histogram.
* @param stop The stopping value of the histogram.
* @param interval The interval.
* @todo Check for reasonable values.
*/
MAP _stp_map_new_KEY1__ (int num_entries, HSTAT_LINEAR, int start, int stop, int interval) {}
/** @} end of map_create group */
/** @defgroup map_set Setting the Values in Maps
* This documents the _stp_map_set_ and _stp_map_add_ functions that are
* dynamically created based on the needed keys and values.
* @{
*/
/** Set the current element's value to a C string.
* This sets the current element's value to an C string. The map must have been created
* to hold strings using <i>_stp_map_new_(xxx, STRING)</i>
*
* If the element doesn't exist, it is created. If no current element (key)
* is set for the map, this function does nothing.
* @param map
* @param val new string
* @sa _stp_map_set()
*/
void _stp_map_set_str (MAP map, char *val) {}
/** Appends a C string to the current element's value
* This appends a C string to the current element's value. The map must have been created
* to hold strings using <i>_stp_map_new_(xxx, STRING)</i>
*
* If the element doesn't exist, it is created. If no current element (key)
* is set for the map, this function does nothing.
* @param map
* @param val string to append
* @sa _stp_map_set()
*/
void _stp_map_add_str (MAP map, char *val) {}
/** @} end of map_set group*/
/** @defgroup map_get Getting the Values from Maps
* This documents the _stp_map_get_ functions that are
* dynamically created based on the needed keys and values.
* @{
*/
/** Gets the current element's value.
* This returns the current element's value. The map must have been created
* to hold strings using <i>_stp_map_new_(xxx, STRING)</i>.
* @param map
* @returns A string pointer. If the current element is not set or doesn't exist, returns NULL.
*/
char *_stp_map_get_str (MAP map) {}
/** Gets the current element's value.
* This returns the current element's value. The map must have been created
* to hold stats using <i>_stp_map_new_(xxx, STAT)</i> (or HSTAT_LOG or HSTAT_LINEAR). This function would only be used
* @param map
* @returns A stat pointer. If the current element is not set or doesn't exist, returns NULL.
*/
stat *_stp_map_get_stat (MAP map) {}
/** Gets the current element's value.
* This returns the current element's value. The map must have been created
* to hold int64s using <i>_stp_map_new_(xxx, INT64)</i>.
* @param map
* @returns The value. If the current element is not set or doesn't exist, returns 0.
*/
int64_t _stp_map_get_int64 (MAP map) {}
/** @} end of map_get group */
/** @} */
/** @page format_string Format Strings
Format strings for maps and stats use a special format string. Be careful
not to confuse it with a printf-style format.
@verbatim
--- KEYS and RESULTS ---
%p - address (hex padded to sizeof(void *))
%P - symbolic address
%x - hex int64
%X - HEX int64
%d - decimal int64
%s - string
--- STATS ---
%m - min
%M - max
%A - avg
%S - sum
%H - histogram
%C - count
--- MISC ---
%% - print '%'
--- PER_CPU ---
%c - CPU number
@endverbatim
When printing map keys, format types are preceeded by a single-digit number
indicating the key number. For example, "%1d,%2s" prints key 1 as an int64 followed by
key 2 as a string. Here's a good example from the test files.
@include map_format.c
*/
|
