Re: [PATCH 8/9] Documentation for DTrace USDT probes.

[jose.marchesi@oracle.com (Jose E. Marchesi)]

    >     > +Some @code{SystemTap} probes have an associated semaphore variable;
    >     > +for instance, this happens automatically if you defined your probe
    >     > +using a DTrace-style @file{.d} file.  If your probe has a semaphore,
    >     > +@value{GDBN} will automatically enable it when you specify a
    >     > +breakpoint using the @samp{-probe-stap} notation.  But, if you put a
    >     > +breakpoint at a probe's location by some other method (e.g.,
    >     > +@code{break file:line}), then @value{GDBN} will not automatically set
    >     > +the semaphore.  @code{DTrace} probes do not support the notion of
    >     > +semaphores.
    >     
    >     The last sentence confused me: you first explain something that seems
    >     to imply semaphores are part of DTrace probes, but then say that they
    >     don't support semaphores.  What am I missing?
    > 
    > The paragraph starts explaining that SystemTap probes may have
    > associated semaphore variables, followed by a short description on how
    > gdb handles these variables.  That was part of the original
    > documentation on SystemTap probes.
    > 
    > I just added the last sentence to note that DTrace probes do not support
    > semaphore variables at all.
    > 
    > I don't see where the confusion is?
    
    The confusion starts with the fact that "DTrace" is mentioned twice,
    the first time in the context of discussing semaphores.

Aaah, that mention to the "DTrace-like" file.  Yes, I agree, it can be
confusing now that DTrace probes are also supported.

    How about the following rewrite:
    
      Some @code{SystemTap} probes have an associated semaphore variable.
      If your probe has a semaphore, @value{GDBN} will automatically
      enable it when you specify a breakpoint using the @samp{-probe-stap}
      notation.  But, if you put a breakpoint at a probe's location by
      some other method (e.g., @code{break file:line}), then @value{GDBN}
      will not automatically set the semaphore.  @code{DTrace} probes do
      not support semaphore variables associated with them.

I think that is indeed better than the current wording.  Thanks.
    
    >     > +probe being handled.  Some @code{DTrace} probes can be enabled or
    >     > +disabled, but @code{SystemTap} probes do not support these notions.
    >     
    >     Which "notions"?  If you want to say they cannot be disabled, please
    >     say so explicitly.
    > 
    > No, I want to say that SystemTap probes do not even support the notion
    > of being enabled or disabled.  That is not quite the same than saying
    > that SystemTap probes cannot be disabled: for example some DTrace probes
    > cannot be disabled because they are always enabled.
    
    Sorry, I don't see the difference between "cannot be disabled" and
    "don't support the notion of being enabled or disabled".  A trap that
    cannot be disabled is by definition always enabled, right?  So from
    the user point of view, saying they cannot be disabled says it all,
    right?

Well... right, from the user perspective SystemTap probes are always
enabled...  Ok, I will follow your suggestion and just mention that
SystemTap probes cannot be disabled.