[asterisk-dev] [Code Review] Finish implementaton of astobj2 OBJ_MULTIPLE, and convert ast_channel_iterator to use it.

[Kevin Fleming]

-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviewboard.asterisk.org/r/379/
-----------------------------------------------------------

(Updated 2009-10-06 08:17:38.135042)


Review request for Asterisk Developers and Russell Bryant.


Changes
-------

This new version has a number of changes:

1) ao2_iterator objects now support an AO2_ITERATOR_UNLINK flag, which causes the iterator to remove objects from the container as they are returned.
2) ao2_iterator objects now support an AO2_ITERATOR_MALLOCD flag, which is used when the API itself allocates an iterator and it must be freed by ao2_iterator_destroy().
3) ao2_find() and ao2_callback() now return a pointer to an ao2_iterator when OBJ_MULTIPLE is used without OBJ_NODATA; the caller can retrieve each found/matched object by using ao2_iterator_next(), finally calling ao2_iterator_destroy() when they are finished with the iterator. The iterator holds the only reference to a dynamically allocated container holding the results, so when the iterator is destroyed, the container will be destroyed as well.
4) The API documentation in astobj2.h has been updated.


Summary
-------

This patch finishes the implementation of OBJ_MULTIPLE in astobj2 (the case where multiple results need to be returned; OBJ_NODATA mode already was supported). In addition, it converts ast_channel_iterators (only the targeted versions, not the ones that iterate over all channels) to use this method.

The patch is not yet complete, as astobj2.h needs some editing to document the new structures and remove the existing comments about limitations of OBJ_MULTIPLE, but the functional parts should be complete.

During this work, I removed the 'ao2_flags' arguments to the ast_channel_iterator constructor functions; there were no uses of that argument yet, there is only one possible flag to pass, and it made the iterators less 'opaque'. If at some point in the future someone really needs an ast_channel_iterator that does not lock the container, we can provide constructor(s) for that purpose.


Diffs (updated)
-----

  /trunk/main/channel.c 222222 
  /trunk/main/cli.c 222222 
  /trunk/main/manager.c 222222 
  /trunk/res/snmp/agent.c 222222 
  /trunk/include/asterisk/astobj2.h 222222 
  /trunk/include/asterisk/channel.h 222222 
  /trunk/include/asterisk/lock.h 222222 
  /trunk/main/astobj2.c 222222 
  /trunk/apps/app_softhangup.c 222222 
  /trunk/funcs/func_channel.c 222222 
  /trunk/apps/app_chanspy.c 222222 
  /trunk/apps/app_directed_pickup.c 222222 

Diff: https://reviewboard.asterisk.org/r/379/diff


Testing
-------

None yet; posted this from my hotel room in Madrid, where testing is somewhat hard to do. Will setup a test next week when I return to the office.


Thanks,

Kevin