# Array Operations in SystemTap

This section enumerates some of the most commonly used array operations in SystemTap.

## Assigning an Associated Value

Use `=` to set an associated value to indexed unique pairs, as in:

    array_name[index_expression] = value

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 `index_expression` and `value`. 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:

Associating Timestamps to Process Names

    foo[tid()] = gettimeofday_s()

Whenever an event invokes the statement in , SystemTap returns the appropriate `tid()` value (i.e. the ID of a thread, which is then used as the unique key). At the same time, SystemTap also uses the function `gettimeofday_s()` to set the corresponding timestamp as the associated value to the unique key defined by the function `tid()`. This creates an array composed of key pairs containing thread IDs and timestamps.

In this same example, if `tid()` returns a value that is already defined in the array `foo`, the operator will discard the original associated value to it, and replace it with the current timestamp from `gettimeofday_s()`.

array operations assigning associated values
assigning associated values array operations
values, assignment of array operations
assigning associated values array operations associating timestamps to process names
array operations assigning associated values associating timestamps to process names
operations assigning associated values associating timestamps to process names
assigning associated values associating timestamps to process names array operations
associating timestamps to process names assigning associated values array operations
timestamps, association thereof to process names assigning associated values array operations

## Reading Values From Arrays

You can also read values from an array the same way you would read the value of a variable. To do so, include the `array_name[index_expression]` statement as an element in a mathematical expression. For example:

Using Array Values in Simple Computations

    delta = gettimeofday_s() - foo[tid()]

This example assumes that the array `foo` was built using the construct in (from ). This sets a timestamp that will serve as a reference point, to be used in computing for `delta`.

The construct in computes a value for the variable `delta` by subtracting the associated value of the key `tid()` from the current `gettimeofday_s()`. The construct does this by reading the value of `tid()` from the array. This particular construct is useful for determining the time between two events, such as the start and completion of a read operation.

Note

If the `index_expression` cannot find the unique key, it returns a value of 0 (for numerical operations, such as ) or a null/empty string value (for string operations) by default.

reading values from arrays array operations
array operations reading values from arrays
operations reading values from arrays
reading values from arrays array operations using arrays in simple computations
array operations reading values from arrays using arrays in simple computations
operations reading values from arrays using arrays in simple computations
using arrays in simple computations reading values from arrays array operations
algebraic formulas using arrays reading values from arrays array operations
array operations reading values from arrays computing for timestamp deltas
operations reading values from arrays computing for timestamp deltas
computing for timestamp deltas reading values from arrays array operations
reading values from arrays computing for timestamp deltas array operations
timestamp deltas, computing for reading values from arrays array operations
reading values from arrays array operations empty unique keys
array operations reading values from arrays empty unique keys
operations reading values from arrays empty unique keys
empty unique keys reading values from arrays array operations

## Incrementing Associated Values

Use `++` to increment the associated value of a unique key in an array, as in:

    array_name[index_expression] ++

Again, you can also use a handler function for your `index_expression`. For example, if you wanted to tally how many times a specific process performed a read to the virtual file system (using the event `vfs.read`), you can use the following probe:

vfsreads.stp

    probe vfs.read
    {
      reads[execname()] ++
    }

In , the first time that the probe returns the process name `gnome-terminal` (i.e. the first time `gnome-terminal` performs a VFS read), that process name is set as the unique key `gnome-terminal` with an associated value of 1. The next time that the probe returns the process name `gnome-terminal`, SystemTap increments the associated value of `gnome-terminal` by 1. SystemTap performs this operation for all process names as the probe returns them.

array operations incrementing associated values
incrementing associated values array operations
operations incrementing associated values
incrementing associated values array operations tallying virtual file system reads (VFS reads)
array operations incrementing associated values tallying virtual file system reads (VFS reads)
operations incrementing associated values tallying virtual file system reads (VFS reads)
tallying virtual file system reads (VFS reads) incrementing associated values array operations
VFS reads, tallying of incrementing associated values array operations

## Processing Multiple Elements in an Array

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 : 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 useful is to print the key pairs in the array `reads`, but how?

The best way to process all key pairs in an array (as an iteration) is to use the `foreach` statement. Consider the following example:

cumulative-vfsreads.stp

    global reads
    probe vfs.read
    {
      reads[execname()] ++
    }
    probe timer.s(3)
    {
      foreach (count in reads)
        printf("%s : %d \n", count, reads[count])
    }

In the second probe of , the `foreach` statement uses the variable `count` to reference each iteration of a unique key in the array `reads`. The `reads[count]` array statement in the same probe retrieves the associated value of each unique key.

Given what we know about the first probe in , 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.

Now, remember that the `foreach` statement in prints all 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 `+` (ascending) or `-` (descending). In addition, you can also limit the number of iterations the script needs to process with the `limit value` option.

For example, consider the following replacement probe:

    probe timer.s(3)
    {
      foreach (count in reads- limit 10)
        printf("%s : %d \n", count, reads[count])
    }

