On 04/11/10 08:59, Brian Utterback wrote:
On 04/09/10 20:44, Alan Wright wrote:
I honestly can't see what value a list would add to this case.
The examples in the case material provide way more information
than such a list because they provide context, and one can
always obtain a list by running kstat at the command line.
If an interface table is desirable, how about:
Interfaces
________________________________________________________________
| Imported Interface | Classification | Comments |
|________________________|___________________|__________________|
| smbsrv kstats | Project | |
| | Private | |
|________________________|___________________|__________________|
Alan
Did you name the stats you are using something opaque or something
vaguely intelligible? I am going to guess the latter. So, we know that
the kstat output was explicitly designed to be machine readable, i.e.
able to be an interface. So, with library interfaces we have man pages
to tell us what each is and we know if there doesn't exist a man page,
then that interface is private. Tell me, where is the list of public
kstats? As a programmer, I see something I would like to use in the
kstats output, and looking at the source code I see that it tallies
exactly what I need. How do I find out if it is public or private? I
might plug it into Google and see what I get. If you don't list it in
your proposal, then I get nothing, or just where it is found in the
source code. If you do list it, then the single hit that is not in the
source code is going to be your table, where it is clearly listed as
private. Darn, I am out of luck.
>
Unless and until we get a standard set of docs that definitively lists
what is public, then in proposals like this one is the only place these
interfaces are documented. You don't have to do this now, when you
integrate make a list from the kstat output and send it so it gets added
to the mail file. How hard is that?
Yes, the kstat interface should have a self-describing means of describing
kstat stability attributes, along the lines of Dtrace. The default
would be to make all of them (i.e., those not explicitly selecting a higher
level)
something like "Project Private", and you'd see that in kstat(1m) output etc.
But it seems unreasonable to insist that this project in any
way document its private interfaces because of a deficiency in the kstat design.
If it's such a burning need let's spin up an rfe/project to add stability
levels to published kstats, but don't hammer this project with that
requirement.
Gavin
_______________________________________________
opensolaris-arc mailing list
opensolaris-arc@opensolaris.org
