Re: [libgpiod][RFC v2] core: implement v2.0 API

[Kent Gibson <warthog618@gmail.com>]

On Sat, May 29, 2021 at 07:23:20AM +0800, Kent Gibson wrote:
> On Fri, May 28, 2021 at 03:51:03PM +0200, Bartosz Golaszewski wrote:
> > On Thu, May 27, 2021 at 1:27 PM Kent Gibson <warthog618@gmail.com> wrote:
> > >

<snip>

> > > >  /**
> > > > - * @brief Get the handle to the GPIO chip controlling this line.
> > > > - * @param line The GPIO line object.
> > > > - * @return Pointer to the GPIO chip handle controlling this line.
> > > > + * @brief Get the pointer to the line-info object associated with this event.
> > > > + * @param event Line info event object.
> > > > + * @return Returns a pointer to the line-info object associated with this event
> > > > + *         whose lifetime is tied to the event object. It must not be freed by
> > > > + *         the caller.
> > > >   */
> > > > -struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line);
> > > > +struct gpiod_line_info *
> > > > +gpiod_info_event_peek_line_info(struct gpiod_info_event *event);
> > > > +
> > >
> > > Rather than the peek/copy you use here, I would rename the peek to
> > > get...
> > 
> > Ha! I think we'll disagree here again. In most cases in low-level
> > linux C libraries, a "get" for complex objects returns a copy (or a
> > new reference if we're using shared objects). I would like to stay
> > consistent with that pattern. To me "peek" is a good way to
> > distinguish those functions that allow you to look into the internals
> > of the parent object. If anything - I'd go with the get/peek pattern
> > where the former returns a new object over whose lifetime the caller
> > takes responsibility and the latter returns a pointer to an object
> > stored in the parent. I went with copy/peek because it hints at a
> > different behavior than regular get but I can live with get/peek.
> > 
> 

I forgot to ask about where gpiod_line_info_get_name() and others that
return char * fit wrt that pattern.
So a string isn't a complex object?
Maybe they should be _peek_ as well?
Either way, it would be nice for their commentary to describe the lifetime
of the returned pointer.

Cheers,
Kent.