From e32551b18f4560056d2d482f5e1505b1b98fa82a Mon Sep 17 00:00:00 2001 From: hunt Date: Tue, 29 Mar 2005 18:07:58 +0000 Subject: *** empty log message *** --- runtime/docs/html/group__maps.html | 1265 ++++++++++++++++++++++++++++++++++++ 1 file changed, 1265 insertions(+) create mode 100644 runtime/docs/html/group__maps.html (limited to 'runtime/docs/html/group__maps.html') diff --git a/runtime/docs/html/group__maps.html b/runtime/docs/html/group__maps.html new file mode 100644 index 00000000..1da96a51 --- /dev/null +++ b/runtime/docs/html/group__maps.html @@ -0,0 +1,1265 @@ + + +SystemTap: Maps + + + +

Maps

Implements maps (associative arrays) and lists. +More... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +


Data Structures
struct	stat
	Statistics are stored in this struct. More...
union	key_data
	Keys are either longs or char *. More...
struct	map_node
	basic map element More...
struct	map_node_int64
	map element containing int64 More...
struct	map_node_str
	map element containing string More...
struct	map_node_stat
	map element containing stats More...
struct	map_root
	This structure contains all information about a map. More...
Defines
+#define	key1str(ptr) (ptr->n.key1.str)
	Extracts string from key1 union.
+#define	key2str(ptr) (ptr->n.key2.str)
	Extracts string from key2 union.
+#define	key1int(ptr) (ptr->n.key1.val)
	Extracts int from key1 union.
+#define	key2int(ptr) (ptr->n.key2.val)
	Extracts int from key2 union.
#define	_stp_map_key2(map, key1, key2)
	Macro to call the proper _stp_map_key functions based on the types of the arguments.
#define	_stp_map_key(map, key)
	Macro to call the proper _stp_map_key function based on the type of the argument.
#define	_stp_map_set(map, val)
	Macro to call the proper _stp_map_set function based on the type of the argument.
#define	foreach(map, ptr)
	Loop through all elements of a map or list.
Typedefs
+typedef map_root *	MAP
	All maps are of this type.
Enumerations
enum	keytype { NONE, +LONG, +STR + }
	keys can be longs or strings
enum	valtype { INT64, +STAT, +STRING, +END + }
	values can be either int64, stats or strings
Functions
MAP	_stp_map_new (unsigned max_entries, enum valtype type)
	Create a new map.
void	_stp_map_key_del (MAP map)
	Deletes the current element.
map_node *	_stp_map_start (MAP map)
	Get the first element in a map.
map_node *	_stp_map_iter (MAP map, struct map_node *m)
	Get the next element in a map.
void	_stp_map_del (MAP map)
	Deletes a map.
void	_stp_map_key_long_long (MAP map, long key1, long key2)
	Set the map's key to two longs.
void	_stp_map_key_str_str (MAP map, char key1, char key2)
	Set the map's key to two strings.
void	_stp_map_key_str_long (MAP map, char *key1, long key2)
	Set the map's key to a string and a long.
void	_stp_map_key_long_str (MAP map, long key1, char *key2)
	Set the map's key to a long and a string.
void	_stp_map_key_str (MAP map, char *key)
	Set the map's key to a string.
void	_stp_map_key_long (MAP map, long key)
	Set the map's key to a long.
void	_stp_map_set_int64 (MAP map, int64_t val)
	Set the current element's value to an int64.
void	_stp_map_add_int64 (MAP map, int64_t val)
	Adds an int64 to the current element's value.
int64_t	_stp_map_get_int64 (MAP map)
	Gets the current element's value.
void	_stp_map_set_str (MAP map, char *val)
	Set the current element's value to a string.
char *	_stp_map_get_str (MAP map)
	Gets the current element's value.
void	_stp_map_set_stat (MAP map, stat *stats)
	Set the current element's value to a stat.
stat *	_stp_map_get_stat (MAP map)
	Gets the current element's value.
void	_stp_map_stat_add (MAP map, int64_t val)
	Add to the current element's statistics.
Variables
+enum keytype	packed
	keys can be longs or strings

Detailed Description

+Implements maps (associative arrays) and lists. +

Define Documentation

+ + + + +
+ + + + + + + + + + + + +
#define _stp_map_key ( map,
key )
+
+ + + + + +
+ + + +
+Value:
({ \ + if (__builtin_types_compatible_p (typeof (key), char[])) \ + _stp_map_key_str (map, (char *)(key)); \ + else \ + _stp_map_key_long (map, (long)(key)); \ + }) +
Macro to call the proper _stp_map_key function based on the type of the argument. +
+
Note:
May cause compiler warning on some GCCs
+ +
+Definition at line 141 of file map.h.
+

