From 3750373a50833fcda902407e5b260cb8c5799ad6 Mon Sep 17 00:00:00 2001 From: hunt Date: Thu, 26 May 2005 07:21:46 +0000 Subject: [PATCH] Document generated functions for maps. --- runtime/map.doc | 191 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 runtime/map.doc diff --git a/runtime/map.doc b/runtime/map.doc new file mode 100644 index 000000000..94d9ffdd9 --- /dev/null +++ b/runtime/map.doc @@ -0,0 +1,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 _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. + * @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 _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. + * @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 _stp_map_new_(xxx, INT64) + * + * 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 _stp_map_new_(xxx, STAT) (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 _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. + * @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 _stp_map_new_(xxx, INT64) + * + * 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 _stp_map_new_(xxx, STAT) (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 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. + * @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 _stp_map_new_(xxx, STRING). + * @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 _stp_map_new_(xxx, STAT) (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 _stp_map_new_(xxx, INT64). + * @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 */ +/** @} */ -- 2.43.5