API redesign progress

Jef Driesen jefdriesen at telenet.be
Sat Jun 23 13:45:30 PDT 2012

On 06/22/2012 10:53 PM, Linus Torvalds wrote:
> Looking at the subsurface libdivecomputer interfaces, the horrible
> device open and parser setup stuff is now gone. A few comments:
>   - do we have to do the parser create for each dive, or could that be
> something that is just done once? As libdivecomputer gets more detaisl
> from the computer (which might update the parse state), why not just
> do it all automatically?

There is no need to create a new parser for every dive. You can perfectly re-use 
the same one for every dive (downloaded from the same device of course). Just 
create the parser once, call set_data() for each dive, and parse it.

This scenario is exactly the reason why there is a set_data() function, and the 
dive data isn't directly passed to the dc_parser_new() function. The set_data() 
function can be called multiple times.

>     It seems silly do do the create_parser() in the dive callback. In
> fact, it seems silly to do it in the application at all, why isn't it
> done implicitly and automatically by dc_device_open()?

Creating the parser in the callback is convenient. In some cases you can't 
create a parser upfront (at the time of calling dc_device_open, or even 
immediately after it) because the actual model number is required for parsing 
the data. The model code from the device descriptor isn't sufficient, because in 
most cases the model isn't necessary for downloading. As long as you select a 
model from the same family, downloading will work fine, but for parsing you need 
the exact model number. In practice this mismatch isn't an issue because the 
exact model number is usually autodetected somewhere during the download.

But the model code may not be available until some or all the data has been 
downloaded. So you have to postpone creating the parser until you have all the 
info. And in the dive callback you are guaranteed to have all the info.

You also have to take into account the use-case where you want to parse data 
without a device connection available. For example re-parsing older dives, 
importing data that was downloaded elsewhere, etc. An example is the Uwatec 
Smart. Downloading isn't supported on Mac OS X (due to the lack of IrDA 
support), and a possible workaround is to download the data elsewhere (the 
Uwatec SmartTrak application stores the raw data internally) and than import it. 
If the parser is directly tied to a device connection, then such use-case is 
impossible to support.

BTW, for this situation I want to introduce some variant of the new 
dc_parser_new function that doesn't take a device handle. I have been thinking 
of something like this:

dc_parser_new_for_data (dc_parser_t **parser,
                         const dc_event_devinfo_t *devinfo,
                         const dc_event_clock_t *clock);

>   - The event handling is still horrible. There does not seem to be any
> sane generic way to just get the event type and meaning.

Which events are you referring to? The device events (e.g. DC_EVENT_*), or the 
parser events (e.g. DC_SAMPLE_EVENT)? Can you explain in some more detail?

>   - Is there some way to get air temperature before the dive?

Not yet, but it's on the todo list. This is probably the most often requested 
feature, but I want to concentrate on the api redesign first. The obvious 
implemention is to extend the get_field() api with a temperature field.

> But the big things that I *really* hated (enumeration of device models
> etc) are fixed and libdivecomputer.c doesn't look crazy. Good.



More information about the subsurface mailing list