+ + + + +
+ + + + + + + + + + + + + + + +
#define _stp_map_key2 ( map,
key1,
key2 )
+
+ + + + + +
+ + + +
+Value:
({ \ + if (__builtin_types_compatible_p (typeof (key1), char[])) \ + if (__builtin_types_compatible_p (typeof (key2), char[])) \ + _stp_map_key_str_str (map, (char *)(key1), (char *)(key2)); \ + else \ + _stp_map_key_str_long (map, (char *)(key1), (long)(key2)); \ + else \ + if (__builtin_types_compatible_p (typeof (key2), char[])) \ + _stp_map_key_long_str (map, (long)(key1), (char *)(key2)); \ + else \ + _stp_map_key_long_long (map, (long)(key1), (long)(key2)); \ + }) +
Macro to call the proper _stp_map_key functions based on the types of the arguments. +
+
Note:
May cause compiler warning on some GCCs
+ +
+Definition at line 123 of file map.h.
+

+ + + + +
+ + + + + + + + + + + + +
#define _stp_map_set ( map,
val )
+
+ + + + + +
+ + + +
+Value:
({ \ + if (__builtin_types_compatible_p (typeof (val), char[])) \ + _stp_map_set_str (map, (char *)(val)); \ + else \ + _stp_map_set_int64 (map, (int64_t)(val)); \ + }) +
Macro to call the proper _stp_map_set function based on the type of the argument. +
+
Note:
May cause compiler warning on some GCCs
+ +
+Definition at line 153 of file map.h.
+

+ + + + +
+ + + + + + + + + + + + +
#define foreach ( map,
ptr )
+
+ + + + + +
+ + + +
+Value:
for (ptr = (typeof(ptr))_stp_map_start(map); ptr; \ + ptr = (typeof(ptr))_stp_map_iter (map, (struct map_node *)ptr)) +
Loop through all elements of a map or list. +
+
Parameters:
+ + + +
map
ptr pointer to a map_node_stat, map_node_int64 or map_node_str
+
+Example:
/* example showing how to print all the stats in a map using foreach() */ + +struct map_node_stat *ptr; + +foreach (map, ptr) + printf ("map[%s,%ld] = [c=%lld s=%lld min=%lld max=%lld]\n", key1str(ptr), + key2int(ptr), ptr->stats.count, ptr->stats.sum, ptr->stats.min, + ptr->stats.max); + +
+
+Definition at line 169 of file map.h.
+

Function Documentation

