Asterisk - The Open Source Telephony Project GIT-master-67613d1
Data Fields
ao2_iterator Struct Reference

When we need to walk through a container, we use an ao2_iterator to keep track of the current position. More...

#include <astobj2.h>

Collaboration diagram for ao2_iterator:
Collaboration graph
[legend]

Data Fields

struct ao2_containerc
 
int complete
 
int flags
 
void * last_node
 

Detailed Description

When we need to walk through a container, we use an ao2_iterator to keep track of the current position.

Because the navigation is typically done without holding the lock on the container across the loop, objects can be inserted or deleted or moved while we work. As a consequence, there is no guarantee that we manage to touch all the elements in the container, and it is possible that we touch the same object multiple times.

An iterator must be first initialized with ao2_iterator_init(), then we can use o = ao2_iterator_next() to move from one element to the next. Remember that the object returned by ao2_iterator_next() has its refcount incremented, and the reference must be explicitly released when done with it.

In addition, ao2_iterator_init() will hold a reference to the container being iterated and the last container node found. These objects will be unreffed when ao2_iterator_destroy() is called to free up the resources used by the iterator (if any).

Example:

struct ao2_container *c = ... // the container we want to iterate on
struct ao2_iterator i;
struct my_obj *o;
while ((o = ao2_iterator_next(&i))) {
... do something on o ...
ao2_ref(o, -1);
}
while ((o = ao2_iterator_next(&i))) {
... do something on o ...
ao2_ref(o, -1);
}
#define ao2_iterator_next(iter)
Definition: astobj2.h:1911
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attribute_warn_unused_result
Create an iterator for a container.
void ao2_iterator_restart(struct ao2_iterator *iter)
Restart an iteration.
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
void ao2_iterator_destroy(struct ao2_iterator *iter)
Destroy a container iterator.
Generic container type.
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1821
struct ao2_container * c
Definition: astobj2.h:1823

The astobj2 iterator

Note
You are not supposed to know the internals of an iterator! We would like the iterator to be opaque, unfortunately its size needs to be known if we want to store it around without too much trouble. Anyways... The iterator has a pointer to the container, and a flags field specifying various things e.g. whether the container should be locked or not while navigating on it. The iterator "points" to the current container node.

Details are in the implementation of ao2_iterator_next()

Examples
app_skel.c.

Definition at line 1821 of file astobj2.h.

Field Documentation

◆ c

struct ao2_container* c

The container (Has a reference)

Definition at line 1823 of file astobj2.h.

Referenced by __ao2_iterator_next(), ao2_iterator_count(), ao2_iterator_destroy(), and ao2_iterator_restart().

◆ complete

int complete

Nonzero if the iteration has completed.

Definition at line 1827 of file astobj2.h.

Referenced by __ao2_iterator_next(), and ao2_iterator_restart().

◆ flags

int flags

◆ last_node

void* last_node

Last container node (Has a reference)

Definition at line 1825 of file astobj2.h.

Referenced by __ao2_iterator_next(), and ao2_iterator_restart().


The documentation for this struct was generated from the following file: