library: normalize/standardize the i/f, <SLABINFO> api

Before this major redesign, the slabs interface likely
was our messiest 2nd generation attempt at opaqueness.
Beyond the standard 'new', 'ref' & 'unref', there were
a total of 12 exported functions. Now, there are four.

The 1st step was to remove several of those functions.
These were quick to go since they were not used (yet):
. procps_slabnode_count
. procps_slabnode_getname
. procps_slabnode_getstack

Then, the following were internalized so users needn't
be burdened with implementation details in the future:
. procps_slabinfo_read (renamed: read_slabinfo_failed)
. procps_slabnode_stacks_alloc (renamed: stacks_alloc)

Still others evolved into the minimal interface we had
strived for in the other upgraded 3rd generation APIs:
. procps_slabnode_get -----------> procps_slabinfo_get
. separate stack_alloc/fill --> procps_slabinfo_select
. separate stacks_alloc/fill ---> procps_slabinfo_reap
. procps_slabnode_stacks_sort --> procps_slabinfo_sort

------------------------------------------------------
Beyond those reductions, the major modifications were:

. This API tries to be as forgiving as possible and as
such won't throw errors when a caller request makes no
sense. For example, if a 'get' or 'select' requested a
SLABNODE item (with no current means to id that node),
results will be zero. By the same token, should 'reap'
include a global SLABS item (meaning those values will
be duplicated in *every* node stack) it'll be allowed.

. If the above behavior is undesired, a new #define of
ENFORCE_LOGICAL can be used to restrict certain items.

. Permission problems will now be caught at 'new' time
thanks to a priming 'read' call. That read also serves
to make DELTA values potentially useful at 1st access.

. Separate slab/slabnode enumerators were consolidated
into one, simplifying validation & the results struct.

. Several internal parameter checks were relaxed since
they were already checked by the caller. Besides if we
cannot trust our own code we might as well hang it up.

. That sort provision was made more efficient and will
offer the ascending choice, in addition to descending.

------------------------------------------------------
Lastly, some additional thoughts regarding the future:

. It would not be difficult to expand 'select' to also
accept a nodeid, or to clone it as 'select_node'. And,
should the same be extended to 'get', a results struct
could be returned instead of signed long accommodating
the extra data type(s) like a node name (string data).

. The 'get' function is not currently affected by that
 define ENFORCE_LOGICAL. However, at some future point
perhaps -EINVAL would be more appropriate than a zero.

Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit is contained in:
Jim Warner 2016-06-05 00:00:00 -05:00 committed by Craig Small
parent 5be4167782
commit 5d5a52a380
3 changed files with 821 additions and 651 deletions

View File

@ -33,20 +33,12 @@ global:
procps_pids_select;
procps_pids_sort;
procps_slabinfo_new;
procps_slabinfo_read;
procps_slabinfo_ref;
procps_slabinfo_unref;
procps_slabs_get;
procps_slabs_getstack;
procps_slabnode_count;
procps_slabnode_getname;
procps_slabnode_get;
procps_slabnode_getstack;
procps_slabnode_stack_fill;
procps_slabnode_stack_alloc;
procps_slabnode_stacks_fill;
procps_slabnode_stacks_sort;
procps_slabnode_stacks_alloc;
procps_slabinfo_get;
procps_slabinfo_reap;
procps_slabinfo_select;
procps_slabinfo_sort;
procps_stat_new;
procps_stat_ref;
procps_stat_unref;

File diff suppressed because it is too large Load Diff

View File

