From f02d561e798f1c599c4c622983946a6e6fb53395 Mon Sep 17 00:00:00 2001
From: ddomingo <ddomingo@redhat.com>
Date: Tue, 9 Dec 2008 15:14:40 +1000
Subject: revised discussion on multiple index expressions

---
 .../en-US/Array-Operations.xml                     | 38 ++++++++++++++++++++++
 doc/SystemTap_Beginners_Guide/en-US/Arrays.xml     |  4 +--
 2 files changed, 40 insertions(+), 2 deletions(-)

(limited to 'doc/SystemTap_Beginners_Guide')

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
index 987e2b29..8fe46721 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Array-Operations.xml
@@ -1148,6 +1148,44 @@ reads[execname()] &lt;&lt;&lt; count
 -->
 
 </variablelist>
+
+<para>
+	When using statistical aggregates, you can also build array constructs that use multiple index 
+	expressions (to a maximum of 5). This is helpful in capturing additional contextual information 
+	during a probe. For example:
+</para>
+
+<example id="multiplearrayindices">
+	<title>Multiple Array Indexes</title>
+<programlisting>
+global reads
+probe vfs.read
+{
+reads[execname(),pid()] &lt;&lt;&lt; 1
+}
+probe timer.s(3)
+{
+foreach([var1,var2] in reads)
+	printf("%s (%d) : %d \n", var1, var2, @count(reads[var1,var2]))
+}	
+</programlisting>
+</example>
+
+<para>
+	In <xref linkend="multiplearrayindices"/>, the first probe tracks how many times each process 
+	performs a VFS read. What makes this different from earlier examples is that this array associates
+	a performed read to both a process name <emphasis>and</emphasis> its corresponding process ID.
+</para>
+
+<para>
+	The second probe in <xref linkend="multiplearrayindices"/> demonstrates how to process and print
+	the information collected by the array <literal>reads</literal>. Note how the 
+	<command>foreach</command> statement uses the same number of variables (i.e. 
+	<literal>var1</literal> and <literal>var2</literal>) contained in the first instance of the array 
+	<literal>reads</literal> from the first probe.
+</para>
+
+
 </section>
 
 </section>
\ No newline at end of file
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml
index 36423fb4..04e34de3 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml
@@ -158,13 +158,13 @@ foo["dick"] = 24
 foo["harry"] = 25
 </screen>
 </example>
-
+<!--
 <para>You can specify up to 5 index expressons in an array statement, each one delimited by a comma (<command>,</command>). 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 <xref linkend="arraysimplestexample"/>, you can use the following statement:</para>
 
 <screen>
 foo["tom","dick","harry"] ++
 </screen>
-
+-->
 <important>
 	<title>Important</title>
 	<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>
-- 
cgit