[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_*()
side.

> 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.

Cheers
-- 
Jens Rehsack
pkgsrc, Perl5
sno at NetBSD.org



Jens Rehsack
rehsack at gmail.com






More information about the users mailing list