2015-07-11 10:30:00 +05:30
|
|
|
/*
|
2023-02-07 15:39:48 +05:30
|
|
|
* slabinfo.h - slab pools related declarations for libproc2
|
2015-07-11 10:30:00 +05:30
|
|
|
*
|
2023-02-08 11:30:00 +05:30
|
|
|
* Copyright © 2015-2023 Jim Warner <james.warner@comcast.net>
|
2023-02-07 15:39:48 +05:30
|
|
|
* Copyright © 2015-2023 Craig Small <csmall@dropbear.xyz>
|
2015-07-11 10:30:00 +05:30
|
|
|
*
|
|
|
|
|
* This library is free software; you can redistribute it and/or
|
|
|
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
|
|
|
* License as published by the Free Software Foundation; either
|
|
|
|
|
* version 2.1 of the License, or (at your option) any later version.
|
|
|
|
|
*
|
|
|
|
|
* This library is distributed in the hope that it will be useful,
|
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
|
|
* Lesser General Public License for more details.
|
|
|
|
|
*
|
|
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
|
|
|
* License along with this library; if not, write to the Free Software
|
|
|
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
|
|
|
*/
|
|
|
|
|
|
2016-09-28 20:40:10 +05:30
|
|
|
#ifndef PROCPS_SLABINFO_H
|
|
|
|
|
#define PROCPS_SLABINFO_H
|
2004-01-25 04:03:56 +05:30
|
|
|
|
2018-04-06 10:30:00 +05:30
|
|
|
#ifdef __cplusplus
|
library: add item origin (as comments) to header files
A lack of documentation seems to be the major obstacle
to releasing this new library. So, in an effort to get
the ball rolling again, this patch adds the origins of
each item as a comment to six of the new header files.
However, before reviewing how such changes may benefit
that documentation objective, it seemed appropriate to
first reflect on newlib's background & current status.
___________________________________________ BACKGROUND
Discussions about and work on a new library began back
in July 2012 but quickly died. After a lull of 2 years
those discussions were resumed in August 2014 but soon
died also (and no code survived the gitorious demise).
With those early discussions, the recommended approach
was to encapsulate all of the libprocps data offerings
in individual functions. When it came to extensibility
it was suggested we should rely on symbols versioning.
Unfortunately that approach would have made for a huge
Application Programming Interface virtually impossible
to master or even document. And, runtime call overhead
would have been substantial for ps and especially top.
So, an alternative design was sought but there were no
new suggestions/contributions via freelists or gitlab.
Thus, in spite of a lack of library design experience,
the procps-ng team (Craig & Jim) set out to develop an
alternative API, more concise and with lower overhead.
Reference(s):
. 07/01/2012, begin library design discussion
https://www.freelists.org/post/procps/Old-library-calls
. 08/12/2014, revival of library design discussion
https://www.freelists.org/post/procps/libprocs-redesign
_____________________________________ DESIGN EVOLUTION
Our newlib branch first appeared on June 14, 2015. And
our current API actually represents the 4th generation
during the past 3 years of evolution. First, there was
a basic 'new', 'get' and 'unref' approach, using enums
to minimize the proliferation of 'get' function calls.
Then, in anticipation of other programs like ps, where
multiple fields times multiple processes would greatly
increase the number of 'get' function calls, a concept
of 'chains' was introduced. This became generation #2.
Such 'chains' proved unnecessarily complex so 'stacks'
replaced them. This was considered the 3rd generation,
but too many implementation details were still exposed
requiring those users to 'alloc', 'read', 'fill', etc.
Finally, a 4th generation emerged representing several
refinements to standardize and minimize those exported
functions, thus hiding all implementation details from
the users. Lastly, handling of 'errno' was normalized.
Reference(s):
. 06/14/2015, revival of new API discussion
https://www.freelists.org/post/procps/The-library-API-again
. 06/24/2015, birth of the newlib branch
https://www.freelists.org/post/procps/new-library
. 06/29/2015, 2nd generation introduced 'chains'
https://www.freelists.org/post/procps/new-library,8
. 07/22/2015, 3rd generation introduced 'stacks'
https://www.freelists.org/post/procps/newlib-stacks-vs-chains
. 06/18/2016, 4th generation refinements begin
https://www.freelists.org/post/procps/newlib-generation-35
. 11/10/2017, 4th generation standardized 'errno'
https://www.freelists.org/post/procps/some-more-master-newlib-stuff
_______________________________________ CURRENT DESIGN
Central to this new design is a simple 'result' struct
reflecting an item plus its value (thanks to a union).
As a user option, these item structures can be grouped
into 'stacks', yielding many results with just 1 call.
Such a 'stack' can be seen as a variable length record
whose content/order is determined solely by the users.
Within that 'result' structure, the union has standard
C language types so there is never a doubt how a value
should be used in a printf statement. Given that linux
requires a least a 32-bit platform the only difference
in capacity surrounds 'long' integers. And, where such
types might be used, the 32-bit maximums are adequate.
The items themselves are simply enumerators defined in
the respective header files. A user can name any items
of interest then the library magically provides result
structure(s). The approach was proven to be extensible
without breaking the ABI (in commit referenced below).
The 6 major APIs each provide for the following calls:
. 'new' ---------> always required as the first call .
. 'ref' -------------------------> strictly optional .
. 'unref' --------> optional, if ill-behaved program .
. 'get' --------------------> retrieve a single item .
. 'select' ----------------> retrieve multiple items .
And the 'get' and 'select' functions provide for delta
results representing the difference between successive
get/select calls (or a 'new' then 'get/select' call).
For the <diskstats>, <pids>, <slabinfo> & <stat> APIs,
where results are unpredictable, a 'reap' function can
return multiple result structures for multiple stacks.
The <pids> API differs from others in that those items
of interest must be provided at 'new' or 'reset' time,
a function unique to this API. And the <pids> 'select'
function requires PIDs or UIDs which are to be fetched
which then operates as a subset of 'reap'. Lastly, the
'get' function is an iterator for successive PIDs/TIDs
returning items previously identified via 'new/reset'.
To provide assistance to users during development, the
special header 'proc/xtra-procps-debug.h' is available
to check type usage against library expectations. That
check is activated by including this header explicitly
or via build using: ./configure '-DXTRA_PROCPS_DEBUG'.
Reference(s):
. 08/05/2016, type validation introduced
https://www.freelists.org/post/procps/newlib-types-validation
commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f
. 08/11/2016, extensibility while preserving ABI example
https://www.freelists.org/post/procps/new-meminfo-fields
commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de
_________________________ INITIAL DOCUMENTATION EFFORT
The initial attempt, referenced below, dealt primarily
with the <pids> interface. Separate man pages for each
exported function were created. Plus there was another
document describing the items, among other miscellany.
Adopting such an approach encounters several problems:
1. In order to use these man pages, users are required
to already know how to use the library. Or alternately
one could randomly search each of them while trying to
ascertain which function call satisfies their need and
what exactly was the proper compliment/order required.
2. While we can explain what all of those <pids> items
represent, that certainly isn't true for all the APIs.
See the gaps in kernel documentation for <meminfo> and
complete lack of documentation with that <vmstat> API.
3. Our documentation effort should take pains to avoid
unnecessary implementation details. Here's an example:
. "The pointer to info will have memory"
. "allocated and a structure created."
Alternatively, the following conveys user requirements
while not offering any internal implementation detail:
. "You must provide the address of a NULL"
. "info structure pointer."
Reference(s):
. 01/04/2017, initial documentation offering
https://www.freelists.org/post/procps/Using-reap-and-get
commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0
___________________ RECOMMENDED DOCUMENTATION APPROACH
I recommend that the newlib documentation consist of 3
man pages only. The first would cover the 5 major APIs
and their common functions. The second would deal with
the <pids> API exclusively, explaining how it differs.
Any remaining exported libproc functions which are yet
to be included could be represented in a 3rd document.
For these new documents the following are are assumed:
1. Since we will not be able to document all items, we
shouldn't try to document any items. We should instead
rely on proc(5) or Documentation/filesystems/proc.txt.
2. Program development often involves referencing some
header file(s). So, make that an absolute requirement.
3. With the addition of item origins, represented with
this commit, and considering that 'types' were already
present, the header file might be all some users need.
4. And who knows, when a user of our libproc complains
about gaps in their documentation, it might prompt the
kernel folks to correct those long standing omissions.
To summarize, I suggest that we replace that libproc.3
document with a more general one explaining the basics
of accessing this new library and the common calls for
most of the major interfaces. We can then create a new
document (libproc-pids.3?), which explains differences
in using the <PIDS> application programming interface.
A final document (libproc-misc.3?) covers what's left.
Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
|
|
|
extern "C "{
|
2018-04-06 10:30:00 +05:30
|
|
|
#endif
|
2015-07-04 10:29:59 +05:30
|
|
|
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
enum slabinfo_item {
|
library: refactored some header file items and origins
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 96d59cbf46b3ff687bd29fad4708074a0e1cea14
. 01/2019, <stat> origins tweaked
commit 201e816b26ddaccc923ec40977c92037cdd0c34e
Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
|
|
|
SLABINFO_noop, // ( never altered )
|
|
|
|
|
SLABINFO_extra, // ( reset to zero )
|
|
|
|
|
// returns origin, see proc(5)
|
|
|
|
|
// ------- -------------------
|
|
|
|
|
SLAB_NAME, // str /proc/slabinfo
|
|
|
|
|
SLAB_NUM_OBJS, // u_int "
|
|
|
|
|
SLAB_ACTIVE_OBJS, // u_int "
|
|
|
|
|
SLAB_OBJ_SIZE, // u_int "
|
|
|
|
|
SLAB_OBJ_PER_SLAB, // u_int "
|
|
|
|
|
SLAB_NUMS_SLABS, // u_int "
|
|
|
|
|
SLAB_ACTIVE_SLABS, // u_int "
|
|
|
|
|
SLAB_PAGES_PER_SLAB, // u_int "
|
|
|
|
|
SLAB_PERCENT_USED, // u_int derived from ACTIVE_OBJS / NUM_OBJS
|
2023-04-11 15:22:24 +05:30
|
|
|
SLAB_SIZE_TOTAL, // ul_int derived from page size * NUMS_SLABS * PAGES_PER_SLAB
|
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-21 10:30:00 +05:30
|
|
|
|
library: refactored some header file items and origins
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 96d59cbf46b3ff687bd29fad4708074a0e1cea14
. 01/2019, <stat> origins tweaked
commit 201e816b26ddaccc923ec40977c92037cdd0c34e
Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
|
|
|
SLABS_CACHES_TOTAL, // u_int derived from all caches
|
|
|
|
|
SLABS_CACHES_ACTIVE, // u_int "
|
|
|
|
|
SLABS_NUM_OBJS, // u_int "
|
|
|
|
|
SLABS_ACTIVE_OBJS, // u_int "
|
|
|
|
|
SLABS_OBJ_SIZE_AVG, // u_int "
|
|
|
|
|
SLABS_OBJ_SIZE_MIN, // u_int "
|
|
|
|
|
SLABS_OBJ_SIZE_MAX, // u_int "
|
|
|
|
|
SLABS_NUMS_SLABS, // u_int "
|
|
|
|
|
SLABS_ACTIVE_SLABS, // u_int "
|
|
|
|
|
SLABS_PAGES_TOTAL, // u_int "
|
|
|
|
|
SLABS_SIZE_ACTIVE, // ul_int "
|
|
|
|
|
SLABS_SIZE_TOTAL, // ul_int "
|
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-21 10:30:00 +05:30
|
|
|
|
library: refactored some header file items and origins
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 96d59cbf46b3ff687bd29fad4708074a0e1cea14
. 01/2019, <stat> origins tweaked
commit 201e816b26ddaccc923ec40977c92037cdd0c34e
Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
|
|
|
SLABS_DELTA_CACHES_TOTAL, // s_int derived from above
|
|
|
|
|
SLABS_DELTA_CACHES_ACTIVE, // s_int "
|
|
|
|
|
SLABS_DELTA_NUM_OBJS, // s_int "
|
|
|
|
|
SLABS_DELTA_ACTIVE_OBJS, // s_int "
|
|
|
|
|
SLABS_DELTA_OBJ_SIZE_AVG, // s_int "
|
|
|
|
|
SLABS_DELTA_OBJ_SIZE_MIN, // s_int "
|
|
|
|
|
SLABS_DELTA_OBJ_SIZE_MAX, // s_int "
|
|
|
|
|
SLABS_DELTA_NUMS_SLABS, // s_int "
|
|
|
|
|
SLABS_DELTA_ACTIVE_SLABS, // s_int "
|
|
|
|
|
SLABS_DELTA_PAGES_TOTAL, // s_int "
|
|
|
|
|
SLABS_DELTA_SIZE_ACTIVE, // s_int "
|
|
|
|
|
SLABS_DELTA_SIZE_TOTAL // s_int "
|
2015-07-04 10:29:59 +05:30
|
|
|
};
|
|
|
|
|
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
enum slabinfo_sort_order {
|
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-21 10:30:00 +05:30
|
|
|
SLABINFO_SORT_ASCEND = +1,
|
|
|
|
|
SLABINFO_SORT_DESCEND = -1
|
2004-01-25 04:03:56 +05:30
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
struct slabinfo_result {
|
|
|
|
|
enum slabinfo_item item;
|
2015-07-11 10:30:00 +05:30
|
|
|
union {
|
2016-06-14 10:30:00 +05:30
|
|
|
signed int s_int;
|
|
|
|
|
unsigned int u_int;
|
|
|
|
|
unsigned long ul_int;
|
|
|
|
|
char *str;
|
2015-07-11 10:30:00 +05:30
|
|
|
} result;
|
2015-07-04 10:29:59 +05:30
|
|
|
};
|
|
|
|
|
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
struct slabinfo_stack {
|
|
|
|
|
struct slabinfo_result *head;
|
|
|
|
|
};
|
2015-07-11 10:30:00 +05:30
|
|
|
|
2020-06-19 10:30:00 +05:30
|
|
|
struct slabinfo_reaped {
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
int total;
|
|
|
|
|
struct slabinfo_stack **stacks;
|
|
|
|
|
};
|
2015-07-11 10:30:00 +05:30
|
|
|
|
2021-12-15 11:30:00 +05:30
|
|
|
struct slabinfo_info;
|
|
|
|
|
|
2015-07-11 10:30:00 +05:30
|
|
|
|
2016-08-06 21:41:11 +05:30
|
|
|
#define SLABINFO_GET( info, actual_enum, type ) ( { \
|
|
|
|
|
struct slabinfo_result *r = procps_slabinfo_get( info, actual_enum ); \
|
|
|
|
|
r ? r->result . type : 0; } )
|
2016-06-18 10:30:00 +05:30
|
|
|
|
2016-08-05 10:30:00 +05:30
|
|
|
#define SLABINFO_VAL( relative_enum, type, stack, info ) \
|
2016-06-18 10:30:00 +05:30
|
|
|
stack -> head [ relative_enum ] . result . type
|
2015-07-11 10:30:00 +05:30
|
|
|
|
|
|
|
|
|
2016-07-21 10:30:00 +05:30
|
|
|
int procps_slabinfo_new (struct slabinfo_info **info);
|
|
|
|
|
int procps_slabinfo_ref (struct slabinfo_info *info);
|
|
|
|
|
int procps_slabinfo_unref (struct slabinfo_info **info);
|
2015-07-11 10:30:00 +05:30
|
|
|
|
2016-06-18 10:30:00 +05:30
|
|
|
struct slabinfo_result *procps_slabinfo_get (
|
2016-07-21 10:30:00 +05:30
|
|
|
struct slabinfo_info *info,
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
enum slabinfo_item item);
|
2015-07-11 10:30:00 +05:30
|
|
|
|
2020-06-19 10:30:00 +05:30
|
|
|
struct slabinfo_reaped *procps_slabinfo_reap (
|
2016-07-21 10:30:00 +05:30
|
|
|
struct slabinfo_info *info,
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
enum slabinfo_item *items,
|
|
|
|
|
int numitems);
|
2015-07-11 10:30:00 +05:30
|
|
|
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
struct slabinfo_stack *procps_slabinfo_select (
|
2016-07-21 10:30:00 +05:30
|
|
|
struct slabinfo_info *info,
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
enum slabinfo_item *items,
|
|
|
|
|
int numitems);
|
2015-07-11 10:30:00 +05:30
|
|
|
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
struct slabinfo_stack **procps_slabinfo_sort (
|
2016-07-21 10:30:00 +05:30
|
|
|
struct slabinfo_info *info,
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
struct slabinfo_stack *stacks[],
|
2015-07-21 10:30:00 +05:30
|
|
|
int numstacked,
|
library: normalize/standardize the i/f, <SLABINFO> api
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>
2016-06-05 10:30:00 +05:30
|
|
|
enum slabinfo_item sortitem,
|
|
|
|
|
enum slabinfo_sort_order order);
|
2015-07-04 10:29:59 +05:30
|
|
|
|
2018-09-01 10:30:00 +05:30
|
|
|
|
|
|
|
|
#ifdef XTRA_PROCPS_DEBUG
|
2020-07-25 10:30:00 +05:30
|
|
|
# include "xtra-procps-debug.h"
|
2018-09-01 10:30:00 +05:30
|
|
|
#endif
|
2018-04-06 10:30:00 +05:30
|
|
|
#ifdef __cplusplus
|
|
|
|
|
}
|
|
|
|
|
#endif
|
2016-09-28 20:40:10 +05:30
|
|
|
#endif
|
