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

diff --git a/NEWS b/NEWS
index 8608e86efe0015a4e37e39f6cda8959dafe1bd97..a8b0a1a5361a3d48a36d05f2c51b74c96e880056 100644 (file)
--- 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 f792a6456ec77d0ef2c4986db509d731edc61017..ef61d338ab9645df010a21b17b300cf6a421dac6 100644 (file)
--- 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