[PATCH 11/11] libctf, include: new functions for looking up enumerators

[Nick Alcock]

On 14 Jun 2024, David Faust uttered the following:

> On 6/13/24 11:54, Nick Alcock wrote:
>> Three new functions for looking up the enum type containing a given
>> enumeration constant, and optionally that constant's value.
>
> The new functions make sense to me, though I don't have much experience
> as a user of libctf or it's APIs.

The APIs I got help on from Stephen Brennan and Indu Bhagat earlier. I'm
fairly confident that at least *one* user will like them. :)

> Just a few small comments/nits below.

Thanks! All fixed as you suggested.

>> +   from end-of-iteration.  DICT should be NULL before the first call and is set
>> +   to NULL after the last and on error: on successful call it is the caller's
>> +   responsibility to ctf_dict_close() it.  The caller should  otherwise pass it
>
> IMO it would be good to also clearly say that on success DICT is set to
> point to the dictionary containing the returned type.  (Which has been
> implicitly opened and therefore must be closed via ctf_dict_close by the
> caller).

True! I, uh, assumed that would go without saying, which in
documentation is probably a bad stance :)

The "pass in DICT unchanged, we actually use it to store state" thing is
a bit weird but seems more or less harmless (when I get dict leaks, it's
not because of that, it's because I forget to close them on error
paths), and without it I'd need to add the ability for ctf_next_t
iterators to hold archives and dicts at the same time, which does get
quite complex. (I tried, and honestly the _next iterators are complex
enough to write as it is!)

-- 
NULL && (void)