Debian Codegraph @

doc/SystemTap_Beginners_Guide/en-US/Array-Operations.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="arrayoperators">
6 <title>Array Operations in SystemTap</title>
7 <indexterm>
8 <primary>array operations</primary>
9 <secondary>associative arrays</secondary>
10 </indexterm>
11
12 <indexterm>
13 <primary>operations</primary>
14 <secondary>associative arrays</secondary>
15 </indexterm>
16
17 <para>This section enumerates some of the most commonly used array operations in SystemTap.</para>
18
19 <section id="arrayops-assignvalue">
20 <title>Assigning an Associated Value</title>
21
22 <indexterm>
23 <primary>array operations</primary>
24 <secondary>assigning associated values</secondary>
25 </indexterm>
26
27 <indexterm>
28 <primary>assigning associated values</primary>
29 <secondary>array operations</secondary>
30 </indexterm>
31
32 <indexterm>
33 <primary>values, assignment of</primary>
34 <secondary>array operations</secondary>
35 </indexterm>
36 <para>Use <command>=</command> to set an associated value to indexed unique pairs, as in:</para>
37
38 <screen><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>] = <replaceable>value</replaceable></screen>
39
40 <para><xref linkend="arraysimplestexample"/> 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 <command><replaceable>index_expression</replaceable></command> and <command><replaceable>value</replaceable></command>. 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:</para>
41 <indexterm>
42 <primary>assigning associated values</primary>
43 <secondary>array operations</secondary>
44 <tertiary>associating timestamps to process names</tertiary>
45 </indexterm>
46
47 <indexterm>
48 <primary>array operations</primary>
49 <secondary>assigning associated values</secondary>
50 <tertiary>associating timestamps to process names</tertiary>
51 </indexterm>
52
53 <indexterm>
54 <primary>operations</primary>
55 <secondary>assigning associated values</secondary>
56 <tertiary>associating timestamps to process names</tertiary>
57 </indexterm>
58
59 <indexterm>
60 <primary>assigning associated values</primary>
61 <secondary>associating timestamps to process names</secondary>
62 <tertiary>array operations</tertiary>
63 </indexterm>
64
65 <indexterm>
66 <primary>associating timestamps to process names</primary>
67 <secondary>assigning associated values</secondary>
68 <tertiary>array operations</tertiary>
69 </indexterm>
70
71 <indexterm>
72 <primary>timestamps, association thereof to process names</primary>
73 <secondary>assigning associated values</secondary>
74 <tertiary>array operations</tertiary>
75 </indexterm>
76
77
78 <example id="arrays-timestampprocessname">
79 <title>Associating Timestamps to Process Names</title>
80 <programlisting>foo[tid()] = gettimeofday_s()</programlisting>
81 </example>
82
83 <para>Whenever an event invokes the statement in <xref linkend="arrays-timestampprocessname"/>, SystemTap returns the appropriate <command>tid()</command> value (that is, the ID of a thread, which is then used as the unique key). At the same time, SystemTap also uses the function <command>gettimeofday_s()</command> to set the corresponding timestamp as the associated value to the unique key defined by the function <command>tid()</command>. This creates an array composed of key pairs containing thread IDs and timestamps.</para>
84
85 <para>In this same example, if <command>tid()</command> returns a value that is already defined in the array <command>foo</command>, the operator will discard the original associated value to it, and replace it with the current timestamp from <command>gettimeofday_s()</command>.</para>
86 </section>
87 <section id="arrayops-readvalues">
88 <title>Reading Values From Arrays</title>
89 <indexterm>
90 <primary>reading values from arrays</primary>
91 <secondary>array operations</secondary>
92 </indexterm>
93
94
95 <indexterm>
96 <primary>array operations</primary>
97 <secondary>reading values from arrays</secondary>
98 </indexterm>
99
100 <indexterm>
101 <primary>operations</primary>
102 <secondary>reading values from arrays</secondary>
103 </indexterm>
104
105 <para>You can also read values from an array the same way you would read the value of a variable.
106 To do so, include the
107 <command><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>]</command>
108 statement as an element in a mathematical expression. For example:</para>
109 <!--
110 <para>You can also use the <command>=</command> operator to read values from an array. This is accomplished by simply including the <command><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>]</command> as an element in a mathematical expression. For example:</para>-->
111 <indexterm>
112 <primary>reading values from arrays</primary>
113 <secondary>array operations</secondary>
114 <tertiary>using arrays in simple computations</tertiary>
115 </indexterm>
116
117 <indexterm>
118 <primary>array operations</primary>
119 <secondary>reading values from arrays</secondary>
120 <tertiary>using arrays in simple computations</tertiary>
121 </indexterm>
122
123 <indexterm>
124 <primary>operations</primary>
125 <secondary>reading values from arrays</secondary>
126 <tertiary>using arrays in simple computations</tertiary>
127 </indexterm>
128
129 <indexterm>
130 <primary>using arrays in simple computations</primary>
131 <secondary>reading values from arrays</secondary>
132 <tertiary>array operations</tertiary>
133 </indexterm>
134
135 <indexterm>
136 <primary>algebraic formulas using arrays</primary>
137 <secondary>reading values from arrays</secondary>
138 <tertiary>array operations</tertiary>
139 </indexterm>
140
141 <indexterm>
142 <primary>array operations</primary>
143 <secondary>reading values from arrays</secondary>
144 <tertiary>computing for timestamp deltas</tertiary>
145 </indexterm>
146
147 <indexterm>
148 <primary>operations</primary>
149 <secondary>reading values from arrays</secondary>
150 <tertiary>computing for timestamp deltas</tertiary>
151 </indexterm>
152
153 <indexterm>
154 <primary>computing for timestamp deltas</primary>
155 <secondary>reading values from arrays</secondary>
156 <tertiary>array operations</tertiary>
157 </indexterm>
158
159 <indexterm>
160 <primary>reading values from arrays</primary>
161 <secondary>computing for timestamp deltas</secondary>
162 <tertiary>array operations</tertiary>
163 </indexterm>
164 <indexterm>
165 <primary>timestamp deltas, computing for</primary>
166 <secondary>reading values from arrays</secondary>
167 <tertiary>array operations</tertiary>
168 </indexterm>
169 <example id="arrayreadingvaluesfrom">
170 <title>Using Array Values in Simple Computations</title>
171 <screen>delta = gettimeofday_s() - foo[tid()]</screen>
172 </example>
173
174 <para>
175 This example assumes that the array <command>foo</command> was built using the construct in
176 <xref linkend="arrays-timestampprocessname"/> (from <xref linkend="arrayops-assignvalue"/>). This
177 sets a timestamp that will serve as a <emphasis>reference point</emphasis>, to be used in
178 computing for <literal>delta</literal>.
179 </para>
180
181 <para>
182 The construct in <xref linkend="arrayreadingvaluesfrom"/> computes a value for the variable
183 <literal>delta</literal> by subtracting the associated value of the key <literal>tid()</literal>
184 from the current <command>gettimeofday_s()</command>. The construct does this by
185 <emphasis>reading</emphasis> the value of <literal>tid()</literal> from the array. This particular
186 construct is useful for determining the time between two events, such as the start and completion
187 of a read operation.
188 </para>
189 <!--
190
191 <para>
192 In <xref linkend="arrayreadingvaluesfrom"/>, the first statement sets a timestamp associated
193 with the returned value of the handler function <command>tid()</command> as a
194 <emphasis>reference point</emphasis>.
195 The second statement computes a value for the variable
196 <command>delta</command> by subtracting the associated value the reference point from the
197 current <command>gettimeofday_s()</command>. Note that the first statement writes the value
198 of <command>gettimeofday_s()</command> into the appropriate key of array
199 <literal>foo</literal>, while in the second statement the value of
200 <command>foo[tid()]</command> is <emphasis>read</emphasis> from the array in order to compute
201 for <literal>delta</literal>.
202 </para>
203 -->
204
205 <indexterm>
206 <primary>reading values from arrays</primary>
207 <secondary>array operations</secondary>
208 <tertiary>empty unique keys</tertiary>
209 </indexterm>
210
211 <indexterm>
212 <primary>array operations</primary>
213 <secondary>reading values from arrays</secondary>
214 <tertiary>empty unique keys</tertiary>
215 </indexterm>
216
217 <indexterm>
218 <primary>operations</primary>
219 <secondary>reading values from arrays</secondary>
220 <tertiary>empty unique keys</tertiary>
221 </indexterm>
222
223 <indexterm>
224 <primary>empty unique keys</primary>
225 <secondary>reading values from arrays</secondary>
226 <tertiary>array operations</tertiary>
227 </indexterm>
228 <note>
229 <title>Note</title>
230 <para>
231 If the <command><replaceable>index_expression</replaceable></command> cannot
232 find the unique key, it returns a value of 0 (for numerical operations, such as
233 <xref linkend="arrayreadingvaluesfrom"/>) or a null/empty string value (for string operations) by
234 default.
235 </para>
236 </note>
237 </section>
238 <section id="arrayops-increment">
239 <title>Incrementing Associated Values</title>
240 <indexterm>
241 <primary>array operations</primary>
242 <secondary>incrementing associated values</secondary>
243 </indexterm>
244
245 <indexterm>
246 <primary>incrementing associated values</primary>
247 <secondary>array operations</secondary>
248 </indexterm>
249
250 <indexterm>
251 <primary>operations</primary>
252 <secondary>incrementing associated values</secondary>
253 </indexterm>
254 <para>Use <command>++</command> to increment the associated value of a unique key in an array, as in:</para>
255
256 <screen><replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>] ++</screen>
257
258 <para>Again, you can also use a handler function for your <command><replaceable>index_expression</replaceable></command>. For example, if you wanted to tally how many times a specific process performed a read to the virtual file system (using the event <command>vfs.read</command>), you can use the following probe:</para>
259
260 <!-- next 3 indexterms for tallying virtual file system reads (VFS reads) -->
261
262 <indexterm>
263 <primary>incrementing associated values</primary>
264 <secondary>array operations</secondary>
265 <tertiary>tallying virtual file system reads (VFS reads)</tertiary>
266 </indexterm>
267
268 <indexterm>
269 <primary>array operations</primary>
270 <secondary>incrementing associated values</secondary>
271 <tertiary>tallying virtual file system reads (VFS reads)</tertiary>
272 </indexterm>
273
274 <indexterm>
275 <primary>operations</primary>
276 <secondary>incrementing associated values</secondary>
277 <tertiary>tallying virtual file system reads (VFS reads)</tertiary>
278 </indexterm>
279
280 <indexterm>
281 <primary>tallying virtual file system reads (VFS reads)</primary>
282 <secondary>incrementing associated values</secondary>
283 <tertiary>array operations</tertiary>
284 </indexterm>
285
286 <indexterm>
287 <primary>VFS reads, tallying of</primary>
288 <secondary>incrementing associated values</secondary>
289 <tertiary>array operations</tertiary>
290 </indexterm>
291 <example id="simplesimplevfsread">
292 <title>vfsreads.stp</title>
293 <programlisting>probe vfs.read
294 {
295 reads[execname()] ++
296 }</programlisting>
297 </example>
298
299 <para>In <xref linkend="simplesimplevfsread"/>, 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 the unique key <literal>gnome-terminal</literal> with an associated value of 1. The next time that the probe returns the process name <command>gnome-terminal</command>, SystemTap increments the associated value of <literal>gnome-terminal</literal> by 1. SystemTap performs this operation for <emphasis>all</emphasis> process names as the probe returns them.</para>
300 </section>
301
302 <section id="arrayops-foreach">
303 <title>Processing Multiple Elements in an Array</title>
304 <indexterm>
305 <primary>multiple elements in an array</primary>
306 <secondary>array operations</secondary>
307 </indexterm>
308
309 <indexterm>
310 <primary>array operations</primary>
311 <secondary>multiple elements in an array</secondary>
312 </indexterm>
313
314 <indexterm>
315 <primary>operations</primary>
316 <secondary>multiple elements in an array</secondary>
317 </indexterm>
318
319 <indexterm>
320 <primary>array operations</primary>
321 <secondary>processing multiple elements in an array</secondary>
322 </indexterm>
323
324 <indexterm>
325 <primary>processing multiple elements in an array</primary>
326 <secondary>array operations</secondary>
327 </indexterm>
328
329 <indexterm>
330 <primary>operations</primary>
331 <secondary>processing multiple elements in an array</secondary>
332 </indexterm>
333 <!-- <title>Processing Elements in a Tuple as Iterations</title> -->
334 <para>Once you've collected enough information in an array, you will need to retrieve and process all elements in that array to make it useful. Consider <xref linkend="simplesimplevfsread"/>: the script collects information about how many VFS reads each process performs, but does not specify what to do with it. The obvious means for making <xref linkend="simplesimplevfsread"/> useful is to print the key pairs in the array <command>reads</command>, but how?</para>
335
336 <!-- next 3 indexterms for foreach -->
337 <indexterm>
338 <primary>array operations</primary>
339 <secondary>processing multiple elements in an array</secondary>
340 <tertiary>foreach</tertiary>
341 </indexterm>
342
343 <indexterm>
344 <primary>operations</primary>
345 <secondary>processing multiple elements in an array</secondary>
346 <tertiary>foreach</tertiary>
347 </indexterm>
348
349 <indexterm>
350 <primary>processing multiple elements in an array</primary>
351 <secondary>foreach</secondary>
352 <tertiary>array operations</tertiary>
353 </indexterm>
354
355 <indexterm>
356 <primary>foreach</primary>
357 <secondary>processing multiple elements in an array</secondary>
358 <tertiary>array operations</tertiary>
359 </indexterm>
360
361
362
363 <!-- next 2 indexterms for iterations, processing elements in an array as -->
364
365 <indexterm>
366 <primary>array operations</primary>
367 <secondary>processing multiple elements in an array</secondary>
368 <tertiary>iterations, processing elements in an array as</tertiary>
369 </indexterm>
370
371 <indexterm>
372 <primary>operations</primary>
373 <secondary>processing multiple elements in an array</secondary>
374 <tertiary>iterations, processing elements in an array as</tertiary>
375 </indexterm>
376
377 <indexterm>
378 <primary>iterations, processing elements in an array as</primary>
379 <secondary>processing multiple elements in an array</secondary>
380 <tertiary>array operations</tertiary>
381 </indexterm>
382 <para>The best way to process all key pairs in an array (as an iteration) is to use the <command>foreach</command> statement. Consider the following example:</para>
383 <!-- <para>The best way to process all elements in a tuple (treating each element as an iteration) is to use the <command>foreach</command> statement. Consider the following example:</para>-->
384
385
386 <!-- next 2 indexterms for cumulative virtual file system reads, tallying -->
387
388 <indexterm>
389 <primary>array operations</primary>
390 <secondary>processing multiple elements in an array</secondary>
391 <tertiary>cumulative virtual file system reads, tallying</tertiary>
392 </indexterm>
393
394 <indexterm>
395 <primary>operations</primary>
396 <secondary>processing multiple elements in an array</secondary>
397 <tertiary>cumulative virtual file system reads, tallying</tertiary>
398 </indexterm>
399
400 <indexterm>
401 <primary>cumulative virtual file system reads, tallying</primary>
402 <secondary>processing multiple elements in an array</secondary>
403 <tertiary>array operations</tertiary>
404 </indexterm>
405
406 <indexterm>
407 <primary>processing multiple elements in an array</primary>
408 <secondary>cumulative virtual file system reads, tallying</secondary>
409 <tertiary>array operations</tertiary>
410 </indexterm>
411
412 <indexterm>
413 <primary>virtual file system reads (cumulative), tallying</primary>
414 <secondary>processing multiple elements in an array</secondary>
415 <tertiary>array operations</tertiary>
416 </indexterm>
417 <example id="simplevfsreadprint">
418 <title>cumulative-vfsreads.stp</title>
419 <programlisting>global reads
420 probe vfs.read
421 {
422 reads[execname()] ++
423 }
424 probe timer.s(3)
425 {
426 foreach (count in reads)
427 printf("%s : %d \n", count, reads[count])
428 }</programlisting>
429 </example>
430
431 <para>In the second probe of <xref linkend="simplevfsreadprint"/>, the <command>foreach</command> statement uses the variable <command>count</command> to reference each iteration of a unique key in the array <command>reads</command>. The <command>reads[count]</command> array statement in the same probe retrieves the associated value of each unique key.</para>
432
433 <para>Given what we know about the first probe in <xref linkend="simplevfsreadprint"/>, the script prints VFS-read statistics every 3 seconds, displaying names of processes that performed a VFS-read along with a corresponding VFS-read count.</para>
434 <indexterm>
435 <primary>array operations</primary>
436 <secondary>processing multiple elements in an array</secondary>
437 <tertiary>limiting the output of foreach</tertiary>
438 </indexterm>
439
440 <indexterm>
441 <primary>operations</primary>
442 <secondary>processing multiple elements in an array</secondary>
443 <tertiary>limiting the output of foreach</tertiary>
444 </indexterm>
445
446 <indexterm>
447 <primary>processing multiple elements in an array</primary>
448 <secondary>limiting the output of foreach</secondary>
449 <tertiary>array operations</tertiary>
450 </indexterm>
451
452 <indexterm>
453 <primary>limiting the output of foreach</primary>
454 <secondary>processing multiple elements in an array</secondary>
455 <tertiary>array operations</tertiary>
456 </indexterm>
457
458 <!-- next 2 indexterms for ordering the output of foreach -->
459
460 <indexterm>
461 <primary>array operations</primary>
462 <secondary>processing multiple elements in an array</secondary>
463 <tertiary>ordering the output of foreach</tertiary>
464 </indexterm>
465
466 <indexterm>
467 <primary>operations</primary>
468 <secondary>processing multiple elements in an array</secondary>
469 <tertiary>ordering the output of foreach</tertiary>
470 </indexterm>
471
472 <indexterm>
473 <primary>processing multiple elements in an array</primary>
474 <secondary>ordering the output of foreach</secondary>
475 <tertiary>array operations</tertiary>
476 </indexterm>
477
478 <indexterm>
479 <primary>ordering the output of foreach</primary>
480 <secondary>processing multiple elements in an array</secondary>
481 <tertiary>array operations</tertiary>
482 </indexterm>
483
484
485 <para>Now, remember that the <command>foreach</command> statement in <xref linkend="simplevfsreadprint"/> prints <emphasis>all</emphasis> iterations of process names in the array, and in no particular order. You can instruct the script to process the iterations in a particular order by using <command>+</command> (ascending) or <command>-</command> (descending). In addition, you can also limit the number of iterations the script needs to process with the <command>limit <replaceable>value</replaceable></command> option.</para>
486
487 <para>For example, consider the following replacement probe:</para>
488 <screen>probe timer.s(3)
489 {
490 foreach (count in reads- limit 10)
491 printf("%s : %d \n", count, reads[count])
492 }</screen>
493
494 <para>This <command>foreach</command> statement instructs the script to process the elements in the array <command>reads</command> in descending order (of associated value). The <command>limit 10</command> option instructs the <command>foreach</command> to only process the first ten iterations (that is, print the first 10, starting with the highest value).</para>
495 </section>
496
497 <section id="arrayops-deleting">
498 <title>Clearing/Deleting Arrays and Array Elements</title>
499 <indexterm>
500 <primary>array operations</primary>
501 <secondary>deleting arrays and array elements</secondary>
502 </indexterm>
503
504 <indexterm>
505 <primary>operations</primary>
506 <secondary>deleting arrays and array elements</secondary>
507 </indexterm>
508
509 <indexterm>
510 <primary>array operations</primary>
511 <secondary>clearing arrays/array elements</secondary>
512 </indexterm>
513
514 <indexterm>
515 <primary>operations</primary>
516 <secondary>clearing arrays/array elements</secondary>
517 </indexterm>
518
519 <indexterm>
520 <primary>clearing arrays/array elements</primary>
521 <secondary>array operations</secondary>
522 </indexterm>
523 <para>Sometimes, you may need to clear the associated values in array elements, or reset an entire array for re-use in another probe. <xref linkend="simplevfsreadprint"/> in <xref linkend="arrayops-foreach"/> allows you to track how the number of VFS reads per process grows over time, but it does not show you the number of VFS reads each process makes per 3-second period.</para>
524
525 <!-- next 3 indexterms for delete operator -->
526 <indexterm>
527 <primary>array operations</primary>
528 <secondary>clearing arrays/array elements</secondary>
529 <tertiary>delete operator</tertiary>
530 </indexterm>
531
532 <indexterm>
533 <primary>operations</primary>
534 <secondary>clearing arrays/array elements</secondary>
535 <tertiary>delete operator</tertiary>
536 </indexterm>
537
538 <indexterm>
539 <primary>clearing arrays/array elements</primary>
540 <secondary>array operations</secondary>
541 <tertiary>delete operator</tertiary>
542 </indexterm>
543
544 <indexterm>
545 <primary>delete operator</primary>
546 <secondary>clearing arrays/array elements</secondary>
547 <tertiary>array operations</tertiary>
548 </indexterm>
549 <para>To do that, you will need to clear the values accumulated by the array. You can accomplish this using the <command>delete</command> operator to delete elements in an array, or an entire array. Consider the following example:</para>
550
551 <indexterm>
552 <primary>array operations</primary>
553 <secondary>clearing arrays/array elements</secondary>
554 <tertiary>virtual file system reads (non-cumulative), tallying</tertiary>
555 </indexterm>
556
557 <indexterm>
558 <primary>operations</primary>
559 <secondary>clearing arrays/array elements</secondary>
560 <tertiary>virtual file system reads (non-cumulative), tallying</tertiary>
561 </indexterm>
562
563 <indexterm>
564 <primary>clearing arrays/array elements</primary>
565 <secondary>array operations</secondary>
566 <tertiary>virtual file system reads (non-cumulative), tallying</tertiary>
567 </indexterm>
568
569 <indexterm>
570 <primary>virtual file system reads (non-cumulative), tallying</primary>
571 <secondary>clearing arrays/array elements</secondary>
572 <tertiary>array operations</tertiary>
573 </indexterm>
574 <example id="simplevfsreadprintnotcumulative">
575 <title>noncumulative-vfsreads.stp</title>
576 <programlisting>global reads
577 probe vfs.read
578 {
579 reads[execname()] ++
580 }
581 probe timer.s(3)
582 {
583 foreach (count in reads)
584 printf("%s : %d \n", count, reads[count])
585 delete reads
586 }</programlisting>
587 </example>
588 <!--
589 <example id="simplevfsreadprintnotcumulative">
590 <title>vfsreads-per-2secs.stp</title>
591 <programlisting>global reads
592 probe vfs.read
593 {
594 reads[execname()] ++
595 }
596
597 probe timer.s(3)
598 {
599 printf("=======\n")
600 foreach (count in reads+)
601 printf("%s : %d \n", count, reads[count])
602 delete reads
603 }</programlisting>
604 </example>-->
605
606 <para>In <xref linkend="simplevfsreadprintnotcumulative"/>, the second probe prints the number of VFS reads each process made <emphasis>within the probed 3-second period only</emphasis>. The <command>delete reads</command> statement clears the <command>reads</command> array within the probe.</para>
607
608 <note>
609 <title>Note</title>
610
611 <!-- next 2 indexterms for multiple array operations within the same probe -->
612
613 <indexterm>
614 <primary>array operations</primary>
615 <secondary>clearing arrays/array elements</secondary>
616 <tertiary>multiple array operations within the same probe</tertiary>
617 </indexterm>
618
619 <indexterm>
620 <primary>operations</primary>
621 <secondary>clearing arrays/array elements</secondary>
622 <tertiary>multiple array operations within the same probe</tertiary>
623 </indexterm>
624
625 <indexterm>
626 <primary>clearing arrays/array elements</primary>
627 <secondary>array operations</secondary>
628 <tertiary>multiple array operations within the same probe</tertiary>
629 </indexterm>
630
631 <indexterm>
632 <primary>multiple array operations within the same probe</primary>
633 <secondary>clearing arrays/array elements</secondary>
634 <tertiary>array operations</tertiary>
635 </indexterm>
636 <para>You can have multiple array operations within the same probe. Using the examples from <xref linkend="arrayops-foreach"/> and <xref linkend="arrayops-deleting"/> , you can track the number of VFS reads each process makes per 3-second period <emphasis>and</emphasis> tally the cumulative VFS reads of those same processes. Consider the following example:</para>
637
638 <screen>global reads, totalreads
639
640 probe vfs.read
641 {
642 reads[execname()] ++
643 totalreads[execname()] ++
644 }
645
646 probe timer.s(3)
647 {
648 printf("=======\n")
649 foreach (count in reads-)
650 printf("%s : %d \n", count, reads[count])
651 delete reads
652 }
653
654 probe end
655 {
656 printf("TOTALS\n")
657 foreach (total in totalreads-)
658 printf("%s : %d \n", total, totalreads[total])
659 }</screen>
660
661 <para>In this example, the arrays <command>reads</command> and <command>totalreads</command> track the same information, and are printed out in a similar fashion. The only difference here is that <command>reads</command> is cleared every 3-second period, whereas <command>totalreads</command> keeps growing.</para>
662 </note>
663 </section>
664 <section id="arrayops-conditionals">
665 <title>Using Arrays in Conditional Statements</title>
666 <indexterm>
667 <primary>array operations</primary>
668 <secondary>conditional statements, using arrays in</secondary>
669 </indexterm>
670
671 <indexterm>
672 <primary>operations</primary>
673 <secondary>conditional statements, using arrays in</secondary>
674 </indexterm>
675
676 <indexterm>
677 <primary>conditional statements, using arrays in</primary>
678 <secondary>array operations</secondary>
679 </indexterm>
680
681 <indexterm>
682 <primary>if/else statements, using arrays in</primary>
683 <secondary>array operations</secondary>
684 </indexterm>
685
686 <para>You can also use associative arrays in <command>if</command> statements. This is useful if you want to execute a subroutine once a value in the array matches a certain condition. Consider the following example:</para>
687
688 <example id="simplevfsreadprintif">
689 <title>vfsreads-print-if-1kb.stp</title>
690 <programlisting>global reads
691 probe vfs.read
692 {
693 reads[execname()] ++
694 }
695
696 probe timer.s(3)
697 {
698 printf("=======\n")
699 foreach (count in reads-)
700 if (reads[count] >= 1024)
701 printf("%s : %dkB \n", count, reads[count]/1024)
702 else
703 printf("%s : %dB \n", count, reads[count])
704 }</programlisting>
705 </example>
706
707 <para>Every three seconds, <xref linkend="simplevfsreadprintif"/> prints out a list of all processes, along with how many times each process performed a VFS read. If the associated value of a process name is equal or greater than 1024, the <command>if</command> statement in the script converts and prints it out in <command>kB</command>.</para>
708 <!-- <title>vfsreads-stop-on-stapio.stp</title>
709 <programlisting>global reads
710 probe kernel.function("vfs_read")
711 {
712 reads[execname()] ++
713 }
714
715 probe timer.s(3)
716 {
717 printf("=======\n")
718 foreach (count in reads+)
719 printf("%s : %d \n", count, reads[count])
720 if(reads["stapio"] >= 20) {
721 exit()
722 }
723 }</programlisting>
724 </example>
725
726 <para>The <command>if(reads["stapio"] >= 20)</command> instructs the script to execute the subroutine <command>exit()</command> once the value associated with the unique key <command>stapio</command> (in the array <command>reads</command>) is greater than or equal to 20.</para>
727 -->
728 <formalpara>
729 <title>Testing for Membership</title>
730
731 <!-- next 3 indexterms for testing for array membership -->
732 <indexterm>
733 <primary>array operations</primary>
734 <secondary>conditional statements, using arrays in</secondary>
735 <tertiary>testing for array membership</tertiary>
736 </indexterm>
737
738 <indexterm>
739 <primary>operations</primary>
740 <secondary>conditional statements, using arrays in</secondary>
741 <tertiary>testing for array membership</tertiary>
742 </indexterm>
743
744 <indexterm>
745 <primary>conditional statements, using arrays in</primary>
746 <secondary>array operations</secondary>
747 <tertiary>testing for array membership</tertiary>
748 </indexterm>
749
750 <indexterm>
751 <primary>testing for array membership</primary>
752 <secondary>conditional statements, using arrays in</secondary>
753 <tertiary>array operations</tertiary>
754 </indexterm>
755
756 <indexterm>
757 <primary>membership (in array), testing for</primary>
758 <secondary>conditional statements, using arrays in</secondary>
759 <tertiary>array operations</tertiary>
760 </indexterm>
761
762
763 <para>You can also test whether a specific unique key is a member of an array. Further, membership in an array can be used in <command>if</command> statements, as in:</para>
764 </formalpara>
765
766 <screen>if([<replaceable>index_expression</replaceable>] in <replaceable>array_name</replaceable>) <replaceable>statement</replaceable></screen>
767
768 <para>To illustrate this, consider the following example:</para>
769
770 <example id="simplesimplevfsreadprintifmember">
771 <title>vfsreads-stop-on-stapio2.stp</title>
772 <programlisting>global reads
773
774 probe vfs.read
775 {
776 reads[execname()] ++
777 }
778
779 probe timer.s(3)
780 {
781 printf("=======\n")
782 foreach (count in reads+)
783 printf("%s : %d \n", count, reads[count])
784 if(["stapio"] in reads) {
785 printf("stapio read detected, exiting\n")
786 exit()
787 }
788 }</programlisting>
789 </example>
790
791 <para>The <command>if(["stapio"] in reads)</command> statement instructs the script to print <computeroutput>stapio read detected, exiting</computeroutput> once the unique key <command>stapio</command> is added to the array <command>reads</command>.</para>
792 </section>
793
794 <section id="arrayops-aggregates">
795 <title>Computing for Statistical Aggregates</title>
796 <indexterm>
797 <primary>statistical aggregates</primary>
798 <secondary>array operations</secondary>
799 </indexterm>
800 <indexterm>
801 <primary>aggregates (statistical)</primary>
802 <secondary>array operations</secondary>
803 </indexterm>
804
805 <indexterm>
806 <primary>array operations</primary>
807 <secondary>computing for statistical aggregates</secondary>
808 </indexterm>
809
810 <indexterm>
811 <primary>operations</primary>
812 <secondary>computing for statistical aggregates</secondary>
813 </indexterm>
814
815 <indexterm>
816 <primary>computing for statistical aggregates</primary>
817 <secondary>array operations</secondary>
818 </indexterm>
819 <para>Statistical aggregates are used to collect statistics on numerical values where it is important to accumulate new data quickly and in large volume (that is, storing only aggregated stream statistics). Statistical aggregates can be used in global variables or as elements in an array.</para>
820 <!-- next 3 indexterms for adding values to statistical aggregatest -->
821 <indexterm>
822 <primary>array operations</primary>
823 <secondary>computing for statistical aggregates</secondary>
824 <tertiary>adding values to statistical aggregates</tertiary>
825 </indexterm>
826
827 <indexterm>
828 <primary>operations</primary>
829 <secondary>computing for statistical aggregates</secondary>
830 <tertiary>adding values to statistical aggregates</tertiary>
831 </indexterm>
832
833 <indexterm>
834 <primary>computing for statistical aggregates</primary>
835 <secondary>array operations</secondary>
836 <tertiary>adding values to statistical aggregates</tertiary>
837 </indexterm>
838
839 <indexterm>
840 <primary>adding values to statistical aggregates</primary>
841 <secondary>computing for statistical aggregates</secondary>
842 <tertiary>array operations</tertiary>
843 </indexterm>
844
845 <para>To add value to a statistical aggregate, use the operator <command>&lt;&lt;&lt; <replaceable>value</replaceable></command>.</para>
846
847 <remark>need more examples of supported rvalues, for example, length, count, and what each one does.</remark>
848
849 <example id="simpleaggregates">
850 <title>stat-aggregates.stp</title>
851 <programlisting>global reads
852 probe vfs.read
853 {
854 reads[execname()] &lt;&lt;&lt; $count
855 }</programlisting>
856 </example>
857
858 <!-- next 2 indexterms for count operator -->
859
860 <indexterm>
861 <primary>array operations</primary>
862 <secondary>computing for statistical aggregates</secondary>
863 <tertiary>count (operator)</tertiary>
864 </indexterm>
865
866 <indexterm>
867 <primary>operations</primary>
868 <secondary>computing for statistical aggregates</secondary>
869 <tertiary>count (operator)</tertiary>
870 </indexterm>
871
872 <indexterm>
873 <primary>computing for statistical aggregates</primary>
874 <secondary>array operations</secondary>
875 <tertiary>count (operator)</tertiary>
876 </indexterm>
877
878 <indexterm>
879 <primary>count operator</primary>
880 <secondary>computing for statistical aggregates</secondary>
881 <tertiary>array (operator)</tertiary>
882 </indexterm>
883
884 <para>In <xref linkend="simpleaggregates"/>, the operator <command>&lt;&lt;&lt; $count</command> <emphasis>stores</emphasis> the amount returned by <literal>$count</literal> to the associated value of the corresponding <command>execname()</command> in the <literal>reads</literal> array. Remember, these values are <emphasis>stored</emphasis>; they are not added to the associated values of each unique key, nor are they used to replace the current associated values. In a manner of speaking, think of it as having each unique key (<command>execname()</command>) having multiple associated values, accumulating with each probe handler run.</para>
885
886 <note>
887 <title>Note</title>
888 <para>In the context of <xref linkend="simpleaggregates"/>, <literal>count</literal> returns the amount of data read by the returned <command>execname()</command> to the virtual file system.</para>
889 </note>
890
891
892 <!-- next 2 indexterms for extracting data collected by statistical aggregates -->
893
894 <indexterm>
895 <primary>array operations</primary>
896 <secondary>computing for statistical aggregates</secondary>
897 <tertiary>extracting data collected by statistical aggregates</tertiary>
898 </indexterm>
899
900 <indexterm>
901 <primary>operations</primary>
902 <secondary>computing for statistical aggregates</secondary>
903 <tertiary>extracting data collected by statistical aggregates</tertiary>
904 </indexterm>
905
906 <indexterm>
907 <primary>computing for statistical aggregates</primary>
908 <secondary>array operations</secondary>
909 <tertiary>extracting data collected by statistical aggregates</tertiary>
910 </indexterm>
911
912 <indexterm>
913 <primary>extracting data collected by statistical aggregates</primary>
914 <secondary>computing for statistical aggregates</secondary>
915 <tertiary>array operations</tertiary>
916 </indexterm>
917
918 <indexterm>
919 <primary>integer extractors</primary>
920 <secondary>computing for statistical aggregates</secondary>
921 <tertiary>array operations</tertiary>
922 </indexterm>
923
924
925 <para>To extract data collected by statistical aggregates, use the syntax format <command>@<replaceable>extractor</replaceable>(<replaceable>variable/array index expression</replaceable>)</command>. <command><replaceable>extractor</replaceable></command> can be any of the following integer extractors:</para>
926
927 <variablelist>
928
929 <varlistentry>
930 <term>count</term>
931 <listitem>
932 <indexterm>
933 <primary>array operations</primary>
934 <secondary>computing for statistical aggregates</secondary>
935 <tertiary>@count (integer extractor)</tertiary>
936 </indexterm>
937
938 <indexterm>
939 <primary>operations</primary>
940 <secondary>computing for statistical aggregates</secondary>
941 <tertiary>@count (integer extractor)</tertiary>
942 </indexterm>
943
944 <indexterm>
945 <primary>computing for statistical aggregates</primary>
946 <secondary>array operations</secondary>
947 <tertiary>@count (integer extractor)</tertiary>
948 </indexterm>
949
950 <indexterm>
951 <primary>@count (integer extractor)</primary>
952 <secondary>computing for statistical aggregates</secondary>
953 <tertiary>array operations</tertiary>
954 </indexterm>
955 <para>
956 Returns the number of all values stored into the variable/array index expression. Given the sample probe in <xref linkend="simpleaggregates"/>, the expression <command>@count(reads[execname()])</command> will return <emphasis>how many values are stored</emphasis> in each unique key in array <literal>reads</literal>.
957 </para>
958 </listitem>
959 </varlistentry>
960
961 <varlistentry>
962 <term>sum</term>
963 <listitem>
964
965 <!-- next 2 indexterms for sum (integer extractor) -->
966
967 <indexterm>
968 <primary>array operations</primary>
969 <secondary>computing for statistical aggregates</secondary>
970 <tertiary>@sum (integer extractor)</tertiary>
971 </indexterm>
972
973 <indexterm>
974 <primary>operations</primary>
975 <secondary>computing for statistical aggregates</secondary>
976 <tertiary>@sum (integer extractor)</tertiary>
977 </indexterm>
978
979 <indexterm>
980 <primary>computing for statistical aggregates</primary>
981 <secondary>array operations</secondary>
982 <tertiary>@sum (integer extractor)</tertiary>
983 </indexterm>
984
985 <indexterm>
986 <primary>@sum (integer extractor)</primary>
987 <secondary>computing for statistical aggregates</secondary>
988 <tertiary>array operations</tertiary>
989 </indexterm>
990
991 <para>
992 Returns the sum of all values stored into the variable/array index expression. Again, given sample probe in <xref linkend="simpleaggregates"/>, the expression <command>@sum(reads[execname()])</command> will return <emphasis>the total of all values stored</emphasis> in each unique key in array <literal>reads</literal>.
993 </para>
994 </listitem>
995 </varlistentry>
996
997 <varlistentry>
998 <term>min</term>
999 <listitem>
1000
1001 <!-- next 2 indexterms for min (integer extractor) -->
1002
1003 <indexterm>
1004 <primary>array operations</primary>
1005 <secondary>computing for statistical aggregates</secondary>
1006 <tertiary>@min (integer extractor)</tertiary>
1007 </indexterm>
1008
1009 <indexterm>
1010 <primary>operations</primary>
1011 <secondary>computing for statistical aggregates</secondary>
1012 <tertiary>@min (integer extractor)</tertiary>
1013 </indexterm>
1014
1015 <indexterm>
1016 <primary>computing for statistical aggregates</primary>
1017 <secondary>array operations</secondary>
1018 <tertiary>@min (integer extractor)</tertiary>
1019 </indexterm>
1020
1021 <indexterm>
1022 <primary>@min (integer extractor)</primary>
1023 <secondary>computing for statistical aggregates</secondary>
1024 <tertiary>array operations</tertiary>
1025 </indexterm>
1026
1027 <para>
1028 Returns the smallest among all the values stored in the variable/array index expression.
1029 </para>
1030 </listitem>
1031 </varlistentry>
1032
1033 <varlistentry>
1034 <term>max</term>
1035 <listitem>
1036
1037 <!-- next 2 indexterms for max (integer extractor) -->
1038
1039 <indexterm>
1040 <primary>array operations</primary>
1041 <secondary>computing for statistical aggregates</secondary>
1042 <tertiary>@max (integer extractor)</tertiary>
1043 </indexterm>
1044
1045 <indexterm>
1046 <primary>operations</primary>
1047 <secondary>computing for statistical aggregates</secondary>
1048 <tertiary>@max (integer extractor)</tertiary>
1049 </indexterm>
1050
1051 <indexterm>
1052 <primary>computing for statistical aggregates</primary>
1053 <secondary>array operations</secondary>
1054 <tertiary>@max (integer extractor)</tertiary>
1055 </indexterm>
1056
1057 <indexterm>
1058 <primary>@max (integer extractor)</primary>
1059 <secondary>computing for statistical aggregates</secondary>
1060 <tertiary>array operations</tertiary>
1061 </indexterm>
1062
1063 <para>
1064 Returns the largest among all the values stored in the variable/array index expression.
1065 </para>
1066 </listitem>
1067 </varlistentry>
1068
1069 <varlistentry>
1070 <term>avg</term>
1071 <listitem>
1072
1073 <!-- next 2 indexterms for avg (integer extractor) -->
1074
1075 <indexterm>
1076 <primary>array operations</primary>
1077 <secondary>computing for statistical aggregates</secondary>
1078 <tertiary>@avg (integer extractor)</tertiary>
1079 </indexterm>
1080
1081 <indexterm>
1082 <primary>operations</primary>
1083 <secondary>computing for statistical aggregates</secondary>
1084 <tertiary>@avg (integer extractor)</tertiary>
1085 </indexterm>
1086
1087 <indexterm>
1088 <primary>computing for statistical aggregates</primary>
1089 <secondary>array operations</secondary>
1090 <tertiary>@avg (integer extractor)</tertiary>
1091 </indexterm>
1092
1093 <indexterm>
1094 <primary>@avg (integer extractor)</primary>
1095 <secondary>computing for statistical aggregates</secondary>
1096 <tertiary>array operations</tertiary>
1097 </indexterm>
1098
1099
1100 <para>
1101 Returns the average of all values stored in the variable/array index expression.
1102 </para>
1103 </listitem>
1104 </varlistentry>
1105
1106
1107
1108 <!--
1109 <varlistentry>
1110 <term></term>
1111 <listitem>
1112 <para>
1113 </para>
1114 </listitem>
1115 </varlistentry>
1116 -->
1117
1118 </variablelist>
1119
1120 <para>
1121 When using statistical aggregates, you can also build array constructs that use multiple index
1122 expressions (to a maximum of 5). This is helpful in capturing additional contextual information
1123 during a probe. For example:
1124 </para>
1125
1126 <example id="multiplearrayindices">
1127 <title>Multiple Array Indexes</title>
1128 <programlisting>global reads
1129 probe vfs.read
1130 {
1131 reads[execname(),pid()] &lt;&lt;&lt; 1
1132 }
1133 probe timer.s(3)
1134 {
1135 foreach([var1,var2] in reads)
1136 printf("%s (%d) : %d \n", var1, var2, @count(reads[var1,var2]))
1137 }</programlisting>
1138 </example>
1139
1140 <para>
1141 In <xref linkend="multiplearrayindices"/>, the first probe tracks how many times each process
1142 performs a VFS read. What makes this different from earlier examples is that this array associates
1143 a performed read to both a process name <emphasis>and</emphasis> its corresponding process ID.
1144 </para>
1145
1146 <para>
1147 The second probe in <xref linkend="multiplearrayindices"/> demonstrates how to process and print
1148 the information collected by the array <literal>reads</literal>. Note how the
1149 <command>foreach</command> statement uses the same number of variables (that is,
1150 <literal>var1</literal> and <literal>var2</literal>) contained in the first instance of the array
1151 <literal>reads</literal> from the first probe.
1152 </para>
1153
1154
1155 </section>
1156
1157 </section>