The internal implementation of objects and containers is opaque to the user, so we can use different data structures as needs arise.user code can access, and for which the system keeps track (with a bit of help from the programmer) of the number of references around. When an object has no more references (refcount == 0), it is destroyed, by first invoking whatever 'destructor' function the programmer specifies (it can be NULL if none is necessary), and then freeing the memory. This way objects can be shared without worrying who is in charge of freeing them. As an additional feature, ao2 objects are associated to individual locks.
Creating an object requires the size of the object and and a pointer to the destructor function:
struct foo *o;
o = ao2_alloc(sizeof(struct foo), my_destructor_fn);
The value returned points to the user-visible portion of the objects (user-data), but is also used as an identifier for all object-related operations such as refcount and lock manipulations.
On return from ao2_alloc():
causing the destructor to be called (and then memory freed) when the refcount goes to 0.
A container must first be allocated, specifying the initial parameters. At the moment, this is done as follows:
A container knows little or nothing about the objects it stores, other than the fact that they have been created by ao2_alloc(). All knowledge of the (user-defined) internals of the objects is left to the (user-supplied) functions passed as arguments to ao2_container_alloc().
If we want to insert an object in a container, we should initialize its fields -- especially, those used by my_hash_fn() -- to compute the bucket to use. Once done, we can link an object to a container with
The function returns NULL in case of errors (and the object is not inserted in the container). Other values mean success (we are not supposed to use the value as a pointer to anything). Linking an object to a container increases its refcount by 1 automatically.
A container with a single buckets is effectively a linked list. However there is no ordering among elements.