+ + + + +
+ + + + + + + + + + + + + + + + + + +
void _stp_map_add_int64 ( MAP map,
int64_t 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 _stp_map_new()
+If the element doesn't exist, it is created. If no current element (key) is set for the map, this function does nothing.
Parameters:
+ + + +
map
val value
+
+
See also:
_stp_map_set_int64
+ +
+Definition at line 558 of file map.c.
+

+ + + + +
+ + + + + + + + + +
void _stp_map_del ( MAP map )
+
+ + + + + +
+ + + +
+Deletes a map. +
+Deletes a map, freeing all memory in all elements. Normally done only when the module exits.
Parameters:
+ + +
map
+
+ +
+Definition at line 205 of file map.c. +
+References _stp_vfree(), map_root::head, map_node::lnode, and map_root::membuf.
+

+ + + + +
+ + + + + + + + + +
int64_t _stp_map_get_int64 ( MAP map )
+
+ + + + + +
+ + + +
+Gets the current element's value. +
+
Parameters:
+ + +
map
+
+
Returns:
The value. If the current element is not set or doesn't exist, returns 0.
+ +
+Definition at line 568 of file map.c. +
+References map_root::create, map_root::key, and map_node_int64::val.
+

+ + + + +
+ + + + + + + + + +
stat* _stp_map_get_stat ( MAP map )
+
+ + + + + +
+ + + +
+Gets the current element's value. +
+
Parameters:
+ + +
map
+
+
Returns:
A pointer to the stats struct. If the current element is not set or doesn't exist, returns NULL.
+ +
+Definition at line 732 of file map.c. +
+References map_root::create, map_root::key, and map_node_stat::stats.
+

+ + + + +
+ + + + + + + + + +
char* _stp_map_get_str ( MAP map )
+
+ + + + + +
+ + + +
+Gets the current element's value. +
+
Parameters:
+ + +
map
+
+
Returns:
A string pointer. If the current element is not set or doesn't exist, returns NULL.
+ +
+Definition at line 649 of file map.c. +
+References map_root::create, map_root::key, and map_node_str::str.
+

+ + + + +
+ + + + + + + + + + + + + + + + + + +
struct map_node* _stp_map_iter ( MAP map,
struct map_node * m
)
+
+ + + + + +
+ + + +
+Get the next element in a map. +
+
Parameters:
+ + + +
map
m a pointer to the current element, returned from _stp_map_start() or _stp_map_iter().
+
+
Returns:
a pointer to the next element. This is typically used with _stp_map_start(). See the foreach() macro for typical usage. It probably does what you want anyway.
+
See also:
foreach
+ +
+Definition at line 186 of file map.c. +
+References map_root::head, and map_node::lnode.
+

+ + + + +
+ + + + + + + + + +
void _stp_map_key_del ( MAP map )
+
+ + + + + +
+ + + +
+Deletes the current element. +
+If no current element (key) for this map is set, this function does nothing.
Parameters:
+ + +
map
+
+ +
+Definition at line 118 of file map.c. +
+References _stp_free(), map_node::hnode, and map_node::lnode. +
+Referenced by _stp_map_set_stat(), and _stp_map_set_str().
+

+ + + + +
+ + + + + + + + + + + + + + + + + + +
void _stp_map_key_long ( MAP map,
long key
)
+
+ + + + + +
+ + + +
+Set the map's key to a long. +
+This sets the current element based on a long key. If the key is not found, a new element will not be created until a _stp_map_set_xxx call.
Parameters:
+ + + +
map
key
+
+ +
+Definition at line 430 of file map.c. +
+References _stp_map_key_long_long(), and map_root::c_key2type. +
+Referenced by _stp_list_add_int64(), and _stp_list_add_str().
+

+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
void _stp_map_key_long_long ( MAP map,
long key1,
long key2
)
+
+ + + + + +
+ + + +
+Set the map's key to two longs. +
+This sets the current element based on a key of two strings. If the keys are not found, a new element will not be created until a _stp_map_set_xxx call.
Parameters:
+ + + + +
map
key1 first key
key2 second key
+
+ +
+Definition at line 233 of file map.c. +
+References map_root::c_key1, map_root::c_key1type, map_root::c_key2, map_root::c_key2type, map_root::c_keyhead, map_root::create, map_root::hashes, map_root::key, map_node::key1, and key_data::val. +
+Referenced by _stp_map_key_long().
+

+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
void _stp_map_key_long_str ( MAP map,
long key1,
char * key2
)
+
+ + + + + +
+ + + +
+Set the map's key to a long and a string. +
+This sets the current element based on a key of a long and a string. If the keys are not found, a new element will not be created until a _stp_map_set_xxx call.
Parameters:
+ + + + +
map
key1 first key
key2 second key
+
+ +
+Definition at line 373 of file map.c. +
+References map_root::c_key1, map_root::c_key1type, map_root::c_key2, map_root::c_key2type, map_root::c_keyhead, map_root::create, map_root::hashes, map_root::key, map_node::key1, map_node::key2, key_data::str, and key_data::val.
+

+ + + + +
+ + + + + + + + + + + + + + + + + + +
void _stp_map_key_str ( MAP map,
char * key
)
+
+ + + + + +
+ + + +
+Set the map's key to a string. +
+This sets the current element based on a string key. If the key is not found, a new element will not be created until a _stp_map_set_xxx call.
Parameters:
+ + + +
map
key
+
+ +
+Definition at line 414 of file map.c. +
+References _stp_map_key_str_str(), and map_root::c_key2type.
+

+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
void _stp_map_key_str_long ( MAP map,
char * key1,
long key2
)
+
+ + + + + +
+ + + +
+Set the map's key to a string and a long. +
+This sets the current element based on a key of a string and a long. If the keys are not found, a new element will not be created until a _stp_map_set_xxx call.
Parameters:
+ + + + +
map
key1 first key
key2 second key
+
+ +
+Definition at line 325 of file map.c. +
+References map_root::c_key1, map_root::c_key1type, map_root::c_key2, map_root::c_key2type, map_root::c_keyhead, map_root::create, map_root::hashes, map_root::key, map_node::key1, map_node::key2, key_data::str, and key_data::val.
+

+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
void _stp_map_key_str_str ( MAP map,
char * key1,
char * key2
)
+
+ + + + + +
+ + + +
+Set the map's key to two strings. +
+This sets the current element based on a key of two strings. If the keys are not found, a new element will not be created until a _stp_map_set_xxx call.
Parameters:
+ + + + +
map
key1 first key
key2 second key
+
+ +
+Definition at line 276 of file map.c. +
+References map_root::c_key1, map_root::c_key1type, map_root::c_key2, map_root::c_key2type, map_root::c_keyhead, map_root::create, map_root::hashes, map_root::key, map_node::key1, map_node::key2, and key_data::str. +
+Referenced by _stp_map_key_str().
+

+ + + + +
+ + + + + + + + + + + + + + + + + + +
MAP _stp_map_new ( unsigned max_entries,
enum valtype type
)
+
+ + + + + +
+ + + +
+Create a new map. +
+Maps must be created at module initialization time.
Parameters:
+ + + +
max_entries The maximum number of entries allowed. Currently that number will be preallocated. If more entries are required, the oldest ones will be deleted. This makes it effectively a circular buffer. If max_entries is 0, there will be no maximum and entries will be allocated dynamically.
type Type of values stored in this map.
+
+
Returns:
A MAP on success or NULL on failure.
+ +
+Definition at line 57 of file map.c. +
+References _stp_valloc(), map_root::head, map_root::maxnum, map_root::membuf, map_root::pool, and map_root::type. +
+Referenced by _stp_list_new().
+

+ + + + +
+ + + + + + + + + + + + + + + + + + +
void _stp_map_set_int64 ( MAP map,
int64_t val
)
+
+ + + + + +
+ + + +
+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 _stp_map_new()
+If the element doesn't exist, it is created. If no current element (key) is set for the map, this function does nothing.
Parameters:
+ + + +
map
val new value
+
+
See also:
_stp_map_add_int64
+ +
+Definition at line 541 of file map.c. +
+Referenced by _stp_list_add_int64().
+

+ + + + +
+ + + + + + + + + + + + + + + + + + +
void _stp_map_set_stat ( MAP map,
stat * stats
)
+
+ + + + + +
+ + + +
+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 _stp_map_new(xxx, STAT). This function would only be used if we wanted to set stats to something other than the normal initial values (count = 0, sum = 0, etc). It may be deleted if it doesn't turn out to be useful.
See also:
_stp_map_stat_add
+If the element doesn't exist, it is created. If no current element (key) is set for the map, this function does nothing.
Parameters:
+ + + +
map
stats pointer to stats struct.
+
+
Todo:
Histograms don't work yet.
+ +
+Definition at line 673 of file map.c. +
+References _stp_calloc(), _stp_map_key_del(), map_root::create, map_root::head, map_node::hnode, map_root::key, map_node::lnode, map_root::maxnum, map_node_stat::n, map_root::no_wrap, map_root::pool, and map_node_stat::stats. +
+Referenced by _stp_map_stat_add().
+

+ + + + +
+ + + + + + + + + + + + + + + + + + +
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 an string. The map must have been created to hold int64s using _stp_map_new(xxx, STRING)
+If the element doesn't exist, it is created. If no current element (key) is set for the map, this function does nothing.
Parameters:
+ + + +
map
val new string
+
+ +
+Definition at line 588 of file map.c. +
+References _stp_alloc(), _stp_calloc(), _stp_free(), _stp_map_key_del(), map_root::create, map_root::head, map_node::hnode, map_root::key, map_node::lnode, map_root::maxnum, map_node_str::n, map_root::no_wrap, map_root::pool, and map_node_str::str. +
+Referenced by _stp_list_add_str().
+

+ + + + +
+ + + + + + + + + +
struct map_node* _stp_map_start ( MAP map )
+
+ + + + + +
+ + + +
+Get the first element in a map. +
+
Parameters:
+ + +
map
+
+
Returns:
a pointer to the first element. This is typically used with _stp_map_iter(). See the foreach() macro for typical usage. It probably does what you want anyway.
+
See also:
foreach
+ +
+Definition at line 163 of file map.c. +
+References map_root::head.
+

+ + + + +
+ + + + + + + + + + + + + + + + + + +
void _stp_map_stat_add ( MAP map,
int64_t val
)
+
+ + + + + +
+ + + +
+Add to the current element's statistics. +
+Increments the statistics counter by one and the sum by val. 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.
Parameters:
+ + + +
map
val value to add to the statistics
+
+
Todo:
Histograms don't work yet.
+ +
+Definition at line 753 of file map.c. +
+References _stp_map_set_stat(), stat::count, map_root::create, map_root::key, stat::max, stat::min, map_node_stat::stats, and stat::sum.
+ -- cgit

Maps

Data Structures

Defines

Typedefs

Enumerations

Functions

Variables

Detailed Description

Define Documentation

Function Documentation