From c57eb295b15067b8f7964c5e5bd798f1d31a36e5 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Fri, 24 Oct 2008 16:27:01 +1000 Subject: added new section on arrays --- doc/SystemTap_Beginners_Guide/en-US/Arrays.xml | 197 +++++++++++++++++++------ 1 file changed, 150 insertions(+), 47 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US') diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml index 13122189..0df6c817 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml @@ -5,75 +5,178 @@
Associative Arrays -SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values arranged in tabular format. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it. Illustrating this visually would be similar to creating a two-column table: the first column would have the unique key, while the second column would have the associated value. +SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values arranged in tabular format. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it. Illustrating this visually would be similar to creating a two-column table: the first column would have the unique key, while the second column would have each key's associated value. Each unique key and its associated value is referred to as a key pair. -Associative arrays are useful in processing data that would normally be represented best in tabular format. For example, let's say you wanted to see how many times any specific program performs a read to the virtual file system. In this case, your probe would use the event kernel.function("vfs_read"); execname() identifies which program or process performs the read. +Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they are declared as global variables in the SystemTap script. The syntax for manipulating arrays is similar to that of awk, and is as follows: + + +array_name[index expression] operation + + +Here, the array_name is any arbitrary name the array uses. The index expression is used to refer to a specific unique key (or set of unique keys) in the array, and the operation defines what to do with the index expression. To illustrate, let us try to build an array named foo that specifies the ages of three people (i.e. the unique keys): tom, dick, and harry. To assign them the ages (i.e. associated values) of 23, 24, and 25 respectively, we'd use the following array statements: + + + + Basic Array Statements + +foo["tom"] = 23 +foo["dick"] = 24 +foo["harry"] = 25 + + + +
+ Tuples +Another important point to remember in arrays is that each exists in a slot in the array. A key pair's slot is defined by the order in which each pair's unique key is defined. In our sample array foo in , the key pair that uses the unique key tom is in the first slot, since tom was the first unique key to be defined. dick is in the second slot, and so on. + + +The sequence in which each key pair appears in an array (as defined by each pair's slot) is referred to as a tuple. Tuples allow us to refer to key pairs in an array by the order in which they appear in the sequence. + +For example, the array statements in set 23 as the associated value of the unique key tom. Given the same array foo, we can increment the associated value of tom by 1 using the operator ++, like so: + + +foo["tom"] ++ + + +The above statement will increase the associated value of unique key tom to 24. Now, looking back at , we know that dick was the first uniqe key to be defined. As such, we can perform the same operation (i.e. incrementing associated value by 1) to dick using the following statement: + + +foo[2] ++ + + + + Note + You can specify up to 5 index index expressons in an array statement, each one delimited by a comma (,). This is useful if you wish to perform the same operation to a set of key pairs. For example, to increase the associated value of all the key pairs defined by , you can use the following statement: + + +foo["tom",2,"harry"] ++ + + + + +
+ +
+ Commonly Used Array Operators in SystemTap + +This section enumerates some of the most commonly used array operators in SystemTap. + + + + + Assigning Associated Value + + Use = to set an associated value to indexed unique pairs, as in: + +array_name[index expression] = value + + + shows a very basic example of how to set an explicit associated value to a unique key. You can also use a handler function as both your index expression and value. For example, you can use arrays to set a timestamp as the associated value to a process name (which you wish to use as your unique key), as in: + + + Associating Timestamps to Process Names + +foo[execname()] = gettimeofday_s() + + + +Whenever an event invokes the statement in , SystemTap returns the appropriate execname() value (i.e. the name of a process, which is then used as the unique key). At the same time, SystemTap also uses the function gettimeofday_s() to set the corresponding timestamp as the associated value to the unique key defined by the function execname(). This creates an array composed of key pairs containing process names and timestamps. + +In this same example, if execname() returns a value that is already defined in the array foo, the operator will discard the original associated value to it, and replace it with the current timestamp from gettimeofday_s(). + + + + Incrementing Associated Values + + Use ++ to increment the associated value of a unique key in an array, as in: + +array_name[index expression] ++ + + +Again, you can also use a handler function for your index expression. For example, if you wanted to tally how many times a specific process performed a read to the virtual file system (using the event kernel.function("vfs_read")), you can use the following probe: + vfsreads.stp probe kernel.function("vfs_read") -{ - printf("%s\n", execname()) -} +{ + reads[execname()] ++ +} - will display the name of each program that performs a read to the virtual file system as each read is performed. This means that the output of will be a long list of process names, most of which will be repeating. For to be useful, you'd need to feed its output to another program that counts how many times each process name appears and tally the results. +In , the first time that the probe returns the process name gnome-terminal (i.e. the first time gnome-terminal performs a VFS read), that process name is set as the unique key gnome-terminal with an associated value of 1. The next time that the probe returns the process name gnome-terminal, SystemTap increments the associated value of gnome-terminal by 1. SystemTap performs this operation for all process names as the probe returns them. + + + + + + +need to add a link to a more complete list of commonly used array operators! +
+ + + + + + +
\ No newline at end of file -- cgit