Re: tutorial draft checked in

[Martin Hunt <hunt at redhat dot com>]

On Fri, 2006-03-03 at 12:56 -0500, Frank Ch. Eigler wrote:
> I checked in a draft of the systemtap tutorial (/doc/tutorial).  

Very Nice!

On first reading, I have only a few minor comments.

Section 3.5

>This operation is efficient (taking a shared lock) because the
>aggregate values are kept separately on each processor, and are only 
>aggregated across processors on request.

Surprised me. I checked and this accurately described the current
implementation, but the shared lock is unnecessary and should probably
not be mentioned.


>b[cpu(),execname()] <<< 1 # better than ++
[...]
>print(@hist_log(b[0,"zsh"])) print an "ascii art" 
>logarithmic histogram of the same data stream

Indexing by cpu() here complicates the example, especially after
discussing how aggregates store information per-cpu. And the histogram
example won't print anything like a histogram because the values are all
1. I suggest you change these to something clearer.

writes[execname()] <<< count 

print(@hist_log(writes["zsh"])) print an "ascii art" logarithmic
histogram of the same data stream

Section 3.6

What about running out of memory? Need to mention that arrays are
preallocated, fixed in size, can overflow, and what happens when they
do. That may change in the future.

Section 4.3

>Since systemtap cannot examine the C code to infer these 
>types, an optional type annotation syntax is available 
>for explicitly declaring them.

If it is optional, what happens if the types are not declared?
Is there a default? 

4.4

The ideas here are fine. 

Maybe it needs to be clearer that people shouldn't prefix their tapset
functions with "TAPSET_" but with the unique tapset name followed by
underscore.

Martin