[users at i-scream] API discussion

Jens Rehsack rehsack at googlemail.com
Fri Sep 27 16:58:43 BST 2013

Am 27.09.2013 um 17:27 schrieb Tim Bishop <tim at bishnet.net>:

> This is a simplified summary of the API discussions we've been having.
> I'm using CPU stats as an example.
> Originally we had this (function names etc simplified - sorry!):
> get_cpu() which returned a single cpu_stat. This cpu_stat contained a
> total count for all CPUs.
> In 0.90 we pre-emptively changed the API to:
> get_cpu() returns a list of cpu_stats. Only contains one entry which is
> the total count for all CPUs. It was intended this could then be
> modified to return stats for individual CPUs.
> The issue is how we return the total count for all CPUs, and also stats
> for individual CPUs.
> Jens suggested (correct me if I'm wrong):
> get_cpu returns a list of cpu_stats. The first item in the list is the
> total count for all CPUs. Subsequent items in the list would be for
> individual CPUs.
> He cited the example of the get_disk function which returns a list of
> disk_stats, and said that get_cpu should be the same.

I also noted, that - like disks - the upcoming new results shall have
identifiers. Disks have the diskname, processes have procname and procargs,
file systems have device and mount_point, etc.

CPU's would have no identifier for total and a CPU identifier (eg. "cpu0")
for any else. Similiar for paging, swap etc.

Having "total" without identifier in the result[0] item is intended for
backward compatibility. It also helps for systems which doesn't deliver
per_$(device)_stats - without requiring mixing implementations on get_total_*()

> Adam suggested two functions:
> get_cpu returns a single cpu_stat with a total for all CPUs. This is
> compatible with the pre-0.90 function.
> get_per_cpu returns a list of cpu_stats which are the stats for
> individual CPUs.
> An alternative I have, is the same as Adam's, but have get_cpu return a
> list of stats for individual CPUs, and have get_cpu_totals return a
> single stat for all CPUs.
> The discussion is which of these approaches is the best going forward.
> It should be settled on before the API is more solidly frozen in 1.0.

From implementation point of view I completely disagree on such a proposal.
It degrade the get_total_cpu() to a utility function like get_cpu_percent()
and/or get_process_count(). Looking at the difficulty to ensure their
results are consistent I would strongly disagree to follow such a way.

Also: It would require to think about a naming scheme which could require
renaming the existing functions (get_total_fs_stats() vs. get_per_fs_stats()).

While C is more or less a macro assembler (yes, I know it's a programming
language) - it basically supports data types like
* atomic types
* structs
* unions
* list of above

Things like hashes aren't supported - but Perl, Python and C++ do. Looking
at some benchmarking, it's not expensive to make Perl, Python or C++ lists,
hashes or whatever from the sg_vector's returned from libstatgrab. But it
would cost a lot of manpower and probably complexity to introduce separate
per_object / total stats.

> Hopefully I've summarised that accurately.

I'm pretty unsure whether this is possible. The entire controversy isn't
based on complete accurate design.

Jens Rehsack
pkgsrc, Perl5
sno at NetBSD.org

Jens Rehsack
rehsack at gmail.com

More information about the users mailing list