path: root/doc/SystemTap_Beginners_Guide/en-US/Arrays.xml

<?xml version='1.0'?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<section id="associativearrays">
	<title>Associative Arrays</title>
<indexterm>
<primary>arrays</primary>
<secondary>introduction</secondary>
</indexterm>

<indexterm>
<primary>associative arrays</primary>
<secondary>introduction</secondary>
</indexterm>	
<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>

<!-- next 2 indexterms for key pairs -->

<indexterm>
<primary>arrays</primary>
<secondary>introduction</secondary>
<tertiary>key pairs</tertiary>
</indexterm>

<indexterm>
<primary>associative arrays</primary>
<secondary>introduction</secondary>
<tertiary>key pairs</tertiary>
</indexterm>

<indexterm>
<primary>key pairs</primary>
<secondary>introduction</secondary>
<tertiary>arrays</tertiary>
</indexterm>

<!-- next 2 indexterms for unique keys -->

<indexterm>
<primary>arrays</primary>
<secondary>introduction</secondary>
<tertiary>unique keys</tertiary>
</indexterm>

<indexterm>
<primary>associative arrays</primary>
<secondary>introduction</secondary>
<tertiary>unique keys</tertiary>
</indexterm>

<indexterm>
<primary>unique keys</primary>
<secondary>introduction</secondary>
<tertiary>arrays</tertiary>
</indexterm>

<!-- next 2 indexterms for associated values -->

<indexterm>
<primary>arrays</primary>
<secondary>introduction</secondary>
<tertiary>associated values</tertiary>
</indexterm>

<indexterm>
<primary>associative arrays</primary>
<secondary>introduction</secondary>
<tertiary>associated values</tertiary>
</indexterm>

<indexterm>
<primary>associated values</primary>
<secondary>introduction</secondary>
<tertiary>arrays</tertiary>
</indexterm>

<!-- next 2 indexterms for index expression -->

<indexterm>
<primary>arrays</primary>
<secondary>introduction</secondary>
<tertiary>index expression</tertiary>
</indexterm>

<indexterm>
<primary>associative arrays</primary>
<secondary>introduction</secondary>
<tertiary>index expression</tertiary>
</indexterm>

<indexterm>
<primary>index expression</primary>
<secondary>introduction</secondary>
<tertiary>arrays</tertiary>
</indexterm>

<para>Since associative arrays are normally processed in multiple probes (as we will demonstrate later), they are declared as <command>global</command> variables in the SystemTap script. The syntax for manipulating arrays (i.e. accessing elements in an associative array) is similar to that of <command>awk</command>, and is as follows:</para>
<!-- next 3 indexterms for syntax -->
<indexterm>
<primary>arrays</primary>
<secondary>introduction</secondary>
<tertiary>syntax</tertiary>
</indexterm>

<indexterm>
<primary>associative arrays</primary>
<secondary>introduction</secondary>
<tertiary>syntax</tertiary>
</indexterm>

<indexterm>
<primary>syntax</primary>
<secondary>introduction</secondary>
<tertiary>arrays</tertiary>
</indexterm>

<indexterm>
<primary>format</primary>
<secondary>introduction</secondary>
<tertiary>arrays</tertiary>
</indexterm>


<screen>
<replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>] <replaceable>operation</replaceable>
</screen>

<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 (or set of unique keys) in the array, and the <command><replaceable>operation</replaceable></command> defines what to do with the <command><replaceable>index_expression</replaceable></command>. To illustrate, let us try to build an array named <command>foo</command> that specifies the ages of three people (i.e. the unique keys): <command>tom</command>, <command>dick</command>, and <command>harry</command>. To assign them the ages (i.e. associated values) of 23, 24, and 25 respectively, we'd use the following array statements:</para> 

<!-- next 2 indexterms for example -->

<indexterm>
<primary>arrays</primary>
<secondary>introduction</secondary>
<tertiary>example</tertiary>
</indexterm>

