Re: [RFC] libgpiod public API reviews needed

[Bartosz Golaszewski <brgl@xxxxxxxx>]

2018-01-21 16:49 GMT+01:00 Linus Walleij <linus.walleij@xxxxxxxxxx>:
> On Fri, Jan 19, 2018 at 2:28 PM, Bartosz Golaszewski <brgl@xxxxxxxx> wrote:
>
>> I want to commit to a stable interface for the library starting from
>> v1.0 but it would be great if I could get some reviews first - it's
>> basically only about reviewing a single public header: include/gpiod.h
>
> I have no real objections, then, I'm not a great API designer at all.
>
> - In my opinion, all design should consider Rusty Russell's design
>   manifesto:
>   http://sweng.the-davies.net/Home/rustys-api-design-manifesto
>   Just ask yourself the questions in the manifesto to the function
>   signature.
>
> - Things named with the infix "simple" *_simple_* *SIMPLE* etc.
>   This is a weasel word.
>   https://en.wikipedia.org/wiki/Weasel_word
>   I have been adviced against ever using that in code, because the
>   idea of what is "simple" is extremely subjective. A function with
>   six obscure parameters, is that "simple"?
>
>   I would have called it *rudimentary*, *coarse"* or *plain* or something
>   similar less subjective.
>

I was thinking about something like _contextless_ or _ctxless_ but it
would make the already long function names even longer...

> - gpiod_simple_event_handle_cb uses struct timespec.
>   This can create problems.
>   On 32 vs 64 bit platforms, because struct timespec is of different
>   size on 32 vs 64bit platforms, I think. (Looping in Arnd to verify.)
>   You might think "well it is either used on 32bit or on 64bit,
>   and everything else is compiled for that so what."
>   But in reality you have things like Python bindings, and those get
>   a *real* problem when things are in struct timespec, because they
>   map byte-by-byte and precompile code doing this map and
>   redistribute. Disaster.

I was not aware of this, but it seems you're right! Nice catch, thanks.

How about defining a local struct gpiod_timespec with both seconds and
nanoseconds explicitly defined to uint64_t?

Thanks,
Bartosz Golaszewski

>   With libmtp I often wish I has just used ISO 8601
>   https://en.wikipedia.org/wiki/ISO_8601
>   even if it means creating a string on one side and parsing it on
>   the other, because it is unambigous.
>   This might be an especially bad idea of mine but think it over.
--
To unsubscribe from this list: send the line "unsubscribe linux-gpio" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html