@ -3,6 +3,7 @@
*
* Copyright (C) 1998-2005 Albert Cahalan
* Copyright (C) 2015 Craig Small <csmall@enc.com.au>
* Copyright (C) 2016 Jim Warnerl <james.warner@comcast.net>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
@ -26,7 +27,10 @@
__BEGIN_DECLS
enum slabs_item {
enum slabinfo_item {
PROCPS_SLABINFO_noop, // n/a
PROCPS_SLABINFO_extra, // n/a
PROCPS_SLABS_OBJS, // u_int
PROCPS_SLABS_AOBJS, // u_int
PROCPS_SLABS_PAGES, // u_int
@ -37,14 +41,23 @@ enum slabs_item {
PROCPS_SLABS_SIZE_AVG, // u_int
PROCPS_SLABS_SIZE_MIN, // u_int
PROCPS_SLABS_SIZE_MAX, // u_int
PROCPS_SLABS_SIZE_TOTAL, // ul_int
PROCPS_SLABS_SIZE_ACTIVE, // ul_int
PROCPS_SLABS_noop, // n/a
PROCPS_SLABS_stack_end // n/a
};
PROCPS_SLABS_SIZE_TOTAL, // ul_int
enum slabnode_item {
PROCPS_SLABNODE_SIZE, // ul_int
PROCPS_SLABS_DELTA_OBJS, // s_int
PROCPS_SLABS_DELTA_AOBJS, // s_int
PROCPS_SLABS_DELTA_PAGES, // s_int
PROCPS_SLABS_DELTA_SLABS, // s_int
PROCPS_SLABS_DELTA_ASLABS, // s_int
PROCPS_SLABS_DELTA_CACHES, // s_int
PROCPS_SLABS_DELTA_ACACHES, // s_int
PROCPS_SLABS_DELTA_SIZE_AVG, // s_int
PROCPS_SLABS_DELTA_SIZE_MIN, // s_int
PROCPS_SLABS_DELTA_SIZE_MAX, // s_int
PROCPS_SLABS_DELTA_SIZE_ACTIVE, // s_int
PROCPS_SLABS_DELTA_SIZE_TOTAL, // s_int
PROCPS_SLABNODE_NAME, // str
PROCPS_SLABNODE_OBJS, // u_int
PROCPS_SLABNODE_AOBJS, // u_int
PROCPS_SLABNODE_OBJ_SIZE, // u_int
@ -53,83 +66,65 @@ enum slabnode_item {
PROCPS_SLABNODE_SLABS, // u_int
PROCPS_SLABNODE_ASLABS, // u_int
PROCPS_SLABNODE_USE, // u_int
PROCPS_SLABNODE_NAME, // str
PROCPS_SLABNODE_noop, // n/a
PROCPS_SLABNODE_stack_end // n/a
PROCPS_SLABNODE_SIZE // ul_int
};
struct procps_slabinfo;
struct slabnode_stack {
struct slab_result *head;
enum slabinfo_sort_order {
PROCPS_SLABINFO_ASCEND = +1,
PROCPS_SLABINFO_DESCEND = -1
};
struct slab_result {
int item;
struct slabinfo_result {
enum slabinfo_item item;
union {
signed int s_int;
unsigned int u_int;
unsigned long ul_int;
char * str;
} result;
};
int procps_slabinfo_new (struct procps_slabinfo **info);
int procps_slabinfo_read (struct procps_slabinfo *info);
struct slabinfo_stack {
struct slabinfo_result *head;
};
struct slabinfo_reap {
int total;
struct slabinfo_stack **stacks;
};
#define PROCPS_SLABINFO_VAL(rel_enum,type,stack) \
stack -> head [ rel_enum ] . result . type
struct procps_slabinfo;
int procps_slabinfo_new (struct procps_slabinfo **info);
int procps_slabinfo_ref (struct procps_slabinfo *info);
int procps_slabinfo_unref (struct procps_slabinfo **info);
unsigned long procps_slabs_get (
signed long procps_slabinfo_get (
struct procps_slabinfo *info,
enum slabs_item item);
enum slabinfo_item item);
int procps_slabs_getstack (
struct slabinfo_reap *procps_slabinfo_reap (
struct procps_slabinfo *info,
struct slab_result *these);
enum slabinfo_item *items,
int numitems);
int procps_slabnode_count (struct procps_slabinfo *info);
const char *procps_slabnode_getname (
struct slabinfo_stack *procps_slabinfo_select (
struct procps_slabinfo *info,
int nodeid);
enum slabinfo_item *items,
int numitems);
unsigned long procps_slabnode_get (
struct slabinfo_stack **procps_slabinfo_sort (
struct procps_slabinfo *info,
enum slabnode_item item,
int nodeid);
int procps_slabnode_getstack (
struct procps_slabinfo *info,
struct slab_result *these,
int nodeid);
int procps_slabnode_stack_fill (
struct procps_slabinfo *info,
struct slabnode_stack *stack,
int nodeid);
int procps_slabnode_stacks_fill (
struct procps_slabinfo *info,
struct slabnode_stack **stacks,
int maxstacks);
struct slabnode_stack *procps_slabnode_stack_alloc (
struct procps_slabinfo *info,
int maxitems,
enum slabnode_item *items);
struct slabnode_stack **procps_slabnode_stacks_alloc (
struct procps_slabinfo *info,
int maxstacks,
int maxitems,
enum slabnode_item *items);
struct slabnode_stack **procps_slabnode_stacks_sort (
struct procps_slabinfo *info,
struct slabnode_stack **stacks,
struct slabinfo_stack *stacks[],
int numstacked,
enum slabnode_item sort);
enum slabinfo_item sortitem,
enum slabinfo_sort_order order);
__END_DECLS
#endif /* _PROC_SLAB_H */