<indexterm>
<primary>associative arrays</primary>
<secondary>introduction</secondary>
<tertiary>example</tertiary>
</indexterm>

<indexterm>
<primary>example</primary>
<secondary>introduction</secondary>
<tertiary>arrays</tertiary>
</indexterm>
<example id="arraysimplestexample">
	<title>Basic Array Statements</title>
<screen>
foo["tom"] = 23
foo["dick"] = 24
foo["harry"] = 25
</screen>
</example>

<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>
</important>


<section id="tuples">
	<title>Array Slots</title>
<!-- next 2 indexterms for slots -->

<indexterm>
<primary>arrays</primary>
<secondary>introduction</secondary>
<tertiary>slots</tertiary>
</indexterm>

<indexterm>
<primary>associative arrays</primary>
<secondary>introduction</secondary>
<tertiary>slots</tertiary>
</indexterm>

<indexterm>
<primary>slots</primary>
<secondary>introduction</secondary>
<tertiary>arrays</tertiary>
</indexterm>	
<para>Another important point to remember in arrays is that each element therein (i.e. the indexed expression) exists in a <emphasis>slot</emphasis>. A key pair's slot is defined by the order in which each pair's unique key is defined. In our sample array <command>foo</command> in <xref linkend="arraysimplestexample"/>, the key pair that uses the unique key <command>tom</command> is in the first slot, since <command>tom</command> was the first unique key to be defined. <command>dick</command> is in the second slot, and so on.</para>

<!--
<para>The sequence in which each key pair appears in an array (as defined by each pair's slot) is referred to as a <emphasis>tuple</emphasis>. Tuples allow us to refer to key pairs in an array by the order in which they appear in the sequence.</para>-->

<para>For example, the array statements in <xref linkend="arraysimplestexample"/> set 23 as the associated value of the unique key <command>tom</command>. Given the same array <command>foo</command>, we can increment the associated value of <command>tom</command> by 1 using the operator <command>++</command>, like so:</para>

<screen>
foo["tom"] ++
</screen>

<para>The above statement will increase the associated value of unique key <command>tom</command> to 24. Now, looking back at <xref linkend="arraysimplestexample"/>, we know that <command>dick</command> was the first unique key to be defined. As such, we can perform the same operation (i.e. incrementing associated value by 1) to <command>dick</command> using the following statement:</para>

<screen>
foo[2] ++
</screen>

<note>
	<title>Note</title>
	<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",2,"harry"] ++
</screen>
</note>


</section>	
<xi:include href="Array-Operations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />	
<!--	
<varlistentry>
	<term></term>
	<listitem>
		<para></para>
	</listitem>	
</varlistentry>
-->	

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

<formalpara id="aaexamplesimple">
	<title>Incrementing Associated Values of Unique Keys</title>
<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>
</formalpara>
<screen>
<replaceable>array_name</replaceable>[<replaceable>index_expression</replaceable>"] ++
</screen>

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

<formalpara id="aaexamplesimple-example">
	<title>explicit-incrementing-in-arrays.stp</title>
<para>
<programlisting>
probe begin {	foo[4,"hello"] ++ }
</programlisting>
</para>
</formalpara>

<formalpara id="aaexampleupdatecounting">
	<title>Incrementing Associated Values of Unique Keys (By Variable)</title>
	
<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>
</formalpara>

<screen>
<replaceable>array_name</replaceable>[<replaceable>unique_key</replaceable>] += $count	
</screen>

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

<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 kernel function <command>vfs_read</command>, 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>

<formalpara id="aaexamplesimplevfsreads">
	<title>tallying-in-arrays.stp</title>
<para>
<programlisting>
probe kernel.function("vfs_read")
{ reads[execname()] += $count }
</programlisting>
</para>
</formalpara>

<para>In <xref linkend="aaexamplesimplevfsreads"/>, the first time that the probe returns the process name <command>gnome-terminal</command> (i.e. 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>
-->
</section>