This `foreach` statement instructs the script to process the elements in the array `reads` in descending order (of associated value). The `limit 10` option instructs the `foreach` to only process the first ten iterations (i.e. print the first 10, starting with the highest value).

multiple elements in an array array operations
array operations multiple elements in an array
operations multiple elements in an array
array operations processing multiple elements in an array
processing multiple elements in an array array operations
operations processing multiple elements in an array
array operations processing multiple elements in an array foreach
operations processing multiple elements in an array foreach
processing multiple elements in an array foreach array operations
foreach processing multiple elements in an array array operations
array operations processing multiple elements in an array iterations, processing elements in an array as
operations processing multiple elements in an array iterations, processing elements in an array as
iterations, processing elements in an array as processing multiple elements in an array array operations
array operations processing multiple elements in an array cumulative virtual file system reads, tallying
operations processing multiple elements in an array cumulative virtual file system reads, tallying
cumulative virtual file system reads, tallying processing multiple elements in an array array operations
processing multiple elements in an array cumulative virtual file system reads, tallying array operations
virtual file system reads (cumulative), tallying processing multiple elements in an array array operations
array operations processing multiple elements in an array limiting the output of foreach
operations processing multiple elements in an array limiting the output of foreach
processing multiple elements in an array limiting the output of foreach array operations
limiting the output of foreach processing multiple elements in an array array operations
array operations processing multiple elements in an array ordering the output of foreach
operations processing multiple elements in an array ordering the output of foreach
processing multiple elements in an array ordering the output of foreach array operations
ordering the output of foreach processing multiple elements in an array array operations

## Clearing/Deleting Arrays and Array Elements

Sometimes, you may need to clear the associated values in array elements, or reset an entire array for re-use in another probe. in 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.

To do that, you will need to clear the values accumulated by the array. You can accomplish this using the `delete` operator to delete elements in an array, or an entire array. Consider the following example:

noncumulative-vfsreads.stp

    global reads
    probe vfs.read
    {
      reads[execname()] ++
    }
    probe timer.s(3)
    {
      foreach (count in reads)
        printf("%s : %d \n", count, reads[count])
      delete reads
    }

In , the second probe prints the number of VFS reads each process made within the probed 3-second period only. The `delete reads` statement clears the `reads` array within the probe.

Note

You can have multiple array operations within the same probe. Using the examples from and , you can track the number of VFS reads each process makes per 3-second period and tally the cumulative VFS reads of those same processes. Consider the following example:

    global reads, totalreads

    probe vfs.read
    {
      reads[execname()] ++
      totalreads[execname()] ++
    }

    probe timer.s(3)
    {
      printf("=======\n")
      foreach (count in reads-)
        printf("%s : %d \n", count, reads[count])
      delete reads
    }

    probe end
    {
      printf("TOTALS\n")
      foreach (total in totalreads-)
        printf("%s : %d \n", total, totalreads[total])
    }

In this example, the arrays `reads` and `totalreads` track the same information, and are printed out in a similar fashion. The only difference here is that `reads` is cleared every 3-second period, whereas `totalreads` keeps growing.

array operations clearing arrays/array elements multiple array operations within the same probe
operations clearing arrays/array elements multiple array operations within the same probe
clearing arrays/array elements array operations multiple array operations within the same probe
multiple array operations within the same probe clearing arrays/array elements array operations
array operations deleting arrays and array elements
operations deleting arrays and array elements
array operations clearing arrays/array elements
operations clearing arrays/array elements
clearing arrays/array elements array operations
array operations clearing arrays/array elements delete operator
operations clearing arrays/array elements delete operator
clearing arrays/array elements array operations delete operator
delete operator clearing arrays/array elements array operations
array operations clearing arrays/array elements virtual file system reads (non-cumulative), tallying
operations clearing arrays/array elements virtual file system reads (non-cumulative), tallying
clearing arrays/array elements array operations virtual file system reads (non-cumulative), tallying
virtual file system reads (non-cumulative), tallying clearing arrays/array elements array operations

## Using Arrays in Conditional Statements

You can also use associative arrays in `if` 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:

vfsreads-print-if-1kb.stp

    global reads
    probe vfs.read
    {
      reads[execname()] ++
    }

    probe timer.s(3)
    {
      printf("=======\n")
      foreach (count in reads-)
        if (reads[count] >= 1024)
          printf("%s : %dkB \n", count, reads[count]/1024)
        else
          printf("%s : %dB \n", count, reads[count])
    }

Every three seconds, 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 `if` statement in the script converts and prints it out in `kB`.

Testing for Membership

You can also test whether a specific unique key is a member of an array. Further, membership in an array can be used in `if` statements, as in:

array operations conditional statements, using arrays in testing for array membership
operations conditional statements, using arrays in testing for array membership
conditional statements, using arrays in array operations testing for array membership
testing for array membership conditional statements, using arrays in array operations
membership (in array), testing for conditional statements, using arrays in array operations

    if([index_expression] in array_name) statement

