emo/procps
1
0
Fork 0
Code Issues Pull Requests Packages Releases Activity
e782b1d859
procps/proc/stat.h

174 lines
5.9 KiB
C
Raw Normal View History

library: sysstat and vmstat api changes Use the standard libc declarations. For protecting the headers for C++ procps used to have its own defines, this change makes them use the standard libc ones. getstat() -> procps_stat_* vminfo() -> procps_vmstat_* These two components of the library now use the newer version of the API with less exposed global variables. The old methods are there for now. Signed-off-by: Craig Small <csmall@enc.com.au>
2015-06-20 03:13:02 +05:30
/*
library: update those source files for copyright dates 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>
2021-02-05 11:30:00 +05:30
* stat.h - cpu/numa related declarations for libprocps
*
* Copyright (C) 2015 Craig Small <csmall@dropbear.xyz>
* Copyright (C) 2015-2021 Jim Warner <james.warner@comcast.net>
library: sysstat and vmstat api changes Use the standard libc declarations. For protecting the headers for C++ procps used to have its own defines, this change makes them use the standard libc ones. getstat() -> procps_stat_* vminfo() -> procps_vmstat_* These two components of the library now use the newer version of the API with less exposed global variables. The old methods are there for now. Signed-off-by: Craig Small <csmall@enc.com.au>
2015-06-20 03:13:02 +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
*/
library; add more of my gratuitous changes, <STAT> api This commit is just my usual tweaking after an initial submission, once the dust has settled & some more desk checking was performed. Here are the changes included: . get function need not check the 'stat_was_read' flag ( first time in save_sec == 0 so branch always taken ) . some table logic appeared outside the proper section . cleanup_stack's loop made to work like assign_result . eliminated an include of procps.h from stat.h header . removed 'ext_numitems' from the stacks_extent struct . changed the alignment of three prototypes for stat.h . reorganized the pointers for 'stacks_extents' struct . improved types indentation in header for readability . lastly, some really gratuitous changes made to align - comments within that private 'stacks_alloc' function Signed-off-by: Jim Warner <james.warner@comcast.net
2016-05-10 10:30:00 +05:30
library: strictly cosmetic, absolutely no code changes This commit just contains some tweaks to comments plus a few adjustments to whitespace for alignment purposes and a normalization of the header inclusion #define's. [ plus a spelling error in one header file was fixed ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-09-28 20:40:10 +05:30
#ifndef PROCPS_STAT_H
#define PROCPS_STAT_H
library: sysstat and vmstat api changes Use the standard libc declarations. For protecting the headers for C++ procps used to have its own defines, this change makes them use the standard libc ones. getstat() -> procps_stat_* vminfo() -> procps_vmstat_* These two components of the library now use the newer version of the API with less exposed global variables. The old methods are there for now. Signed-off-by: Craig Small <csmall@enc.com.au>
2015-06-20 03:13:02 +05:30
library: replace the troublesome '__BEGIN_DECLS' macro When 'newlib' was introduced, in the commit referenced below, the use of that glibc '__BEGIN_DECLS' macro was standardized. However, as issue #88 revealed, this may result in a fatal build error with other environments. So, this patch just trades that macro for the standard '#ifdef __cplusplus' conventions (thus avoiding use of all those '#include <features.h>' directives as well). Reference(s): . newlib introduced commit a410e236abb47c7c43194e61d0566686f81513af . procps-ng-3.3.13 issue https://gitlab.com/procps-ng/procps/issues/88 . some additional discussion https://www.freelists.org/post/procps/PATCH-Replace-glibcspecific-macros-in-procnumah,1 . musl wiki (see: sys/cdefs.h error messages) https://wiki.musl-libc.org/faq.html Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-04-06 10:30:00 +05:30
#ifdef __cplusplus
extern "C" {
#endif
library: sysstat and vmstat api changes Use the standard libc declarations. For protecting the headers for C++ procps used to have its own defines, this change makes them use the standard libc ones. getstat() -> procps_stat_* vminfo() -> procps_vmstat_* These two components of the library now use the newer version of the API with less exposed global variables. The old methods are there for now. Signed-off-by: Craig Small <csmall@enc.com.au>
2015-06-20 03:13:02 +05:30
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
enum stat_item {
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
STAT_noop, // ( never altered )
STAT_extra, // ( reset to zero )
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
// returns origin, see proc(5)
// ------- -------------------
library: changes to some numa stuff in that <stat> api Now that we may be getting serious with documentation, that stat module was revisited with an eye toward user friendliness. Heck, even this author puzzled over some of the existing notes and naming conventions employed. So, this patch will adjust some identifiers and expand the notes to (hopefully) better serve potential users. The most significant change was making the STAT_TIC_ID always valid for numa nodes, even if any are inactive. Thus the -22222 special STAT_NODE_INVALID constant now is applied only to STAT_TIC_NUMA_NODE. It will be used on the cpu summary and reaps with STAT_REAP_CPUS_ONLY. And it will also mark any numa node that was inactive. Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-24 10:30:00 +05:30
STAT_TIC_ID, // s_int /proc/stat, cpu or numa node id
STAT_TIC_NUMA_NODE, // s_int [ CPU ID based, see: numa(3) ]
library: improve header file item comments, <STAT> api This patch just polishes the 'origin' comments for the <STAT> header file. In particular those derived/unique items (the 'SUM' guys) will now be properly explained. [ in order to employ the 'derived from above' phrase ] [ with their DELTA versions, all SUM items had to be ] [ relocated (and some renamed). in turn, that had an ] [ impact on many portions of the .c source file too. ] Reference(s): . summary calculations introduced commit 2c86c4984a15c9ab912402838c6651f466a3d2ed . origins added to header files commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-01-13 11:30:00 +05:30
STAT_TIC_NUM_CONTRIBUTORS, // s_int [ total CPUs contributing to TIC counts ]
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
STAT_TIC_USER, // ull_int /proc/stat
STAT_TIC_NICE, // ull_int "
STAT_TIC_SYSTEM, // ull_int "
STAT_TIC_IDLE, // ull_int "
STAT_TIC_IOWAIT, // ull_int "
STAT_TIC_IRQ, // ull_int "
STAT_TIC_SOFTIRQ, // ull_int "
STAT_TIC_STOLEN, // ull_int "
STAT_TIC_GUEST, // ull_int "
STAT_TIC_GUEST_NICE, // ull_int "
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
STAT_TIC_DELTA_USER, // sl_int derived from above
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
STAT_TIC_DELTA_NICE, // sl_int "
STAT_TIC_DELTA_SYSTEM, // sl_int "
STAT_TIC_DELTA_IDLE, // sl_int "
STAT_TIC_DELTA_IOWAIT, // sl_int "
STAT_TIC_DELTA_IRQ, // sl_int "
STAT_TIC_DELTA_SOFTIRQ, // sl_int "
STAT_TIC_DELTA_STOLEN, // sl_int "
STAT_TIC_DELTA_GUEST, // sl_int "
STAT_TIC_DELTA_GUEST_NICE, // sl_int "
library: improve header file item comments, <STAT> api This patch just polishes the 'origin' comments for the <STAT> header file. In particular those derived/unique items (the 'SUM' guys) will now be properly explained. [ in order to employ the 'derived from above' phrase ] [ with their DELTA versions, all SUM items had to be ] [ relocated (and some renamed). in turn, that had an ] [ impact on many portions of the .c source file too. ] Reference(s): . summary calculations introduced commit 2c86c4984a15c9ab912402838c6651f466a3d2ed . origins added to header files commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-01-13 11:30:00 +05:30
STAT_TIC_SUM_USER, // ull_int derived from USER + NICE tics
library: tweak those system cpu statistics, <stat> api This patch may be a little misleading in terms of size since most of the changes just reorder a little logic. The most significant changes involve two GUEST values. My original implementation excluded such tics from the TOTAL calculation and, therefore, the BUSY figure too. That decision was erroneously based on some code found in ./kernel/sched/cputime.c which in hindsight applies only to processes, not those system level cpu figures. [ another likely oops classified STOLEN tics as IDLE ] So, this patch attempts to bring those SUM values into better agreement with the calculations performed for a root cgroup (see ./kernel/cgroup/rstat.c source file). [ we differ from those above in that we also include ] [ the IDLE plus IOWAIT tics in our TOTAL calculation ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-09-08 10:30:00 +05:30
STAT_TIC_SUM_SYSTEM, // ull_int derived from SYSTEM + IRQ + SOFTIRQ tics
STAT_TIC_SUM_IDLE, // ull_int derived from IDLE + IOWAIT tics
library: improve header file item comments, <STAT> api This patch just polishes the 'origin' comments for the <STAT> header file. In particular those derived/unique items (the 'SUM' guys) will now be properly explained. [ in order to employ the 'derived from above' phrase ] [ with their DELTA versions, all SUM items had to be ] [ relocated (and some renamed). in turn, that had an ] [ impact on many portions of the .c source file too. ] Reference(s): . summary calculations introduced commit 2c86c4984a15c9ab912402838c6651f466a3d2ed . origins added to header files commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-01-13 11:30:00 +05:30
STAT_TIC_SUM_BUSY, // ull_int derived from SUM_TOTAL - SUM_IDLE tics
library: tweak those system cpu statistics, <stat> api This patch may be a little misleading in terms of size since most of the changes just reorder a little logic. The most significant changes involve two GUEST values. My original implementation excluded such tics from the TOTAL calculation and, therefore, the BUSY figure too. That decision was erroneously based on some code found in ./kernel/sched/cputime.c which in hindsight applies only to processes, not those system level cpu figures. [ another likely oops classified STOLEN tics as IDLE ] So, this patch attempts to bring those SUM values into better agreement with the calculations performed for a root cgroup (see ./kernel/cgroup/rstat.c source file). [ we differ from those above in that we also include ] [ the IDLE plus IOWAIT tics in our TOTAL calculation ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-09-08 10:30:00 +05:30
STAT_TIC_SUM_TOTAL, // ull_int derived from sum of all 10 tics
library: improve header file item comments, <STAT> api This patch just polishes the 'origin' comments for the <STAT> header file. In particular those derived/unique items (the 'SUM' guys) will now be properly explained. [ in order to employ the 'derived from above' phrase ] [ with their DELTA versions, all SUM items had to be ] [ relocated (and some renamed). in turn, that had an ] [ impact on many portions of the .c source file too. ] Reference(s): . summary calculations introduced commit 2c86c4984a15c9ab912402838c6651f466a3d2ed . origins added to header files commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-01-13 11:30:00 +05:30
library: tweak those system cpu statistics, <stat> api This patch may be a little misleading in terms of size since most of the changes just reorder a little logic. The most significant changes involve two GUEST values. My original implementation excluded such tics from the TOTAL calculation and, therefore, the BUSY figure too. That decision was erroneously based on some code found in ./kernel/sched/cputime.c which in hindsight applies only to processes, not those system level cpu figures. [ another likely oops classified STOLEN tics as IDLE ] So, this patch attempts to bring those SUM values into better agreement with the calculations performed for a root cgroup (see ./kernel/cgroup/rstat.c source file). [ we differ from those above in that we also include ] [ the IDLE plus IOWAIT tics in our TOTAL calculation ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-09-08 10:30:00 +05:30
STAT_TIC_SUM_DELTA_USER, // sl_int derived from above
STAT_TIC_SUM_DELTA_SYSTEM, // sl_int "
library: improve header file item comments, <STAT> api This patch just polishes the 'origin' comments for the <STAT> header file. In particular those derived/unique items (the 'SUM' guys) will now be properly explained. [ in order to employ the 'derived from above' phrase ] [ with their DELTA versions, all SUM items had to be ] [ relocated (and some renamed). in turn, that had an ] [ impact on many portions of the .c source file too. ] Reference(s): . summary calculations introduced commit 2c86c4984a15c9ab912402838c6651f466a3d2ed . origins added to header files commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-01-13 11:30:00 +05:30
STAT_TIC_SUM_DELTA_IDLE, // sl_int "
STAT_TIC_SUM_DELTA_BUSY, // sl_int "
library: tweak those system cpu statistics, <stat> api This patch may be a little misleading in terms of size since most of the changes just reorder a little logic. The most significant changes involve two GUEST values. My original implementation excluded such tics from the TOTAL calculation and, therefore, the BUSY figure too. That decision was erroneously based on some code found in ./kernel/sched/cputime.c which in hindsight applies only to processes, not those system level cpu figures. [ another likely oops classified STOLEN tics as IDLE ] So, this patch attempts to bring those SUM values into better agreement with the calculations performed for a root cgroup (see ./kernel/cgroup/rstat.c source file). [ we differ from those above in that we also include ] [ the IDLE plus IOWAIT tics in our TOTAL calculation ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-09-08 10:30:00 +05:30
STAT_TIC_SUM_DELTA_TOTAL, // sl_int "
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
STAT_SYS_CTX_SWITCHES, // ul_int /proc/stat
STAT_SYS_INTERRUPTS, // ul_int "
STAT_SYS_PROC_BLOCKED, // ul_int "
STAT_SYS_PROC_CREATED, // ul_int "
STAT_SYS_PROC_RUNNING, // ul_int "
STAT_SYS_TIME_OF_BOOT, // ul_int "
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
STAT_SYS_DELTA_CTX_SWITCHES, // s_int derived from above
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
STAT_SYS_DELTA_INTERRUPTS, // s_int "
STAT_SYS_DELTA_PROC_BLOCKED, // s_int "
STAT_SYS_DELTA_PROC_CREATED, // s_int "
STAT_SYS_DELTA_PROC_RUNNING // s_int "
library: sysstat and vmstat api changes Use the standard libc declarations. For protecting the headers for C++ procps used to have its own defines, this change makes them use the standard libc ones. getstat() -> procps_stat_* vminfo() -> procps_vmstat_* These two components of the library now use the newer version of the API with less exposed global variables. The old methods are there for now. Signed-off-by: Craig Small <csmall@enc.com.au>
2015-06-20 03:13:02 +05:30
};
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
enum stat_reap_type {
STAT_REAP_CPUS_ONLY,
library: changes to some numa stuff in that <stat> api Now that we may be getting serious with documentation, that stat module was revisited with an eye toward user friendliness. Heck, even this author puzzled over some of the existing notes and naming conventions employed. So, this patch will adjust some identifiers and expand the notes to (hopefully) better serve potential users. The most significant change was making the STAT_TIC_ID always valid for numa nodes, even if any are inactive. Thus the -22222 special STAT_NODE_INVALID constant now is applied only to STAT_TIC_NUMA_NODE. It will be used on the cpu summary and reaps with STAT_REAP_CPUS_ONLY. And it will also mark any numa node that was inactive. Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-24 10:30:00 +05:30
STAT_REAP_NUMA_NODES_TOO
library: extend cpu jiff logic beyond cpu summary info There was not a way I could see to support top's needs for cpu information with the new 'chained' provisions. The sheer quantity of such data plus the unpredictable number of potential processors suggested a totally new approach was warranted while keeping internals opaque. So this patch introduces two new structures solely for use by potential callers (as seen in the API). They're responsible for providing them to the library which is then responsible for filling them with requested data. The top program will continue to provide numa support, without involving the library in any of those details. [ not to mention all the 'dl' and 'stderr' numa crap ] With this transfer of the cpu tics duty to our library the provision associated with the CPU_ZEROTICS #define could not initially be migrated. The commit referenced below suggests it may have lost its importance. In any case such logic may yet be incorporated in the future. But for now, that #define has been completely removed. Reference(s): commit ee3ed4b45edd66c6e0455d3fab08a48e7ea83030 Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-06-28 10:30:00 +05:30
};
library: add final remaining sort function, <STAT> api With this patch, all of the modules which offer a reap function (pids, diskstats, slabinfo and stat too) will now also provide for sorting whatever had been reaped. It was easy to overlook a sort function for our <STAT> guy given the paucity of CPUs on your typical personal desktop or laptop. However, out in the world one might find boxes with hundreds of CPUs plus many NUMA nodes. Hey, who are we to disallow sorts on something another person might see as useful under the above conditions? And, there's always something to be said for symmetry. [ of course, several minor tweaks were also included ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-24 10:30:00 +05:30
enum stat_sort_order {
STAT_SORT_ASCEND = +1,
STAT_SORT_DESCEND = -1
};
library: readstat redesigned using 'stack' vs. 'chain' In addition to that text shown below the line which is common to several commit messages, this patch contains several minor changes with lessor impact upon the API: . A call to procps_stat_read_jiffs() has been added to those jiffs functions carrying the 'fill' nomenclature to parallel like functions in some of our other files. . The #include header files are ordered alphabetically now, with all those <sys/??> types separately grouped. . Standard copyright boilerplate was added in .c file. . The header file follows the conventions of indenting (by 4 spaces) those parameters too lengthy for 1 line. ------------------------------------------------------ . The former 'chains' have now become 'stacks' without the 'next' pointer in each result struct. The pointers initially seemed to offer some flexibility with memory allocations and benefits for the library access logic. However, user access was always via displacement and a a statically allocated chain was cumbersome to define. . An enumerator ending in '_noop' will no longer serve as a fencepost delimiter. Rather, it has become a much more important and flexible user oriented tool. Adding one or more such 'items' in any items list passed into the library becomes the means of extending the 'stack' to also include user (not just library) data. Any such data is guaranteed to never be altered by the library. . Anticipating PID support, where many different types must be represented in a result structure, we'll adopt a common naming standard. And, while not every results structure currently needs to reflect disparate types a union will be employed so the same dot qualifier ('.') can be used consistently when accessing all such data. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-07-21 10:30:00 +05:30
struct stat_result {
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
enum stat_item item;
library: readstat redesigned using 'stack' vs. 'chain' In addition to that text shown below the line which is common to several commit messages, this patch contains several minor changes with lessor impact upon the API: . A call to procps_stat_read_jiffs() has been added to those jiffs functions carrying the 'fill' nomenclature to parallel like functions in some of our other files. . The #include header files are ordered alphabetically now, with all those <sys/??> types separately grouped. . Standard copyright boilerplate was added in .c file. . The header file follows the conventions of indenting (by 4 spaces) those parameters too lengthy for 1 line. ------------------------------------------------------ . The former 'chains' have now become 'stacks' without the 'next' pointer in each result struct. The pointers initially seemed to offer some flexibility with memory allocations and benefits for the library access logic. However, user access was always via displacement and a a statically allocated chain was cumbersome to define. . An enumerator ending in '_noop' will no longer serve as a fencepost delimiter. Rather, it has become a much more important and flexible user oriented tool. Adding one or more such 'items' in any items list passed into the library becomes the means of extending the 'stack' to also include user (not just library) data. Any such data is guaranteed to never be altered by the library. . Anticipating PID support, where many different types must be represented in a result structure, we'll adopt a common naming standard. And, while not every results structure currently needs to reflect disparate types a union will be employed so the same dot qualifier ('.') can be used consistently when accessing all such data. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-07-21 10:30:00 +05:30
union {
library: more tweaks for code and/or comments, 3rd gen Following is a summary of significant changes (if any) to each of these now upgraded 3rd gen library modules. <meminfo> ............................................ . eliminated duplicate decl of 'struct procps_meminfo' . standardized/normalized results struct union members . added 'std' & 'var' dividers in .c file, like <pids> . how did i miss relocating all these friggin' #undefs . cleanup 'get' return logic (remove a redundant 'if') <pids> ............................................... . repositioned the procps_pidsinfo structure in header . removed the extra trailing comma from enum pids_item . standardized/normalized results struct union members <slabinfo> ........................................... . corrected comment typo (jeeze, in an 'aligned' para) . standardized/normalized results struct union members . added 'std' & 'var' dividers in .c file, like <pids> . removed an obsolete #undef from procps_slabinfo_sort . cleanup 'get' return logic (remove a redundant 'if') <stat> ............................................... . how did i miss relocating all these friggin' #undefs . corrected an initialization fencepost used with numa <=== see Craig, here's a bug fix . removed the extra trailing comma from enum stat_item . standardized/normalized results struct union members . added 'std' & 'var' dividers in .c file, like <pids> . strengthen those parm checks in procps_stat_get func . cleanup 'get' return logic (remove a redundant 'if') <vmstat> ............................................. . standardized/normalized results struct union members . added 'std' & 'var' dividers in .c file, like <pids> . cleanup 'get' return logic (remove a redundant 'if') [ virtually all of these tweaks reflect the author's ] [ continuing pursuit of an unreasonable goal -- that ] [ of a 'perfect' (plus 'pretty') C language program! ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-14 10:30:00 +05:30
signed int s_int;
signed long sl_int;
unsigned long ul_int;
library; add more of my gratuitous changes, <STAT> api This commit is just my usual tweaking after an initial submission, once the dust has settled & some more desk checking was performed. Here are the changes included: . get function need not check the 'stat_was_read' flag ( first time in save_sec == 0 so branch always taken ) . some table logic appeared outside the proper section . cleanup_stack's loop made to work like assign_result . eliminated an include of procps.h from stat.h header . removed 'ext_numitems' from the stacks_extent struct . changed the alignment of three prototypes for stat.h . reorganized the pointers for 'stacks_extents' struct . improved types indentation in header for readability . lastly, some really gratuitous changes made to align - comments within that private 'stacks_alloc' function Signed-off-by: Jim Warner <james.warner@comcast.net
2016-05-10 10:30:00 +05:30
unsigned long long ull_int;
library: readstat redesigned using 'stack' vs. 'chain' In addition to that text shown below the line which is common to several commit messages, this patch contains several minor changes with lessor impact upon the API: . A call to procps_stat_read_jiffs() has been added to those jiffs functions carrying the 'fill' nomenclature to parallel like functions in some of our other files. . The #include header files are ordered alphabetically now, with all those <sys/??> types separately grouped. . Standard copyright boilerplate was added in .c file. . The header file follows the conventions of indenting (by 4 spaces) those parameters too lengthy for 1 line. ------------------------------------------------------ . The former 'chains' have now become 'stacks' without the 'next' pointer in each result struct. The pointers initially seemed to offer some flexibility with memory allocations and benefits for the library access logic. However, user access was always via displacement and a a statically allocated chain was cumbersome to define. . An enumerator ending in '_noop' will no longer serve as a fencepost delimiter. Rather, it has become a much more important and flexible user oriented tool. Adding one or more such 'items' in any items list passed into the library becomes the means of extending the 'stack' to also include user (not just library) data. Any such data is guaranteed to never be altered by the library. . Anticipating PID support, where many different types must be represented in a result structure, we'll adopt a common naming standard. And, while not every results structure currently needs to reflect disparate types a union will be employed so the same dot qualifier ('.') can be used consistently when accessing all such data. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-07-21 10:30:00 +05:30
} result;
library: add chaining provisions to readstat cpu & sys If a caller chooses to reduce the overhead of repeated function calls, this commit provides for acquiring all the desired information in just a single library call. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-06-28 10:30:00 +05:30
};
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
struct stat_stack {
struct stat_result *head;
};
library: tweak formatting for readstat header and code This patch mostly just eliminates darn tab characters. Plus the library function declarations and definitions have been standardized. Most visibly, the input params now have all been indented on their own separate line. The following names were changed to more closely match meminfo.c or provide a certain symmetry. Unfortunately that also impacted some other pgms which were updated. . 'procps_stat_get' evolved into 'procps_stat_get_sys' . 'procps_stat_info' is now known as 'procps_statinfo' [and just a little trailing whitespace was eliminated] Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-06-28 10:30:00 +05:30
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
struct stat_reap {
int total;
struct stat_stack **stacks;
};
library: tweak formatting for readstat header and code This patch mostly just eliminates darn tab characters. Plus the library function declarations and definitions have been standardized. Most visibly, the input params now have all been indented on their own separate line. The following names were changed to more closely match meminfo.c or provide a certain symmetry. Unfortunately that also impacted some other pgms which were updated. . 'procps_stat_get' evolved into 'procps_stat_get_sys' . 'procps_stat_info' is now known as 'procps_statinfo' [and just a little trailing whitespace was eliminated] Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-06-28 10:30:00 +05:30
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
struct stat_reaped {
struct stat_stack *summary;
struct stat_reap *cpus;
library: changes to some numa stuff in that <stat> api Now that we may be getting serious with documentation, that stat module was revisited with an eye toward user friendliness. Heck, even this author puzzled over some of the existing notes and naming conventions employed. So, this patch will adjust some identifiers and expand the notes to (hopefully) better serve potential users. The most significant change was making the STAT_TIC_ID always valid for numa nodes, even if any are inactive. Thus the -22222 special STAT_NODE_INVALID constant now is applied only to STAT_TIC_NUMA_NODE. It will be used on the cpu summary and reaps with STAT_REAP_CPUS_ONLY. And it will also mark any numa node that was inactive. Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-24 10:30:00 +05:30
struct stat_reap *numa;
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
};
library: tweak formatting for readstat header and code This patch mostly just eliminates darn tab characters. Plus the library function declarations and definitions have been standardized. Most visibly, the input params now have all been indented on their own separate line. The following names were changed to more closely match meminfo.c or provide a certain symmetry. Unfortunately that also impacted some other pgms which were updated. . 'procps_stat_get' evolved into 'procps_stat_get_sys' . 'procps_stat_info' is now known as 'procps_statinfo' [and just a little trailing whitespace was eliminated] Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-06-28 10:30:00 +05:30
library: readstat redesigned using 'stack' vs. 'chain' In addition to that text shown below the line which is common to several commit messages, this patch contains several minor changes with lessor impact upon the API: . A call to procps_stat_read_jiffs() has been added to those jiffs functions carrying the 'fill' nomenclature to parallel like functions in some of our other files. . The #include header files are ordered alphabetically now, with all those <sys/??> types separately grouped. . Standard copyright boilerplate was added in .c file. . The header file follows the conventions of indenting (by 4 spaces) those parameters too lengthy for 1 line. ------------------------------------------------------ . The former 'chains' have now become 'stacks' without the 'next' pointer in each result struct. The pointers initially seemed to offer some flexibility with memory allocations and benefits for the library access logic. However, user access was always via displacement and a a statically allocated chain was cumbersome to define. . An enumerator ending in '_noop' will no longer serve as a fencepost delimiter. Rather, it has become a much more important and flexible user oriented tool. Adding one or more such 'items' in any items list passed into the library becomes the means of extending the 'stack' to also include user (not just library) data. Any such data is guaranteed to never be altered by the library. . Anticipating PID support, where many different types must be represented in a result structure, we'll adopt a common naming standard. And, while not every results structure currently needs to reflect disparate types a union will be employed so the same dot qualifier ('.') can be used consistently when accessing all such data. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-07-21 10:30:00 +05:30
library: changes to some numa stuff in that <stat> api Now that we may be getting serious with documentation, that stat module was revisited with an eye toward user friendliness. Heck, even this author puzzled over some of the existing notes and naming conventions employed. So, this patch will adjust some identifiers and expand the notes to (hopefully) better serve potential users. The most significant change was making the STAT_TIC_ID always valid for numa nodes, even if any are inactive. Thus the -22222 special STAT_NODE_INVALID constant now is applied only to STAT_TIC_NUMA_NODE. It will be used on the cpu summary and reaps with STAT_REAP_CPUS_ONLY. And it will also mark any numa node that was inactive. Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-24 10:30:00 +05:30
// STAT_TIC_ID value for /proc/stat cpu summary
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
#define STAT_SUMMARY_ID -11111
library: changes to some numa stuff in that <stat> api Now that we may be getting serious with documentation, that stat module was revisited with an eye toward user friendliness. Heck, even this author puzzled over some of the existing notes and naming conventions employed. So, this patch will adjust some identifiers and expand the notes to (hopefully) better serve potential users. The most significant change was making the STAT_TIC_ID always valid for numa nodes, even if any are inactive. Thus the -22222 special STAT_NODE_INVALID constant now is applied only to STAT_TIC_NUMA_NODE. It will be used on the cpu summary and reaps with STAT_REAP_CPUS_ONLY. And it will also mark any numa node that was inactive. Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-24 10:30:00 +05:30
// STAT_TIC_NUMA_NODE value for STAT_REAP_CPUS_ONLY or
// for STAT_REAP_NUMA_NODES_TOO when node was inactive
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
#define STAT_NODE_INVALID -22222
library: readstat redesigned using 'stack' vs. 'chain' In addition to that text shown below the line which is common to several commit messages, this patch contains several minor changes with lessor impact upon the API: . A call to procps_stat_read_jiffs() has been added to those jiffs functions carrying the 'fill' nomenclature to parallel like functions in some of our other files. . The #include header files are ordered alphabetically now, with all those <sys/??> types separately grouped. . Standard copyright boilerplate was added in .c file. . The header file follows the conventions of indenting (by 4 spaces) those parameters too lengthy for 1 line. ------------------------------------------------------ . The former 'chains' have now become 'stacks' without the 'next' pointer in each result struct. The pointers initially seemed to offer some flexibility with memory allocations and benefits for the library access logic. However, user access was always via displacement and a a statically allocated chain was cumbersome to define. . An enumerator ending in '_noop' will no longer serve as a fencepost delimiter. Rather, it has become a much more important and flexible user oriented tool. Adding one or more such 'items' in any items list passed into the library becomes the means of extending the 'stack' to also include user (not just library) data. Any such data is guaranteed to never be altered by the library. . Anticipating PID support, where many different types must be represented in a result structure, we'll adopt a common naming standard. And, while not every results structure currently needs to reflect disparate types a union will be employed so the same dot qualifier ('.') can be used consistently when accessing all such data. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-07-21 10:30:00 +05:30
library: changes to some numa stuff in that <stat> api Now that we may be getting serious with documentation, that stat module was revisited with an eye toward user friendliness. Heck, even this author puzzled over some of the existing notes and naming conventions employed. So, this patch will adjust some identifiers and expand the notes to (hopefully) better serve potential users. The most significant change was making the STAT_TIC_ID always valid for numa nodes, even if any are inactive. Thus the -22222 special STAT_NODE_INVALID constant now is applied only to STAT_TIC_NUMA_NODE. It will be used on the cpu summary and reaps with STAT_REAP_CPUS_ONLY. And it will also mark any numa node that was inactive. Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-24 10:30:00 +05:30
library: ensure that all those 'GET' macros are robust When users call the native 'get' functions they have a responsibility to check that the result struct address was indeed returned. But when using those 'GET' macros there was no protection for possible NULL dereference. So this patch will add some protection for a potential failure of an underlying 'get' function. And should it occur then those 'GET' macros will just return a zero. Plus, we'll also mirror that behavior in the debugging header should the XTRA_PROCPS_DEBUG #define be active. And, we might as well add a warning when invalid items are passed to 'GET' macros, just like we do for 'VAL'. [ lastly, we added the missing opening parens/braces ] [ to 2 'GET' macros in that xtra-procps-debug.h file ] [ which went unnoticed until the qa folks caught up. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-06 21:41:11 +05:30
#define STAT_GET( info, actual_enum, type ) ( { \
struct stat_result *r = procps_stat_get( info, actual_enum ); \
r ? r->result . type : 0; } )
library: <STAT> api, change for that 'get' return type The following commit message is shared with 4 patches. ------------------------------------------------------ Under the newlib interface most of our 'get' functions represent a bit of a compromise in that the actual raw values are coerced into one (probably ok) return type. That approach creates the possibility of truncation at best, and wouldn't serve future needs should something other than numeric data be added to the 'get' results. This commit trades the current compromise for a return value guaranteed to satisfy all future needs, namely a pointer to a particular api's specific results struct. The impact on existing programs is minimal, especially when using a new supplied macro. Otherwise, native 'C' syntax could be used, but may feel somewhat unnatural. [ as an aside, this new approach allows us to delete ] [ all 'getsfunc' table entries & the supporting code ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-18 10:30:00 +05:30
library: expand VAL macros to include the context parm This patch will set the stage for validating the types referenced in the result union. For now, the parameter representing that 'info' structure will remain unused. [ and while we're at it, let us correct a faulty GET ] [ macro in the diskstats header. that puppy missed a ] [ parm which ain't so good if that guy is ever used! ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-05 10:30:00 +05:30
#define STAT_VAL( relative_enum, type, stack, info ) \
library: <STAT> api, change for that 'get' return type The following commit message is shared with 4 patches. ------------------------------------------------------ Under the newlib interface most of our 'get' functions represent a bit of a compromise in that the actual raw values are coerced into one (probably ok) return type. That approach creates the possibility of truncation at best, and wouldn't serve future needs should something other than numeric data be added to the 'get' results. This commit trades the current compromise for a return value guaranteed to satisfy all future needs, namely a pointer to a particular api's specific results struct. The impact on existing programs is minimal, especially when using a new supplied macro. Otherwise, native 'C' syntax could be used, but may feel somewhat unnatural. [ as an aside, this new approach allows us to delete ] [ all 'getsfunc' table entries & the supporting code ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-18 10:30:00 +05:30
stack -> head [ relative_enum ] . result . type
library: readstat redesigned using 'stack' vs. 'chain' In addition to that text shown below the line which is common to several commit messages, this patch contains several minor changes with lessor impact upon the API: . A call to procps_stat_read_jiffs() has been added to those jiffs functions carrying the 'fill' nomenclature to parallel like functions in some of our other files. . The #include header files are ordered alphabetically now, with all those <sys/??> types separately grouped. . Standard copyright boilerplate was added in .c file. . The header file follows the conventions of indenting (by 4 spaces) those parameters too lengthy for 1 line. ------------------------------------------------------ . The former 'chains' have now become 'stacks' without the 'next' pointer in each result struct. The pointers initially seemed to offer some flexibility with memory allocations and benefits for the library access logic. However, user access was always via displacement and a a statically allocated chain was cumbersome to define. . An enumerator ending in '_noop' will no longer serve as a fencepost delimiter. Rather, it has become a much more important and flexible user oriented tool. Adding one or more such 'items' in any items list passed into the library becomes the means of extending the 'stack' to also include user (not just library) data. Any such data is guaranteed to never be altered by the library. . Anticipating PID support, where many different types must be represented in a result structure, we'll adopt a common naming standard. And, while not every results structure currently needs to reflect disparate types a union will be employed so the same dot qualifier ('.') can be used consistently when accessing all such data. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-07-21 10:30:00 +05:30
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct stat_info;
library: readstat redesigned using 'stack' vs. 'chain' In addition to that text shown below the line which is common to several commit messages, this patch contains several minor changes with lessor impact upon the API: . A call to procps_stat_read_jiffs() has been added to those jiffs functions carrying the 'fill' nomenclature to parallel like functions in some of our other files. . The #include header files are ordered alphabetically now, with all those <sys/??> types separately grouped. . Standard copyright boilerplate was added in .c file. . The header file follows the conventions of indenting (by 4 spaces) those parameters too lengthy for 1 line. ------------------------------------------------------ . The former 'chains' have now become 'stacks' without the 'next' pointer in each result struct. The pointers initially seemed to offer some flexibility with memory allocations and benefits for the library access logic. However, user access was always via displacement and a a statically allocated chain was cumbersome to define. . An enumerator ending in '_noop' will no longer serve as a fencepost delimiter. Rather, it has become a much more important and flexible user oriented tool. Adding one or more such 'items' in any items list passed into the library becomes the means of extending the 'stack' to also include user (not just library) data. Any such data is guaranteed to never be altered by the library. . Anticipating PID support, where many different types must be represented in a result structure, we'll adopt a common naming standard. And, while not every results structure currently needs to reflect disparate types a union will be employed so the same dot qualifier ('.') can be used consistently when accessing all such data. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-07-21 10:30:00 +05:30
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
int procps_stat_new (struct stat_info **info);
int procps_stat_ref (struct stat_info *info);
int procps_stat_unref (struct stat_info **info);
library: readstat redesigned using 'stack' vs. 'chain' In addition to that text shown below the line which is common to several commit messages, this patch contains several minor changes with lessor impact upon the API: . A call to procps_stat_read_jiffs() has been added to those jiffs functions carrying the 'fill' nomenclature to parallel like functions in some of our other files. . The #include header files are ordered alphabetically now, with all those <sys/??> types separately grouped. . Standard copyright boilerplate was added in .c file. . The header file follows the conventions of indenting (by 4 spaces) those parameters too lengthy for 1 line. ------------------------------------------------------ . The former 'chains' have now become 'stacks' without the 'next' pointer in each result struct. The pointers initially seemed to offer some flexibility with memory allocations and benefits for the library access logic. However, user access was always via displacement and a a statically allocated chain was cumbersome to define. . An enumerator ending in '_noop' will no longer serve as a fencepost delimiter. Rather, it has become a much more important and flexible user oriented tool. Adding one or more such 'items' in any items list passed into the library becomes the means of extending the 'stack' to also include user (not just library) data. Any such data is guaranteed to never be altered by the library. . Anticipating PID support, where many different types must be represented in a result structure, we'll adopt a common naming standard. And, while not every results structure currently needs to reflect disparate types a union will be employed so the same dot qualifier ('.') can be used consistently when accessing all such data. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-07-21 10:30:00 +05:30
library: <STAT> api, change for that 'get' return type The following commit message is shared with 4 patches. ------------------------------------------------------ Under the newlib interface most of our 'get' functions represent a bit of a compromise in that the actual raw values are coerced into one (probably ok) return type. That approach creates the possibility of truncation at best, and wouldn't serve future needs should something other than numeric data be added to the 'get' results. This commit trades the current compromise for a return value guaranteed to satisfy all future needs, namely a pointer to a particular api's specific results struct. The impact on existing programs is minimal, especially when using a new supplied macro. Otherwise, native 'C' syntax could be used, but may feel somewhat unnatural. [ as an aside, this new approach allows us to delete ] [ all 'getsfunc' table entries & the supporting code ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-18 10:30:00 +05:30
struct stat_result *procps_stat_get (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct stat_info *info,
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
enum stat_item item);
library: add chaining provisions to readstat cpu & sys If a caller chooses to reduce the overhead of repeated function calls, this commit provides for acquiring all the desired information in just a single library call. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-06-28 10:30:00 +05:30
library: final tweaks to code and/or comments, 3rd gen With the dust now settling on all those 3rd generation upgrades, this patch tries to provide some consistency among the separate modules involved. Someday we should consider a 4th generation where all redundant code has been removed and isolated in a new shared source file. Following is a summary of significant changes (if any) to each of these now upgraded 3rd gen library modules. <meminfo> ............................................ . strictly formatting/comment changes, code unaffected <pids> ............................................... . replaced a local mkSTR macro with existing STRINGIFY . added fetch narrative explaining duplicate addresses <slabinfo> ........................................... . rearranged some free logic for procps_slabinfo_unref . added fetch narrative explaining duplicate addresses <stat> ............................................... . added #define ENFORCE_LOGICAL, just as in <slabinfo> . replaced a local mkSTR macro with existing STRINGIFY . alphabetized the function declarations in the header <vmstat> ............................................. . made one coverity concession with read_vmstat_failed [ several of these changes may reflect this author's ] [ continuing pursuit of an unreasonable goal -- that ] [ of a 'perfect' (plus 'pretty') C language program! ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-09 10:30:00 +05:30
struct stat_reaped *procps_stat_reap (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct stat_info *info,
library: final tweaks to code and/or comments, 3rd gen With the dust now settling on all those 3rd generation upgrades, this patch tries to provide some consistency among the separate modules involved. Someday we should consider a 4th generation where all redundant code has been removed and isolated in a new shared source file. Following is a summary of significant changes (if any) to each of these now upgraded 3rd gen library modules. <meminfo> ............................................ . strictly formatting/comment changes, code unaffected <pids> ............................................... . replaced a local mkSTR macro with existing STRINGIFY . added fetch narrative explaining duplicate addresses <slabinfo> ........................................... . rearranged some free logic for procps_slabinfo_unref . added fetch narrative explaining duplicate addresses <stat> ............................................... . added #define ENFORCE_LOGICAL, just as in <slabinfo> . replaced a local mkSTR macro with existing STRINGIFY . alphabetized the function declarations in the header <vmstat> ............................................. . made one coverity concession with read_vmstat_failed [ several of these changes may reflect this author's ] [ continuing pursuit of an unreasonable goal -- that ] [ of a 'perfect' (plus 'pretty') C language program! ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-09 10:30:00 +05:30
enum stat_reap_type what,
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
enum stat_item *items,
int numitems);
library: final tweaks to code and/or comments, 3rd gen With the dust now settling on all those 3rd generation upgrades, this patch tries to provide some consistency among the separate modules involved. Someday we should consider a 4th generation where all redundant code has been removed and isolated in a new shared source file. Following is a summary of significant changes (if any) to each of these now upgraded 3rd gen library modules. <meminfo> ............................................ . strictly formatting/comment changes, code unaffected <pids> ............................................... . replaced a local mkSTR macro with existing STRINGIFY . added fetch narrative explaining duplicate addresses <slabinfo> ........................................... . rearranged some free logic for procps_slabinfo_unref . added fetch narrative explaining duplicate addresses <stat> ............................................... . added #define ENFORCE_LOGICAL, just as in <slabinfo> . replaced a local mkSTR macro with existing STRINGIFY . alphabetized the function declarations in the header <vmstat> ............................................. . made one coverity concession with read_vmstat_failed [ several of these changes may reflect this author's ] [ continuing pursuit of an unreasonable goal -- that ] [ of a 'perfect' (plus 'pretty') C language program! ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-09 10:30:00 +05:30
struct stat_stack *procps_stat_select (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct stat_info *info,
library: improve/standardize one interface, <STAT> api This commit represents a complete redesign of the stat interface. Gone are the confusing 8 separate accessors along with their 2 additional read functions. In their place we have just 3 accessors, with no read required. That old interface also suffered an inflexibility with respect to structures. Now we deal with an unchanging standard 'result' struct enabling future changes where the binary interface will no longer need to be broken. And gone is that former unnecessary typedef, used when dealing with jiffies. Now the standard C type is used. Our new API also adds some brand new functionality. If a caller plans to employ successive 'select' or 'reap' invocations, then delta values are available (which is actually only what that top program is interested in). At some future point a 'sort' function could be easily introduced to complement the 'reap' function. However, I saw no need for it at present and so it was omitted. There were several design decisions which everyone may not agree with. In support I'll offer these rationals: . The 'get' function returns a signed long long result which means a potential loss of some significance. But I felt the ability to distinguish actual errors (minus values) from true zero results were worth such a risk. . The DELTA item enumerators were also made signed and smaller than their parents. And they are intentionally grouped as last so as to emphasize those distinctions. . The SYS type items were excluded from the new 'reap' function. It would not make sense to duplicate them in each results stack. They're limited to 'get'/'select'. . By the same token, some items (DELTA, etc.) will not be allowed under that 'get' routine. That function was already open to significant internal overhead (through subsequent calls like in vmstat.c). That is why it has been limited via 1 second between reads of /proc/stat. Lastly, when we finally get around to documenting this interface there's a real potential toe stubber when it comes to the numa node portion. The libnuma.so doesn't really provide any means to retrieve the active nodes. Thus, any total reported by <stat> is just the highest node number plus one, as reported by the numa library. Any unused/inactive nodes are identified through these . PROCPS_STAT_TIC_ID shows as PROCPS_STAT_NODE_INVALID By the same token after the STAT_REAP_CPUS_ONLY 'reap' . PROCPS_STAT_TIC_NUMA_NODE = PROCPS_STAT_NODE_INVALID Reference(s): http://www.freelists.org/post/procps/newlib-stat-interface Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-06 10:30:00 +05:30
enum stat_item *items,
int numitems);
library: tweak formatting for readstat header and code This patch mostly just eliminates darn tab characters. Plus the library function declarations and definitions have been standardized. Most visibly, the input params now have all been indented on their own separate line. The following names were changed to more closely match meminfo.c or provide a certain symmetry. Unfortunately that also impacted some other pgms which were updated. . 'procps_stat_get' evolved into 'procps_stat_get_sys' . 'procps_stat_info' is now known as 'procps_statinfo' [and just a little trailing whitespace was eliminated] Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-06-28 10:30:00 +05:30
library: add final remaining sort function, <STAT> api With this patch, all of the modules which offer a reap function (pids, diskstats, slabinfo and stat too) will now also provide for sorting whatever had been reaped. It was easy to overlook a sort function for our <STAT> guy given the paucity of CPUs on your typical personal desktop or laptop. However, out in the world one might find boxes with hundreds of CPUs plus many NUMA nodes. Hey, who are we to disallow sorts on something another person might see as useful under the above conditions? And, there's always something to be said for symmetry. [ of course, several minor tweaks were also included ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-24 10:30:00 +05:30
struct stat_stack **procps_stat_sort (
struct stat_info *info,
struct stat_stack *stacks[],
int numstacked,
enum stat_item sortitem,
enum stat_sort_order order);
library: refactor the XTRA_PROCPS_DEBUG implementation If we ever were to eliminate the procps.h header file, as discussed in the thread referenced below, then that would impair the current XTRA_PROCPS_DEBUG provisions. The only remaining way to verify result types would be to explicitly include that <proc/xtra-procps-debug.h>. So, this commit will once again enable the ./configure provision for defining the -DXTRA_PROCPS_DEBUG option. Reference(s): https://www.freelists.org/post/procps/newlib-Qualys-patches,6 Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-09-01 10:30:00 +05:30
#ifdef XTRA_PROCPS_DEBUG
library: ensure 'XTRA_PROCPS_DEBUG' works in real life This commit attempts to smooth some wrinkles impacting any future libprocps user exploitation. The 2 problems relate exclusively to our XTRA_PROCPS_DEBUG provision. 1. The 'xtra-procps-debug.h' header had an include for 'procps-private.h', which was not an installed header. So the STRINGIFY macros will now be embedded directly. 2. Each of the new api headers referenced '<proc/...>' rather than '<procps/...>' for the debugging #include. So, we must drop that prefix in favor of a quoted file name so that debugging builds work regardless of where that 'xtra-procps-debug.h' header happens to be found. Reference(s): . Jun, 2020 - changed target install directory commit d64755ea5f48295f5b064da0ea667ee3503b4cd8 . Sep, 2018 - #include migrated from procps.h commit fab37662efe92650063a45e6b20eda09afe07e14 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-07-25 10:30:00 +05:30
# include "xtra-procps-debug.h"
library: refactor the XTRA_PROCPS_DEBUG implementation If we ever were to eliminate the procps.h header file, as discussed in the thread referenced below, then that would impair the current XTRA_PROCPS_DEBUG provisions. The only remaining way to verify result types would be to explicitly include that <proc/xtra-procps-debug.h>. So, this commit will once again enable the ./configure provision for defining the -DXTRA_PROCPS_DEBUG option. Reference(s): https://www.freelists.org/post/procps/newlib-Qualys-patches,6 Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-09-01 10:30:00 +05:30
#endif
library: replace the troublesome '__BEGIN_DECLS' macro When 'newlib' was introduced, in the commit referenced below, the use of that glibc '__BEGIN_DECLS' macro was standardized. However, as issue #88 revealed, this may result in a fatal build error with other environments. So, this patch just trades that macro for the standard '#ifdef __cplusplus' conventions (thus avoiding use of all those '#include <features.h>' directives as well). Reference(s): . newlib introduced commit a410e236abb47c7c43194e61d0566686f81513af . procps-ng-3.3.13 issue https://gitlab.com/procps-ng/procps/issues/88 . some additional discussion https://www.freelists.org/post/procps/PATCH-Replace-glibcspecific-macros-in-procnumah,1 . musl wiki (see: sys/cdefs.h error messages) https://wiki.musl-libc.org/faq.html Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-04-06 10:30:00 +05:30
#ifdef __cplusplus
}
#endif
library: sysstat and vmstat api changes Use the standard libc declarations. For protecting the headers for C++ procps used to have its own defines, this change makes them use the standard libc ones. getstat() -> procps_stat_* vminfo() -> procps_vmstat_* These two components of the library now use the newer version of the API with less exposed global variables. The old methods are there for now. Signed-off-by: Craig Small <csmall@enc.com.au>
2015-06-20 03:13:02 +05:30
#endif
Reference in New Issue Copy Permalink