Commit Graph

36 Commits

Author SHA1 Message Date
Jim Warner
ea930f6f9e library <stat>: input file buffer size must be dynamic
Since its introduction, our evolved /proc/stat API has
relied on a static buffer of 8192 bytes. This approach
is probably Ok for other /proc files but it would only
accommodate around 100 processors. If such a threshold
were exceeded then this interface could never succeed.

Now days 100 processors doesn't seem at all excessive.

So this commit trades that static buffer for a dynamic
self-tuning one. And since so much former top CPU code
was already rolled into this module, we just stole the
already proven top dynamic buffer management code too.

[ this also meant switching low level unbuffered I/O ]
[ calls to standard library buffered I/O calls. that ]
[ is exactly what <slabinfo> and <diskstats> employ. ]

Reference(s):
. 1st gen readstat introduction
commit a410e236ab

Signed-off-by: Jim Warner <james.warner@comcast.net>
2017-01-05 06:48:38 +11:00
Jim Warner
282ee362f0 library <stat>: improve response to cpu offline/online
With the addition of those new derived SUM values, any
CPUs taken offline or brought online would distort the
historical (delta) results.  So this patch just forces
a history reset when such transitions are encountered.

Reference(s):
. derived SUM provisions introduced
commit 2c86c4984a

Signed-off-by: Jim Warner <james.warner@comcast.net>
2017-01-05 06:48:38 +11:00
Jim Warner
e524e48138 library: eliminate distorted history 1st time switches
Upon reflection, at the point where the 'priming read'
was introduced, any possibility of history distortions
was also eliminated.  This was true because all of the
'old' (zeroed) data will have been replaced with 'new'
data whenever a user finally calls get, select & reap.

Thus, any DELTA values will automatically reflect that
interval between 'new' and subsequent retrieval calls.

