Even though we we had to abandon the master branch top
multi-thread effort and even though the newlib version
of a multi-threaded top provides no real benefit, that
whole exercise was not wasted. Rather, it has revealed
some deficiencies in our library which this addresses.
If two or more threads in the same address space tried
to access the same api simultaneously, there is a good
chance some function-local static variables will yield
some of those renowned unpredictable results. So, this
patch protects them with the '__thread' storage class.
Reference(s):
https://www.freelists.org/post/procps/a-few-more-patches,7
Signed-off-by: Jim Warner <james.warner@comcast.net>
With the way those 'extents_free_all' guys were coded,
there's no real need to check for a NULL this->extents
before calling 'em. That's how <stat> already does it.
Signed-off-by: Jim Warner <james.warner@comcast.net>
In addition to copyright date, the initial descriptive
line was changed from a generic statement to one which
reflects the specific portion of the proc/ filesystem.
[ such descriptions alternate between 'declarations' ]
[ (h files) & corresponding 'definitions' (c files). ]
Also, a few missing copyright attributions were added.
Signed-off-by: Jim Warner <james.warner@comcast.net>
There's a huge toe-stubber awaiting future maintenance
as reflected in that commit below which deals with the
addition of new enumerators to the Item_table. Namely,
whenever the table is grown, one must remember to also
change that existing 'logical_end' enumerator's value.
Well, not anymore! Since that MAXTABLE macro was added
to the procps-private.h header we can now also exploit
it so a 'logical_end' automatically tracks table size.
This change also renders some code associated with the
ITEMTABLE_DEBUG #define unnecessary. So it's gone too.
Reference(s):
. 08/2016, add new enumerators
commit 09e1886c9e
. 08/2020, added MAXTABLE macro
commit c865b06c30
. 08/2020, introduced ITEMTABLE_DEBUG
commit 92d0297e1e
Signed-off-by: Jim Warner <james.warner@comcast.net>
The recent work on updating the <meminfo> and <vmstat>
modules with some newly added linux fields reminded me
(again) of a need for some mechanism guaranteeing that
a header file agrees with the source file assumptions.
Sadly, in the past, if a table entry was omitted or if
the table and header are ordered differently, then the
library would silently return the wrong results values
or even potentially experience a SIGSEGV abnormal end.
This patch offers a much needed development assist for
ensuring that Item_table entries are synchronized with
header file enumerators in terms of number plus order.
It's intended solely for our use as libprocps evolves.
Now, by activating ITEMTABLE_DEBUG, either directly or
via ./configure CFLAGS='-DITEMTABLE_DEBUG', the number
and order will be verified. It is envisioned that this
feature will be used at least once prior to a release.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch just trades the 'typestr' for the much more
meaningful 'valid range' when a relative enum has been
deemed invalid under that XTRA_PROCPS_DEBUG provision.
[ and we'll also make one comment a bit more generic ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
In preparation for a documentation attempt, this patch
renames 'struct reap' to 'struct reaped' in two of our
interfaces. That will bring all the non-pid interfaces
into agreement since the <stat> api already used that.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch just standardizes/normalizes the whitespace
employed within a couple of nearly identical #defines.
Signed-off-by: Jim Warner <james.warner@comcast.net>
Some parts of our newlib implementation are the result
of functions which have been propagated from module to
module. In particular, those 'cleanup_stacks' routines
are all similar & likely originated in the <pids> api.
In that interface there was a need to free dynamically
acquired memory before the result structure was reused
to satisfy subsequent 'get', 'select' or 'reap' calls.
This, in turn, led to a concept of 'dirty' stacks with
the need to call one of two 'cleanup_stack' functions.
None of the remaining interfaces deal with such memory
yet they each had their own 'cleanup_stack' functions.
Those functions were responsible for resetting each of
the result unions to zero, excluding any 'noop' items.
The bottom line is that for all interfaces, repetitive
calls would require iterating through the stack(s) two
separate times: once to 'cleanup' another to 'assign'.
With this commit we will reduce iterations to just the
'assign' routine. A reset to zero will be accomplished
in the 'extra' item set routine (which is the only one
actually requiring any reset). All other items will be
reinitialized automatically by a new current set value
or upon reallocation when an items compliment changes.
In the <pids> interface, any freeing of dynamic memory
could have been accomplished by adding that 'freefunc'
check to the 'assign' function. However, that requires
an Item_table test with every item. Instead, we'll now
satisfy such needs as the very first step in those set
functions responsible for dynamically acquired memory.
[ the <pids> api retains 2 'cleanup_stack' functions ]
[ to accommodate stack(s) 'reset' & to serve 'unref' ]
Lastly, all the 'itemize_stack' functions were tweaked
by eliminating an unnecessary initialization of result
unions. That objective was already accomplished by the
calloc() in a 'stacks_alloc' function or the remaining
'cleanup_stack' routine found in the <pids> interface.
Signed-off-by: Jim Warner <james.warner@comcast.net>
These changes are an outgrowth of the research/testing
behind the previous commit. There is no commingling of
select/reap stacks in interfaces beyond the <pids> api
since there's no need to support any 'reset' function.
However, those <pids> changes prompted a review of all
interfaces offering that 'stacks_fetch' function, thus
revealing 2 instances of useless logic/wasted efforts.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit is intended as a refinement of the patches
mentioned below, where origins/sources of newlib items
were added to the header files for user documentation.
However, if those additions are to be truly effective,
along with kernel documentation (where available), the
following prerequisites must also have been satisfied:
. our identifiers closely align with linux field names
. our derived items are documented or self-documenting
Satisfying those prerequisites prompted this patch and
for these changes, kernel sources were emphasized over
available documentation (shame on me, it should always
have been so). And, while some 'new' fields were found
to be conditional, they were included unconditionally.
These changes appear more extensive than they actually
need be since I have attempted to enforce some spacing
conventions. So, I've summarize the significant things
in the sections that follow. For a proper perspective,
use: 'git diff --ignore-space-change' (good as alias).
___________________________________________ <PIDS> api
This api is unique in that there exists many different
file/directory origins subordinate to /proc/<pid>. And
our item identifiers are sometimes coerced so as to be
able to group related or similar enumerators together.
So, users needed more help relating our identifiers to
an actual documented field. Thus, we will now also add
the field names as with 'stat: delayacct_blkio_ticks'.
Each item ending with a '_C' now consistently includes
both the parent's count/time plus waited for children.
That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT
since its original name is an implementation artifact.
___________________________________________ <STAT> api
The only api change was to correct a typo ('dervied').
_________________________________________ <VMSTAT> api
Even ignoring white space, this interface received the
largest number of changes. Mostly, this was because of
deficiencies in the proc(5) documentation. Recall that
this documentation already sorely lacks any substance.
Usually, just kernel releases are noted, not contents.
When compared to kernel source, that proc(5) contained
many non-existent fields and also omitted many others.
________________________________________ <MEMINFO> api
Sadly, with this api many of the changes were simply a
correction of some earlier 'human error' where several
fields where hashed then tracked but never represented
with an item enumerator in this meminfo.h header file.
_______________________________________ <SLABINFO> api
The 'SLABS' (summary) & 'SLABNODE' items were reversed
since the former are derived from the separate caches.
More significantly, those 'SLABNODE' guys were renamed
to 'SLAB' since they concern individual caches and the
concept of 'nodes' is really an implementation detail.
Also, several enumerators were changed to more closely
agree with official slabinfo(5) documentation referred
to in what we're treating as a base document: proc(5).
Lastly, while those 'SLABS' items are solely a product
of our library and not represented in slabinfo(5), the
names attempt to parallel those found as 'SLAB' items.
______________________________________ <DISKSTATS> api
One enumeration identifier was changed so as to better
reflect its relationship to that actual documentation:
'Documentation/iostats.txt', as referenced in proc(5).
Reference(s):
. 12/2018, item origins added (and commit msg history)
commit 96d59cbf46
. 01/2019, <stat> origins tweaked
commit 201e816b26
Signed-off-by: Jim Warner <james.warner@comcast.net>
Rather than offer three separate patches, they've been
consolidated in this single commit. All are related in
that they surfaced while preparing a subsequent patch.
------------------------------------------------------
library: correct a broken '#if define', <SLABINFO> api
It was introduced (embarrassingly) in the patch below.
Reference(s):
commit 97d078a9af
------------------------------------------------------
library: correct a broken 'GET' macro, <DISKSTATS> api
In the patch referenced below, which purported to make
all the 'GET' macros robust, the 'DISKSTATS_GET' macro
was broken. A necessary parameter wasn't passed to the
subsequently invoked function: procps_diskstats_get().
Reference(s):
commit bef8c7fb70
------------------------------------------------------
library: correct a broken 'sort' func, <DISKSTATS> api
In the commit shown below, an attempt to normalize the
errno handling, the sort function inadvertently lost 1
crucial line of code which produces a consistent SEGV.
Reference(s):
commit 06be33b43e
Signed-off-by: Jim Warner <james.warner@comcast.net>
In proc/slab.c, functions parse_slabinfo20() and parse_slabinfo11(),
sscanf() might overflow curr->name, because "String input conversions
store a terminating null byte ('\0') to mark the end of the input; the
maximum field width does not include this terminator."
Add one byte to name[] for this terminator.
---------------------------- adapted for newlib branch
. file is now proc/slabinfo.c (not .h)
. manifest constant renamed SLABINFO_NAME_LEN
. older parse_slabinfo11() function no longer present
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit removes some obsolete parameter validation
code which was needed back when certain functions were
public, called directly by users (1st/2nd generation).
Now that they're static they can be safely eliminated.
Signed-off-by: Jim Warner <james.warner@comcast.net>
With older library logic having been modified to avoid
using those potentially deadly alloc.h routines, while
improving 'errno' handling, we're ready to standardize
and enhance newlib's approach to any potential errors.
In so doing, we'll establish the following objectives:
. . . . . . . . . . . . . functions returning an 'int'
. an error will be indicated by a negative number that
is always the inverse of some well known errno.h value
. . . . . . . . . . . functions returning an 'address'
. any error will be indicated by a NULL return pointer
with the actual reason found in the formal errno value
And, when errno is manipulated directly we will strive
to do so whenever possible within those routines which
have been declared with PROCPS_EXPORT. In other words,
in the user callable functions defined in source last.
[ But, that won't always be possible. In particular, ]
[ all the 'read_failed' functions will sometimes set ]
[ 'errno' so that they can serve callers returning a ]
[ NULL or an int without duplicating a lot of logic. ]
[ Also, that includes one subordinate function which ]
[ was called by 'read_failed' in the <slabinfo> API. ]
------------------------------------------------------
Along the way, several additional miscellaneous issues
were addressed. They're listed here now for posterity.
. the '-1' return value passed outside the library was
eliminated since it would erroneously equate to -EPERM
. the stacks_fetch functions in <diskstats> and <stat>
weren't checked for their possible minus return values
. hash create was not checked in <meminfo> or <vmstat>
. fixed 'new' function faulty parm check in <slabinfo>
Signed-off-by: Jim Warner <james.warner@comcast.net>
. ensure whitespace exists between the code & comments
[ changing txt slightly keeps right margin alignment ]
. strive for more consistency with some comment styles
[ don't use C '/*' style where C++ '//' style exists ]
. removed the instance of double space in 1 assignment
[ still striving for consistency in whitespace usage ]
. fixed comment relating to number of 'derived fields'
[ the <meminfo> api recently added one new such enum ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
For each of those interfaces employing a priming read,
all the other 'read' functions begin with the module's
name except this guy which began with 'read_slabinfo'.
Now, they'll all begin with their module name then end
the same with a '_read_failed' boolean hinting suffix.
Signed-off-by: Jim Warner <james.warner@comcast.net>
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>
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>
The <slabinfo> header provides 3 groups of enumerators
with prefixes of SLABINFO, SLABS & SLABNODE. The first
is strictly user oriented & isn't supported internally
by any structure. The other two, however, have structs
associated with 'em but, unfortunately, 1 is misnamed.
The 'struct slabs_node' is associated with 'nodes' and
supports the enumerators with the SLABNODE prefix. But
the 'struct slabs_hist' was associated with 'hist' yet
supports those enumerators with just the SLABS prefix.
We do not care very much what some structure is called
but we do care about an identifier used manipulate it.
This patch will trade the 'hist' identifier associated
with 'struct slabs_hist' for a more congruous 'slabs'.
[ it's awful when the author can't remember what the ]
[ true meaning of an identifier is after creating it ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
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>
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>
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>
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>
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>
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>
. a more appropriate error return code was substituted
. a safer form of comparison is utilized in two places
. a STAT_VAL macro replaced by more proper MEMINFO_VAL
. several of the silly 'xerrx' formats had been missed
. a few whitespace changes have also been incorporated
Signed-off-by: Jim Warner <james.warner@comcast.net>
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>
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>
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>
Yes, all of these changes are strictly cosmetic. It is
likely symptomatic of some deep-seated character flaw.
[ or, it might be because of a certain pride in this ]
[ new library and the desire to make it even better! ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
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>
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>
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>
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>
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>
Needless to say, when one copies and then pastes, it's
always better when those results are refined somewhat.
The qsort callback declarations used the wrong results
type and 2 of their 3 input parameters were wrong too.
So this patch will fix that & generalize declarations.
[ plus add comment guidance about noop & extra enums ]
[ & provide for 'noop' sorting, as is done in <PIDS> ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
Before this major redesign, the slabs interface likely
was our messiest 2nd generation attempt at opaqueness.
Beyond the standard 'new', 'ref' & 'unref', there were
a total of 12 exported functions. Now, there are four.
The 1st step was to remove several of those functions.
These were quick to go since they were not used (yet):
. procps_slabnode_count
. procps_slabnode_getname
. procps_slabnode_getstack
Then, the following were internalized so users needn't
be burdened with implementation details in the future:
. procps_slabinfo_read (renamed: read_slabinfo_failed)
. procps_slabnode_stacks_alloc (renamed: stacks_alloc)
Still others evolved into the minimal interface we had
strived for in the other upgraded 3rd generation APIs:
. procps_slabnode_get -----------> procps_slabinfo_get
. separate stack_alloc/fill --> procps_slabinfo_select
. separate stacks_alloc/fill ---> procps_slabinfo_reap
. procps_slabnode_stacks_sort --> procps_slabinfo_sort
------------------------------------------------------
Beyond those reductions, the major modifications were:
. This API tries to be as forgiving as possible and as
such won't throw errors when a caller request makes no
sense. For example, if a 'get' or 'select' requested a
SLABNODE item (with no current means to id that node),
results will be zero. By the same token, should 'reap'
include a global SLABS item (meaning those values will
be duplicated in *every* node stack) it'll be allowed.
. If the above behavior is undesired, a new #define of
ENFORCE_LOGICAL can be used to restrict certain items.
. Permission problems will now be caught at 'new' time
thanks to a priming 'read' call. That read also serves
to make DELTA values potentially useful at 1st access.
. Separate slab/slabnode enumerators were consolidated
into one, simplifying validation & the results struct.
. Several internal parameter checks were relaxed since
they were already checked by the caller. Besides if we
cannot trust our own code we might as well hang it up.
. That sort provision was made more efficient and will
offer the ascending choice, in addition to descending.
------------------------------------------------------
Lastly, some additional thoughts regarding the future:
. It would not be difficult to expand 'select' to also
accept a nodeid, or to clone it as 'select_node'. And,
should the same be extended to 'get', a results struct
could be returned instead of signed long accommodating
the extra data type(s) like a node name (string data).
. The 'get' function is not currently affected by that
define ENFORCE_LOGICAL. However, at some future point
perhaps -EINVAL would be more appropriate than a zero.
Signed-off-by: Jim Warner <james.warner@comcast.net>
Where possible, libprocps files convey the name of the
actual source pseudo file under the '/proc' directory.
This patch brings slab into line with such a standard.
Signed-off-by: Jim Warner <james.warner@comcast.net>
