[users at i-scream] API discussion

[Tim Bishop]

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.

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.

Hopefully I've summarised that accurately.

Tim.

-- 
Tim Bishop
http://www.bishnet.net/tim/
PGP Key: 0x6C226B37FDF38D55