Comments for the draft of CommandsList

Feel free to comment the draft on this page. It is in it's early stage - your opinions have a good chance of changing the shape of things. Please, for the sake of clarity, sign your comments and distinct threads with a horizontal line. --lRem

---

Suggestions on the state of the draft as of 6 July --das

dtrace::work: done

switch to callback model, empty return value, explain that calling this will become optional once event loop integration is done.

dtrace::go: done

add a list argument specifying the callback for tracing data processing.

dtrace::go: done

add a list argument specifying the callback for drop, error and proc notification (i.e. via the handlers set by dtrace_handle_err(), dtrace_handle_drop(), and dtrace_handle_proc()).

dtrace::sleep: done

drop, instead add a boolean argument to dtrace::work indicating whether it should sleep before calling dtrace_work().

dtrace::work: rejected

specify all possible strings for 'output type' explicitly, as well as the format for every type (e.g. for stacks a dict or list, for aggregations a dict etc).

dtrace::work: done

rename to dtrace::process.

dtrace::list: done

make callback based.

dtrace::configure: done

drop the cpp related options, better to run cpp from tcl directly.

dtrace::configure:

detail all legal options in the api spec, it's hard to know from the LibDTrace doc page which options are relevant for TclDTrace, there are also options missing in the LibDTrace doc which are clearly relevant (but are not dtrace(1) options), c.f. dt_options.c.

dtrace::configure: done

relate option names to #pragmas, explain that compiling programs with #pragmas can change configuration.

dtrace::configure: modified

add an option specifying a pid to be grabbed for tracing, with 0 indicating no pid grabbed (like 'dtrace -p', can also be used to replicate 'dtrace -c' (via [exec]) from tcl).

dtrace::configure:

clarify language about return value in the three different call modes (see e.g. language in fconfigure.n man page).

dtrace::compile: rejected

the '[[[provider:] module:] function:] name [[predicate] action]' spec is incorrect (square brackets are nested incorrectly): you can give a predicate without an action (in which case the default action, i.e. print probe identifier, is used); similarly, you can give a provider without a module and a module without a function (e.g. dtrace:::BEGIN)

dtrace::info:

wrap dtrace_program_info() and return the same dict as for dtrace::exec (the user may not want to execute a program, only to examine it, e.g. as in 'dtrace -l').

dtrace::status:

wrap dtrace_status() (no way to determine if tracing has stopped due to external events otherwise).

dtrace::errno, dtrace::errstr: done

drop, report all errors by throwing a tcl error, drop all language about empty string returns in error case from the spec.

dtrace::open: done

throw errors.

dtrace::close: done

drop "OK" string return.

Responses

--lrem

Accepting most of the suggestions. Rejecting the dtrace::compile related one - this spec is correct and taken from the man page. Empty string matches everything, and trying to give predicate without an action results with:

# dtrace -n 'BEGIN /1/'
dtrace: invalid probe specifier BEGIN /1/: expected actions { } following probe description and predicate

--das:

oops, you're right about the predicate, sorry. However I maintain that the '[[[provider:] module:] function:] name' part is incorrect (e.g. does not match the legal probe names someprovider:::, somemodule::, somefunction:, :somename etc), I think it should be something like

[provider]:[module]:[function]:[name]|[module]:[function]:[name]|[function]:[name]|name

(where any part of provider, module, function or name can additionally be replaced by * for globbing).

--lrem:

I'd prefer to leave that in the shape that is found in the man page. But I've added those clarifications I've mentioned earlier.

--das:

it looks fine with those clarifications, this is only a minor nit anyway.

what is not correct however is the phrase Note this does not compile whole scripts., as we've discovered, string compilation does indeed support whole scripts, so you can pass whole programs to dtrace::compile, including #pragmas, type&variable declarations and multiple '[[[provider:] module:] function:] name [[predicate] action]' statements.

--lrem:

As for -p equivalent - I rather make it a separate command. That's because it's not just configuring how DTrace works - it actually grabs the process.

--das:

agreed, dtrace::grab looks good.

--lrem:

As for ::dtrace::status - currently my vision is that when tracing has stopped due to external events we get an error inside ::dtrace::work. But I don't have idea how to make that work once we get that implicit inside event loop.

--das:

passing such errors back via the new error callback should work, may want to check if that can cover everything dtrace_status() can indicate?

--lrem:

At the moment I don't plan on structuring the data for the user. I'll return raw strings as we get them from LibDtrace. We can always add stack parsing in the future, enabled by an option to ::dtrace::go, or even ::dtrace::configure (where it seems to be more intuitive).

--das:

fair enough, probably best to do that sort of thing purely in tcl anyway.

---