From: Frank Ch. Eigler <fche@redhat.com>
Date: Sat, 13 Oct 2012 16:22:56 +0000 (-0400)
Subject: PR12022: lightly document new foreach (@aggr) sorting option
X-Git-Tag: release-2.1~358
X-Git-Url: https://sourceware.org/git/?a=commitdiff_plain;h=2712766d3e146217809d37c9257bd9f6f3207316;p=systemtap.git

PR12022: lightly document new foreach (@aggr) sorting option
---

diff --git a/NEWS b/NEWS
index 8608e86ef..a8b0a1a53 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,9 @@
 * What's new in version 2.1
 
+- The foreach looping constuct can now sort aggregate arrays by the user's      
+  choice of aggregating function.  Previously, @count was implied.  e.g.:
+     foreach ([x,y] in array @sum +) { println(@sum(array[x,y] } 
+
 * What's new in version 2.0, 2012-10-09
 
 - Systemtap includes a new prototype backend, which uses Dyninst to instrument
diff --git a/stap.1 b/stap.1
index f792a6456..ef61d338a 100644
--- a/stap.1
+++ b/stap.1
@@ -909,6 +909,13 @@ By adding a single
 .BR + " or " \-
 operator after the VAR or the ARRAY identifier, the iteration will
 proceed in a sorted order, by ascending or descending index or value.
+If the array contains statistics aggregates, adding the desired
+.BR @operator
+between the ARRAY identifier and the 
+.BR + " or " \-
+will specify the sorting aggregate function.  See the STATISTICS
+section below for the ones available.  Default is
+.BR @count .
 Using the optional
 .BR limit
 keyword limits the number of loop iterations to EXP times.  EXP is
@@ -1238,7 +1245,10 @@ operation.  The
 .IR @count(v) ", " @sum(v) ", " @min(v) ", " @max(v) ", " @avg(v)
 extractor functions compute the number/total/minimum/maximum/average
 of all accumulated values.  The resulting values are all simple
-integers.
+integers.  Arrays containing aggregates may be sorted and iterated.
+See the
+.BR foreach
+construct above.
 .PP
 Histograms are also available, but are more complicated because they
 have a vector rather than scalar value.
@@ -1252,13 +1262,21 @@ with the
 family of functions renders a histogram object as a tabular
 "ASCII art" bar chart.
 .SAMPLE
-probe foo {
-  x <<< $value
+probe timer.profile {
+  x[1] <<< pid()
+  x[2] <<< uid()
+  y <<< tid()
 }
+global x // an array containing aggregates
+global y // a scalar
 probe end {
-  printf ("avg %d = sum %d / count %d\\n",
-          @avg(x), @sum(x), @count(x))
-  print (@hist_log(x))
+  foreach ([i] in x @count+) {
+     printf ("x[%d]: avg %d = sum %d / count %d\\n",
+             i, @avg(x[i]), @sum(x[i]), @count(x[i]))
+     println (@hist_log(x[i]))
+  }
+  println ("y:")        
+  println (@hist_log(y))  
 }
 .ESAMPLE