| 1 |
<?xml version='1.0'?> |
| 2 |
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
| 3 |
]> |
| 4 |
|
| 5 |
<section id="associativearrays"> |
| 6 |
<title>Associative Arrays</title> |
| 7 |
<indexterm> |
| 8 |
<primary>arrays</primary> |
| 9 |
<seealso>associative arrays</seealso> |
| 10 |
</indexterm> |
| 11 |
|
| 12 |
<indexterm> |
| 13 |
<primary>associative arrays</primary> |
| 14 |
<secondary>introduction</secondary> |
| 15 |
</indexterm> |
| 16 |
|
| 17 |
<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a collection of values. Simply put, an associative array is a collection of unique keys; each key in the array has a value associated with it.</para> |
| 18 |
|
| 19 |
<!--<para>SystemTap also supports the use of associative arrays. While an ordinary variable represents a single value, associative arrays can represent a list of values. 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 <emphasis>key pair</emphasis>.</para>--> |
| 20 |
|
| 21 |
<!-- next 2 indexterms for key pairs --> |
| 22 |
|
| 23 |
<!-- |
| 24 |
<indexterm> |
| 25 |
<primary>arrays</primary> |
| 26 |
<secondary>introduction</secondary> |
| 27 |
<tertiary>key pairs</tertiary> |
| 28 |
</indexterm> |
| 29 |
--> |
| 30 |
|
| 31 |
<indexterm> |
| 32 |
<primary>associative arrays</primary> |
| 33 |
<secondary>introduction</secondary> |
| 34 |
<tertiary>key pairs</tertiary> |
| 35 |
</indexterm> |
| 36 |
|
| 37 |
<indexterm> |
| 38 |
<primary>key pairs</primary> |
| 39 |
<secondary>introduction</secondary> |
| 40 |
<tertiary>arrays</tertiary> |
| 41 |
</indexterm> |
| 42 |
|
| 43 |
<!-- next 2 indexterms for unique keys |
| 44 |
|
| 45 |
<indexterm> |
| 46 |
<primary>arrays</primary> |
| 47 |
<secondary>introduction</secondary> |
| 48 |
<tertiary>unique keys</tertiary> |
| 49 |
</indexterm> |
| 50 |
--> |
| 51 |
<indexterm> |
| 52 |
<primary>associative arrays</primary> |
| 53 |
<secondary>introduction</secondary> |
| 54 |
<tertiary>unique keys</tertiary> |
| 55 |
</indexterm> |
| 56 |
|
| 57 |
<indexterm> |
| 58 |
<primary>unique keys</primary> |
| 59 |
<secondary>introduction</secondary> |
| 60 |
<tertiary>arrays</tertiary> |
| 61 |
</indexterm> |
| 62 |
|
| 63 |
<!-- next 2 indexterms for associated values |
| 64 |
|
| 65 |
<indexterm> |
| 66 |
<primary>arrays</primary> |
| 67 |
<secondary>introduction</secondary> |
| 68 |
<tertiary>associated values</tertiary> |
| 69 |
</indexterm> |
| 70 |
--> |
| 71 |
<indexterm> |
| 72 |
<primary>associative arrays</primary> |
| 73 |
<secondary>introduction</secondary> |
| 74 |
<tertiary>associated values</tertiary> |
| 75 |
</indexterm> |
| 76 |
|
| 77 |
<indexterm> |
| 78 |
<primary>associated values</primary> |
| 79 |
<secondary>introduction</secondary> |
| 80 |
<tertiary>arrays</tertiary> |
| 81 |
</indexterm> |
| 82 |
|
| 83 |
<!-- next 2 indexterms for index expression |
| 84 |
|
| 85 |
<indexterm> |
| 86 |
<primary>arrays</primary> |
| 87 |
<secondary>introduction</secondary> |
| 88 |
<tertiary>index expression</tertiary> |
| 89 |
</indexterm> |
| 90 |
--> |
| 91 |
<indexterm> |
| 92 |
<primary>associative arrays</primary> |
| 93 |
<secondary>introduction</secondary> |
| 94 |
<tertiary>index expression</tertiary> |
| 95 |
</indexterm> |
| 96 |
|
| 97 |
<indexterm> |
| 98 |
<primary>index expression</primary> |
| 99 |
<secondary>introduction</secondary> |
| 100 |
<tertiary>arrays</tertiary> |
| 101 |
</indexterm> |
| 102 |
|
| 103 |
<para>Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they should be declared as <command>global</command> variables in the SystemTap script. The syntax for accessing an element in an associative array is similar to that of <command>awk</command>, and is as follows:</para> |
| 104 |
<!-- next 3 indexterms for syntax |
| 105 |
<indexterm> |
| 106 |
<primary>arrays</primary> |
| 107 |
<secondary>introduction</secondary> |
| 108 |
<tertiary>syntax</tertiary> |
| 109 |
</indexterm> |
| 110 |
--> |
| 111 |
<indexterm> |
| 112 |
<primary>associative arrays</primary> |
| 113 |
<secondary>introduction</secondary> |
| 114 |
<tertiary>syntax</tertiary> |
| 115 |
</indexterm> |
| 116 |
|
| 117 |
<indexterm> |
| 118 |
<primary>syntax</primary> |
| 119 |
<secondary>introduction</secondary> |
| 120 |
<tertiary>arrays</tertiary> |
| 121 |
</indexterm> |
| 122 |
|
| 123 |
<indexterm> |
| 124 |
<primary>format</primary> |
| 125 |
<secondary>introduction</secondary> |
| 126 |
<tertiary>arrays</tertiary> |
| 127 |
</indexterm> |
| 128 |
|
| 129 |
|
| 130 |
<screen><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>]</screen> |
| 131 |
|
| 132 |
<para>Here, the <command><replaceable>array_name</replaceable></command> is any arbitrary name the array uses. The <command><replaceable>index_expression</replaceable></command> is used to refer to a specific unique key in the array. To illustrate, let us try to build an array named <command>foo</command> that specifies the ages of three people <command>tom</command>, <command>dick</command>, and <command>harry</command> (which are unique keys). To assign them the ages (associated values) of 23, 24, and 25 respectively, we'd use the following array statements:</para> |
| 133 |
|
| 134 |
<!-- next 2 indexterms for example |
| 135 |
|
| 136 |
<indexterm> |
| 137 |
<primary>arrays</primary> |
| 138 |
<secondary>introduction</secondary> |
| 139 |
<tertiary>example</tertiary> |
| 140 |
</indexterm> |
| 141 |
--> |
| 142 |
<indexterm> |
| 143 |
<primary>associative arrays</primary> |
| 144 |
<secondary>introduction</secondary> |
| 145 |
<tertiary>example</tertiary> |
| 146 |
</indexterm> |
| 147 |
|
| 148 |
<indexterm> |
| 149 |
<primary>example</primary> |
| 150 |
<secondary>introduction</secondary> |
| 151 |
<tertiary>arrays</tertiary> |
| 152 |
</indexterm> |
| 153 |
<example id="arraysimplestexample"> |
| 154 |
<title>Basic Array Statements</title> |
| 155 |
<screen>foo["tom"] = 23 |
| 156 |
foo["dick"] = 24 |
| 157 |
foo["harry"] = 25</screen> |
| 158 |
</example> |
| 159 |
|
| 160 |
<para>You can specify up to nine index expressions in an array statement, each one delimited by a comma (<command>,</command>). This is useful if you wish to have a key that contains multiple pieces of information. The following line from <xref linkend="scriptdisktop"/> uses 5 elements for the key: process ID, executable name, user ID, parent process ID, and string "W". It associates the value of <command>devname</command> with that key.</para> |
| 161 |
|
| 162 |
<screen>device[pid(),execname(),uid(),ppid(),"W"] = devname</screen> |
| 163 |
|
| 164 |
<important> |
| 165 |
<title>Important</title> |
| 166 |
<para>All associate arrays must be declared as <command>global</command>, regardless of whether the associate array is used in one or multiple probes. </para> |
| 167 |
</important> |
| 168 |
|
| 169 |
|
| 170 |
|
| 171 |
<!-- |
| 172 |
<varlistentry> |
| 173 |
<term></term> |
| 174 |
<listitem> |
| 175 |
<para></para> |
| 176 |
</listitem> |
| 177 |
</varlistentry> |
| 178 |
--> |
| 179 |
|
| 180 |
|
| 181 |
|
| 182 |
|
| 183 |
|
| 184 |
<!-- |
| 185 |
|
| 186 |
<para>SystemTap supports numerous ways to manipulate associative arrays (i.e. <command><replaceable>operation</replaceable></command> in the syntax format). For the purposes of this book, we will only cover the most common examples of manipulating associative arrays, all of which appear in <xref linkend="useful-systemtap-scripts"/>.</para> |
| 187 |
|
| 188 |
<formalpara id="aaexamplesimple"> |
| 189 |
<title>Incrementing Associated Values of Unique Keys</title> |
| 190 |
<para>The simplest form of data manipulation in associative arrays is incrementing the associated value of a unique key in the array. The syntax for this operation is as follows:</para> |
| 191 |
</formalpara> |
| 192 |
<screen><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>"] ++</screen> |
| 193 |
|
| 194 |
<para>Here, the <command>++</command> operation instructs SystemTap to increment the associated value of <command><replaceable>unique_key</replaceable></command> by <command><replaceable>value</replaceable></command>. For example, to increase the associated value of unique key <command>hello</command> in array <command>foo</command> by 4, use:</para> |
| 195 |
|
| 196 |
<formalpara id="aaexamplesimple-example"> |
| 197 |
<title>explicit-incrementing-in-arrays.stp</title> |
| 198 |
<para> |
| 199 |
<programlisting>probe begin { foo[4,"hello"] ++ }</programlisting> |
| 200 |
</para> |
| 201 |
</formalpara> |
| 202 |
|
| 203 |
<formalpara id="aaexampleupdatecounting"> |
| 204 |
<title>Incrementing Associated Values of Unique Keys (By Variable)</title> |
| 205 |
|
| 206 |
<para>One of the most common uses of associative arrays is to tally events per unique key. To do this, use the operator <command>+= $count</command>, as in:</para> |
| 207 |
</formalpara> |
| 208 |
|
| 209 |
<screen><replaceable>array_name</replaceable>[<replaceable>unique_key</replaceable>] += $count </screen> |
| 210 |
|
| 211 |
<para>You can also use a handler function in as the <command><replaceable>unique_key</replaceable></command>. Doing so creates an associate array that uses the values returned by the handler function as the unique keys. The first time that a probe using this array returns a string value, that value is set as a unique key with an initial value of 0. The next time that the probe returns the same string value, it increments the associated value of the unique key by 1.</para> |
| 212 |
|
| 213 |
<para>For example, let's say you need to tally how many times each process performs a read to the virtual file system (VFS). To do this, probe the VFS read opeartion, use the handler <command>execname()</command> to identify which processes performed the VFS read, and tally the reads of each process using the associative array named <command>reads</command>, as in</para> |
| 214 |
|
| 215 |
<formalpara id="aaexamplesimplevfsreads"> |
| 216 |
<title>tallying-in-arrays.stp</title> |
| 217 |
<para> |
| 218 |
<programlisting>probe vfs.read |
| 219 |
{ reads[execname()] += $count }</programlisting> |
| 220 |
</para> |
| 221 |
</formalpara> |
| 222 |
|
| 223 |
<para>In <xref linkend="aaexamplesimplevfsreads"/>, the first time that the probe returns the process name <command>gnome-terminal</command> (that is, the first time <command>gnome-terminal</command> performs a VFS read), that process name is set as a unique key. The next time that the probe returns the process name <command>gnome-terminal</command>, SystemTap increments the associated value of <command>gnome-terminal</command> by 1. SystemTap performs this operation for <emphasis>all</emphasis> process names as the probe returns them.</para> |
| 224 |
--> |
| 225 |
</section> |