[PATCH libinput 6/6] doc: put some extra warning in for libinput_event_destroy()

[Peter Hutterer]

On Wed, Dec 10, 2014 at 06:01:13PM +0800, Jonas Ådahl wrote:
> Hi,
> 
> Comment inline.
> 
> On Wed, Dec 10, 2014 at 10:34:04AM +1000, Peter Hutterer wrote:
> > Unlike all other structs, events aren't refcounted and will get destroyed
> > immediately.
> > 
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> >  src/libinput.h | 10 +++++++++-
> >  1 file changed, 9 insertions(+), 1 deletion(-)
> > 
> > diff --git a/src/libinput.h b/src/libinput.h
> > index 7e5d93c..f7cb169 100644
> > --- a/src/libinput.h
> > +++ b/src/libinput.h
> > @@ -335,6 +335,9 @@ struct libinput_seat;
> >   *
> >   * The base event type. Use libinput_event_get_pointer_event() or similar to
> >   * get the actual event type.
> > + *
> > + * @warning Unlike other structs events are considered transient and
> > + * <b>not</b> refcounted.
> >   */
> >  struct libinput_event;
> >  
> > @@ -382,7 +385,12 @@ struct libinput_event_touch;
> >  /**
> >   * @ingroup event
> >   *
> > - * Destroy the event.
> > + * Destroy the event, freeing all associated data. Data obtained from this
> > + * event must be considered invalid after this call.
> 
> Hmm. Is this really correct? The validity of some data, for example the
> coordnates of an absolute motion event, is not related to the lifetime
> of the event, but should rather be considered invalid after some (very
> short) time, so saying that an event invalidates all data of an event
> doesn't seem to make sense to me. What it does invalidate would be any
> data accessed via a pointer, so maybe that is what should be written
> instead?

right, in this case "data" in the context of the C language, so this
paraphaph was to avoid invalid memory access by callers. How about
"resources" instead of data.

+ * Destroy the event, freeing all associated resources. Resources obtained from this
+ * event must be considered invalid after this call.

That should be enough, the varous devices/seat/etc. structs all have notes
that their lifetime is tied to the event and need to be ref'd to extend the
lifetime.

Cheers,
   Peter


> > + *
> > + * @warning Unlike other structs events are considered transient and
> > + * <b>not</b> refcounted. Calling libinput_event_destroy() <b>will</b>
> > + * destroy the event.
> >   *
> >   * @param event An event retrieved by libinput_get_event().
> >   */
> > -- 
> > 2.1.0
> 
> Jonas