[asterisk-dev] [Code Review] Fix ao2_iterator API to hold references to containers being iterated.

[Kevin P. Fleming]

Kevin Fleming wrote:

> Summary
> -------
> 
> See Mantis issue for details of what prompted this change.
> 
> Additional notes:
> 
> This patch changes the ao2_iterator API in two ways: F_AO2I_DONTLOCK has become an enum instead of a macro, with a name that fits our naming policy; also, it is now necessary to call ao2_iterator_destroy() on any iterator that has been created. Currently this only releases the reference to the container being iterated, but in the future this could also release other resources used by the iterator, if the iterator implementation changes to use additional resources.
> 
> The patch currently changes the API in a way that will *not* cause existing code to fail at compilation or run time; instead, existing code that is used against the new API implementation will result in a reference leak on the container being iterated. There are least two ways this can be addressed... the ao2_iterator_init() function's name can be changed so that existing code will fail to compile or link, or the existing function can be left alone (*without* taking a container reference) and a new function created that implements the API properly. If the latter option is chosen, ao2_iterator_init() would be marked 'deprecated' to encourage developers to switch to the new API function as soon as possible.
> 
> 
> This addresses bug 15987.
>     https://issues.asterisk.org/view.php?id=15987

I'd like to get some feedback from community developers on these
proposed API changes; the simpler change (as currently implemented)
would be preferable as I'd like to completely remove the broken API, but
if the community has a significant amount of out-of-tree code using
ao2_iterators this could be painful since it would cause reference leaks
and any dynamically allocated containers might be left in memory.

-- 
Kevin P. Fleming
Digium, Inc. | Director of Software Technologies
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
skype: kpfleming | jabber: kpfleming at digium.com
Check us out at www.digium.com & www.asterisk.org