pfuAutoList(3pfu) OpenGL Performer 3.2.2 libpfutil C Reference Pages
NAME
pfuNewAutoList, pfuGetAutoListClassType, pfuAdd, pfuGet, pfuGetNum,
pfuInsert, pfuMove, pfuRemove, pfuRemoveIndex, pfuReplace, pfuResetList,
pfuSearch, pfuSearchForType, pfuSet - Dynamically-sized resource owning
list
FUNCTION SPECIFICATION
#include <Performer/pfutil.h>
pfuAutoList* pfuNewAutoList(int listLength, void* arena);
pfType* pfuGetAutoListClassType(void);
void pfuAdd(pfuAutoList* list, void* elt);
void* pfuGet(const pfuAutoList* list, int index);
int pfuGetNum(const pfuAutoList* list);
void pfuInsert(pfuAutoList* list, int index, void* elt);
int pfuMove(pfuAutoList* lists, int index, void* elt);
int pfuRemove(pfuAutoList* list, void* elt);
void pfuRemoveIndex(pfuAutoList* list, int index);
int pfuReplace(pfuAutoList* list, void* old, void* new);
void pfuResetList(pfuAutoList* list);
int pfuSearch(const pfuAutoList* list, void* elt);
int pfuSearchForType(const pfuAutoList* list, pfType* type);
void pfuSet(pfuAutoList* list, int index, void* elt);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfuAutoList is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfuAutoList. Casting an object of
class pfuAutoList to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
Page 1
pfuAutoList(3pfu) OpenGL Performer 3.2.2 libpfutil C Reference Pages
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfuAutoList can also be used with these
functions designed for objects of class pfMemory.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
PARAMETERS
list identifies a pfuAutoList.
DESCRIPTION
A pfuAutoList is a dynamically-sized list of elements. Elements must be
of type pointer to pfMemory (or a derived class). pfuAutoList increments
the reference count of elements that are added or inserted into the list.
It decrements the reference count of elements that are removed from the
list. In this way, pfuAutoList takes ownership of its elements.
pfuNewAutoList creates and returns a handle to a new pfuAutoList. The
element size is fixed to be the size of a pfMemory* and cannot be
changed. listLength is the initial length of the list; listLength *
sizeof( pfMemory* ) bytes will be allocated for the list's storage. The
argument arena specifies a malloc arena out of which the pfuAutoList is
to be allocated or NULL for allocation from the process heap.
pfuAutoLists can be deleted with pfDelete. When a list is deleted, it
calls pfMemory::unrefDelete() on all elements in the list.
pfuGetAutoListClassType returns the pfType* for the class pfuAutoList.
The pfType* returned by pfuGetAutoListClassType is the same as the
pfType* returned by invoking pfGetType on any instance of class
pfuAutoList. Because OpenGL Performer allows subclassing of built-in
Page 2
pfuAutoList(3pfu) OpenGL Performer 3.2.2 libpfutil C Reference Pages
types, when decisions are made based on the type of an object, it is
usually better to use pfIsOfType to test if an object is of a type
derived from a Performer type rather than to test for strict equality of
the pfType*'s.
A pfuAutoList dynamically increases its list size by a factor of 2 and
zeros the additional memory whenever it runs out of memory. This way the
list size quickly reaches its final size without many reallocations of
memory. However, some memory (up to one half of the total allocation) at
the end of the list may be wasted. If you know the exact number of
elements in the list, you can specify the pfuAutoList list length when
creating it (the listLength argument to pfuNewAutoList).
pfuSet sets the indexth element of list to elt. The list is
automatically grown if index is beyond the current list length. If the
list already contains an element at indexth then pfMemory::unref() is
called on that element, before elt is inserted into the list.
pfMemory::ref() is called on elt.
pfuGet returns the element of list at index index or 0 if index is out of
bounds.
pfuAdd appends elt to list and automatically grows list if necessary.
pfMemory::ref() is called on elt.
pfuRemove removes elt from list and shifts the elements down over the
vacant spot, e.g. - if elt had index 0, then index 1 becomes index 0,
index 2 becomes index 1 and so on. pfuRemove returns the index of elt if
elt was actually removed and -1 if it was not found in the list.
pfuRemoveIndex removes the indexth element of list, and like pfuRemove,
shifts the elements down over the vacant spot.
Note that if the requested element was removed from the list then
pfMemory::unref() is called on that element. In this way, the list
disowns the removed element.
Note that pfuRemove linearly searches the list for elt and removes only
the first matching element. To remove all occurrences of elt do the
following:
while (pfuRemove(list, elt) >= 0)
/* empty */ ;
pfuSearch returns the index of elt if elt was found in list and -1
otherwise.
pfuSearchForType returns the index of type, if an element was found in
list that returns TRUE for pfMemory::isOfType(), and returns -1
otherwise.
Page 3
pfuAutoList(3pfu) OpenGL Performer 3.2.2 libpfutil C Reference Pages
pfuInsert inserts elt before the list element with index index. index
must be within the range [0 .. pfuGetNum(list)]. pfMemory::ref() is
called on elt.
pfuMove deletes elt from its current location and inserts before the list
element with index index. index must be within the range [0 ..
pfuGetNum(list)] or else (-1) is returned and no move is executed. If elt
is not already in list, (-1) is returned and elt is not inserted into the
list. Otherwise, index is returned to indicate success.
pfuReplace replaces the first instance of old with new and returns the
index of old if it was found in list and -1 otherwise. pfMemory::unref()
is called on old if it was found in the list.
pfuGetNum returns the number of elements in list.
pfuResetList calls pfMemory::unrefDelete() on all the elements in list
and resets the number of elements to 0.
NOTES
Any attempt to add or insert non-pfMemory objects into a pfuAutoList will
fail. If an error status cannot be returned then a warning will be
issued. The list will remain unchanged.
SEE ALSO
pfList, pfMemory
Page 4
