More API breakage: battery.remaining_time

[Richard Hughes]

For me, battery.remaining_time is difficult to use.

It sometimes means time to discharge when on battery, but also means
time to charge when on system AC power.

This concept sort of breaks in the multibattery case where one battery
can be discharging and not the other. It's also difficult to map to UPS
values where both are possible to get.

More seriously, it causes races when the user unplugs AC where the
sequence of events is very bios dependent. Sometimes the time_remaining
value is referring to the old state for a split second when the system
is in another case which I've had to solve for g-p-m with a 500ms
"valid" timeout. This is pretty icky.

I propose splitting battery.remaining_time into
battery.remaining_time_until_charged and
battery.remaining_time_until_discharged and keeping
battery.remaining_time around for 1 year for compatibility with existing
users. This is similar to what we are doing with suspend_to_disk.

Also, I really want to put a new document in HAL root called
API-Changes.txt something like the kernel does.

This can explain what API is changing, why, and when the compatibility
stuff is going away. suspend_to_disk is already in there as deprecated,
and really I want this battery key, and the smbios.* keys there too.

What do you guys think?

NOTE: I *really* want to deprecate the smbios keys before we release
0.5.9 so that we can change hal-info before it is released. Once we
release hal-info, we can't break API as the whole point of hal-info is
that it will work with any hal version >= 0.5.9.

Thanks.

Richard.