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
184
185
186
187
188
189
190
191
|
/* This is for documentation only. Do not compile. */
/* -*- linux-c -*- */
*/
/** @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) {}
/** Set the current element's value to a String.
* This sets the current element's value to a 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 str String containing new value.
* @sa _stp_map_set()
*/
void _stp_map_set_string (MAP map, String str){}
/** Set the current element's value to an int64.
* This sets the current element's value to an int64. The map must have been created
* to hold int64s using <i>_stp_map_new_(xxx, INT64)</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 value
* @sa _stp_map_add_int64()
* @sa _stp_map_set()
*/
void _stp_map_set_int64 (MAP map, int64_t val) {}
/** Set the current element's value to a stat.
* This sets the current element's value to an stat struct. 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
* if you want to set stats to something other than the normal initial values (count = 0,
* sum = 0, etc).
* @sa _stp_map_add_stat
* @sa _stp_map_add_int64_stat
*
* 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 pointer to stats struct.
*/
void _stp_map_set_stat (MAP map, stat *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) {}
/** Adds an int64 to the current element's value.
* This adds an int64 to the current element's value. The map must have been created
* to hold int64s using <i>_stp_map_new_(xxx, INT64)</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 value
* @sa _stp_map_set_int64()
*/
void _stp_map_add_int64 (MAP map, int64_t val) {}
/** Add stats to the current element's value.
* This adds stats to the current element's value to an stat struct. 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
* to combine stats from multiple sources into a single stats struct.
* @sa _stp_map_add_stat
* @sa _stp_map_add_int64_stat
*
* 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 pointer to stats struct.
*/
void _stp_map_add_stat (MAP map, stat *val) {}
/** Add an int64 to the current element's statistics.
* Increments the statistics counter by one and the sum by <i>val</i>.
* Adjusts minimum, maximum, and histogram.
*
* 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 value to add to the statistics
*/
void _stp_map_add_int64_stat (MAP map, int64_t 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 */
/** @} */
|
