Debian Codegraph @

doc/SystemTap_Beginners_Guide/en-US/Arrays.xml

raw
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>