[lwip-devel] misleading @note in sys_untimeout

[chrysn]

hello lwip developers,

in the documentation of sys_untimeout, there is a warning note:

> /**
>  * Go through timeout list (for this task only) and remove the first matching
>  * entry, even though the timeout has not triggered yet.
>  *
>  * @note This function only works as expected if there is only one timeout
>  * calling 'handler' in the list of timeouts.
>  *
>  * @param handler callback function that would be called by the timeout
>  * @param arg callback argument that would be passed to handler
> */
> void
> sys_untimeout(sys_timeout_handler handler, void *arg)

reviewing the code, `handler` is not treated differently from `arg`, and
besides that, the code seems to do exactly what the top two lines say:
it looks for a timeout matching by `handler` and `arg`, and removes at
most one entry.

can you explain to me how the @note is relevant?


i've traced the fragment back to 027d59fd; no code was actually modified
back then, and it looked as safe as today with respect to the note.

given the comment also contains a reference to tasks (which is afaik not
relevant any more, now that this is a NO_SYS=1 implementation only), i'd
suggest this new wording:

> /**
>  * Go through the timeout list and remove the first matching entry, even
>  * though the timeout has not triggered yet.
>  *
>  * @param handler callback function that would be called by the timeout
>  * @param arg callback argument that would be passed to handler
> */
> void
> sys_untimeout(sys_timeout_handler handler, void *arg)

best regards
chrysn

-- 
To use raw power is to make yourself infinitely vulnerable to greater powers.
  -- Bene Gesserit axiom

signature.asc
Description: Digital signature