[ diskstats didn't actually employ a 1st time switch ]
[ like the others so we have changed a comment only. ]
[ but that module will retain something similar used ]
[ inside node_update whenever a new node is created. ]

Reference(s):
. priming read added to slabinfo
commit 5d5a52a380
. priming read added to diskstats
commit ecd64f4445
. priming read added to meminfo, stat, vmstat
commit 1a2b62c779

Signed-off-by: Jim Warner <james.warner@comcast.net>
2017-01-05 06:48:38 +11:00
Jim Warner
2c86c4984a library <stat>: standardized new category calculations
This commit arose out of the discussion (and research)
surrounding the issue cited below. It is an attempt to
consolidate and standardize the calculation of jiffies
categories (e.g. 'idle', 'busy', etc.) once & for all.

Also included is the enum STAT_TIC_NUM_CONTRIBUTORS in
case anyone, in the future, decides to calculate usage
based upon elapsed time * Hz (like top does in process
level %CPU stats). In such an event, a total number of
CPUs or NUMA Nodes would be needed for proper scaling.

Reference(s):
https://gitlab.com/procps-ng/procps/issues/48

Signed-off-by: Jim Warner <james.warner@comcast.net>
2017-01-04 08:29:44 +11:00
Jim Warner
e70531a945 library: protect against possible 'refcount' underflow
In each module employing a priming read at 'new' time,
should that read fail, a call to 'unref' will be made.

However, there is a hidden dependency that these calls
must never occur before the context 'refcount' was set
due to the way an 'unref' conditional was constructed.

So this commit just ensures that 'unref' will function
as expected, even if called with a 'refcount' of zero.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-12-07 22:06:59 +11:00
Jim Warner
82a0dcda0f library: strictly cosmetic, absolutely no code changes
This commit just contains some tweaks to comments plus
a few adjustments to whitespace for alignment purposes
and a normalization of the header inclusion #define's.

[ plus a spelling error in one header file was fixed ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-10-09 21:31:29 +11:00
Jim Warner
9d1f6cb4ea library <stat>: added overlooked numa guest tic counts
When this module was upgraded to 3rd generation in the
patch referenced below, numa node support was migrated
from the top program into newlib. The 'guest_nice' and
'guest' tics were overlooked as top did not need them.

So, this commit corrects that oversight and achieves a
proper symmetry between the cpu & numa jiffies counts.

Reference(s):
. 3rd gen redesign, numa support imported
commit abc71a46ad

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-09-26 07:40:45 +10:00
Jim Warner
1a2b62c779 library: add priming read at 'new' time <most modules>
A priming read at 'new' time in that <slabinfo> module
was important so that permission problems are detected
early. Plus, it also had the potential of making delta
values valid when 'get' or 'select' were first called.

It is for that latter reason that such a read was also
incorporated in the <diskstats> module 'new' function.
No other module, however, employed such priming reads.

This patch just brings those potential benefits to all
of our other newlib modules with the exception of that
<pids> guy. That module is, of necessity, sufficiently
different from those others to justify such exclusion.

Not only are there precious few DELTA enums in <pids>,
but the costs of a priming read would be much greater.

[ otherwise, these newly added priming reads have no ]
[ measurable negative impact on performance/timings. ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-09-21 21:06:12 +10:00
Jim Warner
eeeba3e66c library: improve support of dynamic numa nodes, <stat>
If, in fact, numa nodes are dynamic (like that current
total of on-line cpus) the existing logic was lacking.
It included an early return before checking the total.

So, this commit ensures that the nodes total is always
set or updated consistently in only a single function.
There's no need to set it at the time 'new' is called.

[ and since under our existing code this nodes total ]
[ could never possibly have been zero, the erroneous ]
[ test (with the early return) has now been whacked! ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-09-21 21:06:12 +10:00
Jim Warner
91d47123f2 library: finally circumvent libnuma memory leak <stat>
Still unhappy with a minor memory leak associated with
libnuma, I experimented with omitting the dlclose that
was issued at module's end. For some reason which will
remain a mystery, the valgrind leak then went bye-bye.

So this patch just omits one use of dlclose and relies
on whatever kernel magic is at work to free the memory
when each process ends. We kept, however, the original
code (now commented-out) to serve as a future caution.

There remains one potential (but unlikely) dlclose use
near the original dlopen. But there will be no leak as
that 'numa_node_of_cpu' will not yet have been called.
This seems to be the culprit that triggers such leaks.

None of this libnuma shit would likely have come close
to hitting our fan had the numa developers provided us
with 'new' and 'unref' functions like our newlib does.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-09-18 20:37:24 +10:00
Jim Warner
834ed434c9 library: normalize stack and history allocation naming
Recent profiling and timings have resulted in improved
newlib performance. This patch completes that process.

It just normalizes naming conventions employed for all
allocations involving reaped stacks & history support.

The modules offering a 'reap' function will also offer
the now standardized corresponding STACKS_INCR define.

The modules which provide dynamic history support will
now have a separate #define called NEWOLD_INCR used in
allocations/reallocations. And, while values currently
are set equal to that STACKS_INCR value, in the future
some reason for divorcing those two may be discovered.

----------------------------- for future reference ---

In those modules which contain the STACKS_INCR #define
it is tempting to specify a large value so as to avoid
repeated calls to malloc/realloc. However, in doing so
an extra runtime price will be paid in 'cleanup_stack'
calls with any iterative programs like top or slabtop.

So, with the current values a balance has been sought.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-09-11 09:31:05 +10:00
Jim Warner
4fe42d0be9 library: most function names now more profile friendly
This patch will begin some refinements associated with
gprof. Initially, functions names have been changed to
help in identifying potential bottlenecks. This effort
also included the obscure set, free and sort routines.

Plus the following additional modifications were made:

. the stacks_alloc prologue was generalized plus added
to a couple of modules where it had not yet propagated

. a couple of the '// end ...' comments were corrected

. some functions have been formally tagged as 'inline'

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-23 21:11:09 +10:00
Jim Warner
530d19f90f library <STAT>: exclude an #include for --disable-numa
When the numa stuff was imported from the top program,
that #include for dlopen() was not made conditional as
it should have been. Well, here it is being corrected.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-11 07:57:55 +10:00
Jim Warner
7d20df9ef0 library: if the VAL type is wrong still return a value
Rather than return a 0 result for all VAL type errors,
return what would have been without validation active.

This will enable a program like pgrep to still print a
result even though it used some incorrect type member.

With this commit, our VAL macro validations logic will
behave in exactly the same way as the GET validations.
While warning messages may be issued, except for a bad
enumerator, values will always be returned to callers.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-11 07:56:00 +10:00
Jim Warner
9f27e9d8d9 library: strengthen the VAL macro validation functions
One ought not to assume that random memory access will
always succeed or, when it does, that an obviously bad
item enumerator will always be found at that location.

Thus, this patch corrects some really poor assumptions
associated with the 'xtra_procps_debug.h' header file.

[ and it does so in somewhat contorted ways so as to ]
[ avoid several darn gcc -Wnonnull warning messages! ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-08 22:01:37 +10:00
Jim Warner
bef8c7fb70 library: ensure that all those 'GET' macros are robust
When users call the native 'get' functions they have a
responsibility to check that the result struct address
was indeed returned. But when using those 'GET' macros
there was no protection for possible NULL dereference.

So this patch will add some protection for a potential
failure of an underlying 'get' function. And should it
occur then those 'GET' macros will just return a zero.

Plus, we'll also mirror that behavior in the debugging
header should the XTRA_PROCPS_DEBUG #define be active.
And, we might as well add a warning when invalid items
are passed to 'GET' macros, just like we do for 'VAL'.

[ lastly, we added the missing opening parens/braces ]
[ to 2 'GET' macros in that xtra-procps-debug.h file ]
[ which went unnoticed until the qa folks caught up. ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-07 21:43:38 +10:00
Jim Warner
e3270d463d library: provide for validating result type references
During development, we now have a means for validating
that a type referenced in application code matches the
actual type set by the library. The new feature can be
activated through either of the following two methods:

1) ./configure CFLAGS='-DXTRA_PROCPS_DEBUG' (all pgms)

2) an #include <proc/xtra-procps-debug.h> (single pgm)

[ in the future, one could add a formal configure.ac ]
[ provision. but for now a manual approach is safer. ]

Lastly, for any module which provides a sort function,
the handling for both 'noop' & 'extra' enumerators was
made consistent. Now, 'noop' is not sorted and 'extra'
will be sorted as that module's widest supported type.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-07 21:40:48 +10:00
Jim Warner
6f71a33c1d library: add final remaining sort function, <STAT> api
With this patch, all of the modules which offer a reap
function (pids, diskstats, slabinfo and stat too) will
now also provide for sorting whatever had been reaped.

It was easy to overlook a sort function for our <STAT>
guy given the paucity of CPUs on your typical personal
desktop or laptop. However, out in the world one might
find boxes with hundreds of CPUs plus many NUMA nodes.

Hey, who are we to disallow sorts on something another
person might see as useful under the above conditions?
And, there's always something to be said for symmetry.

[ of course, several minor tweaks were also included ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-28 20:46:18 +10:00
Jim Warner
c4d097c709 library: removed all the 'PROCPS_' enumerator prefixes
Many of our item enumerator identifiers are very long,
especially in that <VMSTAT> module. Additionally, they
all contain the exact same universal 'PROCPS_' prefix.

The origins for this are likely found in the desire to
avoid name clashes with other potential include files.
But with procps-ng newlib, we've probably gone way too
far. Did 'PROCPS_PIDS_TICS_SYSTEM' actually offer more
protection against clash than 'PIDS_TICS_SYSTEM' does?

I don't think so. Besides, no matter how big that name
becomes, one can never guarantee they'll never be some
clash. And, conversely, extremely short names will not
always create conflict. Of course, in either case when
some clash occurs, one can always #undef that problem.

Thus, this commit will eliminate that 'PROCPS_' prefix
making all of those enum identifiers a little shorter.
And, we'll still be well above some ridiculously short
(criminally short) names found in some common headers:

- - - - - - - - - - <term.h>
- 'tab', 'TTY', etc
- - - - - - - - - - - - - - - - <search.h>
- 'ENTER', ENTRY', 'FIND', etc

------------------------------------------------------
Finally, with this as a last of the wholesale changes,
we will have established the naming conventions below:

. only functions will begin with that 'procps_' prefix
. exposed structures begin with the module/header name
. item enumerators begin like structs, but capitalized
. other enumerators work exactly like item enumerators
. macros and constants begin just like the enumerators
------------------------------------------------------

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-26 20:49:00 +10:00
Jim Warner
82d5661603 library: standardize all the 'context' structure names
This patch attempts to standardize the naming of those
most important (declared not defined) context structs.

The present practice represents a hodge podge of names
only some of which reflect the source /proc file name.
And 2 of those file names embed a literal 'info' which
is likely the origin of that required parm identifier.

Now we'll append a universal '_info' to such structure
names, while including the names of those /proc pseudo
files where possible. In any case, that context struct
will *always* begin with the actual module/header file
name. And only the following two sound a little weird!

---------> 'meminfo_info' + 'slabinfo_info' <---------

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-26 20:47:34 +10:00
Jim Warner
220236a9af library: some minor miscellaeous improvements, 3rd gen
A collection of miscellaneous code and comment tweaks.

[ such changes will stop when desk checking ends too ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-17 08:49:48 +10:00
Jim Warner
80ad63dc31 library: refactor exposed pointers management, 3rd gen
This commit brings all of those 'fetch' type functions
(supporting some form of 'reap') into closer alignment
with one another. The biggest impact is to be found in
the <stat> module, which now provides for the separate
copy of stack pointers which will be exposed to users.

The reason such a copy was not employed initially with
<stat>, unlike those for <pids> and <slabinfo>, is due
to the fact that such stacks were never sortable. Thus
the original raw consolidated extent pointers wouldn't
have been disturbed. But that meant no NULL delimiter.

So with this commit, all reap/fetch operations now use
pointer copies when returning results to callers. And,
all such arrays are now NULL delimited meaning callers
can choose their own access fencepost: totals or NULL.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-02 16:33:01 +10:00
Jim Warner
4fe52ccd44 library: reduce copies of items to minimum, <STAT> api
This commit will consolidate the three separate copies
of the item enumerators currently supporting that reap
function (summary, cpus & nodes) into one shared copy.

That select function will continue to maintain its own
dedicated items copy, albeit via a new item structure.

[ and while we're at it, we'll move the 'select' guy ]
[ to its proper alphabetical place, after our 'reap' ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-02 16:33:01 +10:00
Jim Warner
eff9fbc06e library: standardize extents_free_all() logic, 3rd gen
As those 3rd generation newlib APIs evolved so too did
the extents_free_all() function. Most versions of this
function required the callers to first verify that the
extents anchor wasn't empty, which was poor etiquette.

This simple function should have been much more robust
and forgiving. With this commit, it fnally becomes so.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-02 16:33:01 +10:00
Jim Warner
ddb4754b33 library: partial revert of that numa 'fix', <STAT> api
This patch represents the partial revert of the commit
referenced below. And, so that yours truly (the author
for goodness sake) doesn't shoot his tootsies again in
the future, a cautionary programmer comment was added.

Reference(s):
commit dea4033418

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-28 21:11:25 +10:00
Jim Warner
8c7f89ad8d library: <STAT> api, change for that 'get' return type
The following commit message is shared with 4 patches.
------------------------------------------------------

Under the newlib interface most of our 'get' functions
represent a bit of a compromise in that the actual raw
values are coerced into one (probably ok) return type.

That approach creates the possibility of truncation at
best, and wouldn't serve future needs should something
other than numeric data be added to the 'get' results.

This commit trades the current compromise for a return
value guaranteed to satisfy all future needs, namely a
pointer to a particular api's specific results struct.

The impact on existing programs is minimal, especially
when using a new supplied macro. Otherwise, native 'C'
syntax could be used, but may feel somewhat unnatural.

[ as an aside, this new approach allows us to delete ]
[ all 'getsfunc' table entries & the supporting code ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-21 20:58:09 +10:00
Jim Warner
dea4033418 library: bug fix if libnuma.so unavailable, <STAT> api
All our numa logic was well encapsulated under #ifndef
NUMA_DISABLE (as ./configure --disable-numa), with the
exception of 1 case label. The reason it didn't create
any problems is because the sole consumer (top) itself
responded to the presence of #define NUMA_DISABLE too.

But if that option wasn't used, an oops still awaited.

When experimenting with a 32-bit library plus a 64-bit
kernel, a bug was revealed should the numa library not
have been found. Our 'reap' function must tolerate the
potential of a 0 return from that stacks_fetch_tics().

Now, if numa is desired but not possible, we'll be ok.

[ and, we'll build numa history from fresher sources ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-21 20:58:09 +10:00
Jim Warner
4a0e974b7f library: more tweaks for code and/or comments, 3rd gen
Following is a summary of significant changes (if any)
to each of these now upgraded 3rd gen library modules.

<meminfo> ............................................
. eliminated duplicate decl of 'struct procps_meminfo'
. standardized/normalized results struct union members
. added 'std' & 'var' dividers in .c file, like <pids>
. how did i miss relocating all these friggin' #undefs
. cleanup 'get' return logic (remove a redundant 'if')

<pids> ...............................................
. repositioned the procps_pidsinfo structure in header
. removed the extra trailing comma from enum pids_item
. standardized/normalized results struct union members

<slabinfo> ...........................................
. corrected comment typo (jeeze, in an 'aligned' para)
. standardized/normalized results struct union members
. added 'std' & 'var' dividers in .c file, like <pids>
. removed an obsolete #undef from procps_slabinfo_sort
. cleanup 'get' return logic (remove a redundant 'if')

<stat> ...............................................
. how did i miss relocating all these friggin' #undefs
. corrected an initialization fencepost used with numa <=== see Craig, here's a bug fix
. removed the extra trailing comma from enum stat_item
. standardized/normalized results struct union members
. added 'std' & 'var' dividers in .c file, like <pids>
. strengthen those parm checks in procps_stat_get func
. cleanup 'get' return logic (remove a redundant 'if')

<vmstat> .............................................
. standardized/normalized results struct union members
. added 'std' & 'var' dividers in .c file, like <pids>
. cleanup 'get' return logic (remove a redundant 'if')

[ virtually all of these tweaks reflect the author's ]
[ continuing pursuit of an unreasonable goal -- that ]
[ of a 'perfect' (plus 'pretty') C language program! ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-17 21:44:29 +10:00
Jim Warner
876ec555c3 library: final tweaks to code and/or comments, 3rd gen
With the dust now settling on all those 3rd generation
upgrades, this patch tries to provide some consistency
among the separate modules involved. Someday we should
consider a 4th generation where all redundant code has
been removed and isolated in a new shared source file.

Following is a summary of significant changes (if any)
to each of these now upgraded 3rd gen library modules.

<meminfo> ............................................
. strictly formatting/comment changes, code unaffected

<pids> ...............................................
. replaced a local mkSTR macro with existing STRINGIFY
. added fetch narrative explaining duplicate addresses

<slabinfo> ...........................................
. rearranged some free logic for procps_slabinfo_unref
. added fetch narrative explaining duplicate addresses

<stat> ...............................................
. added #define ENFORCE_LOGICAL, just as in <slabinfo>
. replaced a local mkSTR macro with existing STRINGIFY
. alphabetized the function declarations in the header

<vmstat> .............................................
. made one coverity concession with read_vmstat_failed

[ several of these changes may reflect this author's ]
[ continuing pursuit of an unreasonable goal -- that ]
[ of a 'perfect' (plus 'pretty') C language program! ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-13 10:33:37 +10:00
Jim Warner
335cbc2e61 library: make struct name more descriptive, <STAT> api
After normalizing the <SLABINFO> module, much of which
was based on this module, a structure which is crucial
to concurrent select/reap support is renamed the same.

Such a need for concurrent support was revealed during
slabtop testing. That program requests (select) global
data after calling for individual node data (reap) but
before those stacks have been accessed. Therefore, one
set of 'items'/'extents' could not possibly be shared.

So now we will know the former struct fetch_support as
ext_support. The former name was potentially confusing
since the struct was used by both 'select' and 'reap'.
However, only 'reap' ever called the 'fetch' function.

[ this <STAT> already accommodated concurrent usage. ]
[ in fact it contains 3 separate sets of items/exts. ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-09 20:51:06 +10:00
Jim Warner
2aaae6f29b library: improve internal 'get' processing, <STAT> api
With an eye to the future, rather than managing a long
switch/case construct in the procps_stat_get function,
we'll adopt the approach used in the <meminfo> module.

By making 'get' processing table driven too, just like
'select' is already, that may ease future maintenance.

Along the way a rather large boo-boo was fixed dealing
with that /proc/stat 'procs_running' field which crept
in with the commit referenced below. It wasn't spelled
correctly and thus was never captured as PROC_RUNNING.

Reference(s):
commit abc71a46ad

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-07 21:04:43 +10:00
Jim Warner
fac5e6fea0 library: allow negative delta values for 2, <STAT> api
A recent buglet in the <meminfo> interface, where many
delta values could legitimately be negative, suggested
a review of this module where a minus was forced to 0.

As it turns out, there are two delta items that indeed
could be negative. They involve the current processes.

So henceforth, DELTA_PROC_BLOCKED & DELTA_PROC_RUNNING
will now be allowed to go negative. I believe that all
other items can only grow. But, if we find more later,
at least the adaptation approach has been established.

[ this whole business of checking for less than zero ]
[ harks back to an old kernel anomaly where negative ]
[ tics were sometimes experienced. top was affected. ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-12 21:13:47 +10:00
Jim Warner
5ec5002b0d library: lift item restrictions on 'get()', <STAT> api
In the commit referenced below it was acknowledged the
procps_stat_get() function will intentionally restrict
returned values by excluding DELTA items among others.

Upon reflection that decision seemed rather arbitrary,
and so has now been lifted. And, while the initial use
of a DELTA will return 0, subsequent calls to that get
function will now return the difference (providing one
second, at least, has elapsed between any such calls).

Reference(s):
. reference to design decisions
commit abc71a46ad

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-12 07:51:10 +10:00
Jim Warner
1417ba56b5 library; add more of my gratuitous changes, <STAT> api
This commit is just my usual tweaking after an initial
submission, once the dust has settled & some more desk
checking was performed. Here are the changes included:

. get function need not check the 'stat_was_read' flag
( first time in save_sec == 0 so branch always taken )

. some table logic appeared outside the proper section
. cleanup_stack's loop made to work like assign_result
. eliminated an include of procps.h from stat.h header
. removed 'ext_numitems' from the stacks_extent struct
. changed the alignment of three prototypes for stat.h
. reorganized the pointers for 'stacks_extents' struct
. improved types indentation in header for readability

. lastly, some really gratuitous changes made to align
- comments within that private 'stacks_alloc' function

Signed-off-by: Jim Warner <james.warner@comcast.net
2016-05-12 07:51:10 +10:00
Jim Warner
abc71a46ad library: improve/standardize one interface, <STAT> api
This commit represents a complete redesign of the stat
interface. Gone are the confusing 8 separate accessors
along with their 2 additional read functions. In their
place we have just 3 accessors, with no read required.

That old interface also suffered an inflexibility with
respect to structures.  Now we deal with an unchanging
standard 'result' struct enabling future changes where
the binary interface will no longer need to be broken.

And gone is that former unnecessary typedef, used when
dealing with jiffies. Now the standard C type is used.

Our new API also adds some brand new functionality. If
a caller plans to employ successive 'select' or 'reap'
invocations, then delta values are available (which is
actually only what that top program is interested in).

At some future point a 'sort' function could be easily
introduced to complement the 'reap' function. However,
I saw no need for it at present and so it was omitted.

There were several design decisions which everyone may
not agree with. In support I'll offer these rationals:

. The 'get' function returns a signed long long result
which means a potential loss of some significance. But
I felt the ability to distinguish actual errors (minus
values) from true zero results were worth such a risk.

. The DELTA item enumerators were also made signed and
smaller than their parents. And they are intentionally
grouped as last so as to emphasize those distinctions.

. The SYS type items were excluded from the new 'reap'
function. It would not make sense to duplicate them in
each results stack. They're limited to 'get'/'select'.

. By the same token, some items (DELTA, etc.) will not
be allowed under that 'get' routine. That function was
already open to significant internal overhead (through
subsequent calls like in vmstat.c). That is why it has
been limited via 1 second between reads of /proc/stat.

Lastly, when we finally get around to documenting this
interface there's a real potential toe stubber when it
comes to the numa node portion. The libnuma.so doesn't
really provide any means to retrieve the active nodes.
Thus, any total reported by <stat> is just the highest
node number plus one, as reported by the numa library.

Any unused/inactive nodes are identified through these
. PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID

By the same token after the STAT_REAP_CPUS_ONLY 'reap'
. PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID

Reference(s):
http://www.freelists.org/post/procps/newlib-stat-interface

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-08 21:12:22 +10:00
Jim Warner
3a48427d5d library: rename those readstat.c & h sources to 'stat'
In an attempt to normalize the 'stat' interface, we'll
first shed any reminders of the old readproc interface
by changing file names to be more descriptive & brief.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-04-26 22:27:16 +10:00