To illustrate this, consider the following example:

vfsreads-stop-on-stapio2.stp

    global reads

    probe vfs.read
    {
      reads[execname()] ++
    }

    probe timer.s(3)
    {
      printf("=======\n")
      foreach (count in reads+)
        printf("%s : %d \n", count, reads[count])
      if(["stapio"] in reads) {
        printf("stapio read detected, exiting\n")
        exit()
      }
    }

The `if(["stapio"] in reads)` statement instructs the script to print `stapio read detected, exiting` once the unique key `stapio` is added to the array `reads`.

array operations conditional statements, using arrays in
operations conditional statements, using arrays in
conditional statements, using arrays in array operations
if/else statements, using arrays in array operations

## Computing for Statistical Aggregates

Statistical aggregates are used to collect statistics on numerical values where it is important to accumulate new data quickly and in large volume (i.e. storing only aggregated stream statistics). Statistical aggregates can be used in global variables or as elements in an array.

To add value to a statistical aggregate, use the operator `<<< value`.

need more examples of supported rvalues, e.g. length, count, and what each one does.

stat-aggregates.stp

    global reads
    probe vfs.read
    {
      reads[execname()] <<< count
    }

In , the operator `<<< count` stores the amount returned by `count` to to the associated value of the corresponding `execname()` in the `reads` array. Remember, these values are stored; 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 (`execname()`) having multiple associated values, accumulating with each probe handler run.

Note

In the context of , `count` returns the amount of data read by the returned `execname()` to the virtual file system.

To extract data collected by statistical aggregates, use the syntax format `@extractor(variable/array index expression)`. `extractor` can be any of the following integer extractors:

count

  Returns the number of all values stored into the variable/array index expression. Given the sample probe in , the expression `@count(reads[execname()])` will return how many values are stored in each unique key in array `reads`.

array operations computing for statistical aggregates @count (integer extractor)
operations computing for statistical aggregates @count (integer extractor)
computing for statistical aggregates array operations @count (integer extractor)
@count (integer extractor) computing for statistical aggregates array operations
sum

  Returns the sum of all values stored into the variable/array index expression. Again, given sample probe in , the expression `@sum(reads[execname()])` will return the total of all values stored in each unique key in array `reads`.

array operations computing for statistical aggregates @sum (integer extractor)
operations computing for statistical aggregates @sum (integer extractor)
computing for statistical aggregates array operations @sum (integer extractor)
@sum (integer extractor) computing for statistical aggregates array operations
min

  Returns the smallest among all the values stored in the variable/array index expression.

array operations computing for statistical aggregates @min (integer extractor)
operations computing for statistical aggregates @min (integer extractor)
computing for statistical aggregates array operations @min (integer extractor)
@min (integer extractor) computing for statistical aggregates array operations
max

  Returns the largest among all the values stored in the variable/array index expression.

array operations computing for statistical aggregates @max (integer extractor)
operations computing for statistical aggregates @max (integer extractor)
computing for statistical aggregates array operations @max (integer extractor)
@max (integer extractor) computing for statistical aggregates array operations
avg

  Returns the average of all values stored in the variable/array index expression.

array operations computing for statistical aggregates @avg (integer extractor)
operations computing for statistical aggregates @avg (integer extractor)
computing for statistical aggregates array operations @avg (integer extractor)
@avg (integer extractor) computing for statistical aggregates array operations

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:

Multiple Array Indexes

    global reads
    probe vfs.read
    {
      reads[execname(),pid()] <<< 1
    }
    probe timer.s(3)
    {
      foreach([var1,var2] in reads)
        printf("%s (%d) : %d \n", var1, var2, @count(reads[var1,var2]))
    }

In , 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 and its corresponding process ID.

The second probe in demonstrates how to process and print the information collected by the array `reads`. Note how the `foreach` statement uses the same number of variables (i.e. `var1` and `var2`) contained in the first instance of the array `reads` from the first probe.

statistical aggregates array operations
aggregates (statistical) array operations
array operations computing for statistical aggregates
operations computing for statistical aggregates
computing for statistical aggregates array operations
array operations computing for statistical aggregates adding values to statistical aggregates
operations computing for statistical aggregates adding values to statistical aggregates
computing for statistical aggregates array operations adding values to statistical aggregates
adding values to statistical aggregates computing for statistical aggregates array operations
array operations computing for statistical aggregates count (operator)
operations computing for statistical aggregates count (operator)
computing for statistical aggregates array operations count (operator)
count operator computing for statistical aggregates array (operator)
array operations computing for statistical aggregates extracting data collected by statistical aggregates
operations computing for statistical aggregates extracting data collected by statistical aggregates
computing for statistical aggregates array operations extracting data collected by statistical aggregates
extracting data collected by statistical aggregates computing for statistical aggregates array operations
integer extractors computing for statistical aggregates array operations
array operations associative arrays
operations associative arrays