14. Varray
The varray(3m) module is a variable array that permits quick access to elements by index without allocating all the memory for the array when the array is created. Instead, memory is allocated as necessary in increasingly larger chunks (32 * membsize, 64 * membsize, 128 * membsize, ... upto 2^21 * membsize).
14.1. Varray functions
These functions should be used to manage varray objects.
The varray_new function
Synopsis
#include <mba/varray.h>
struct varray *varray_new(size_t membsize);
Description
The varray_new function creates a new varray with no initial storage. Array members will be membsize bytes in size.
Returns
The varray_new function returns the new varray object or a null pointer if an error occurred in which case errno will be set appropriately.
The varray_del function
Synopsis
#include <mba/varray.h>
void varray_del(void *va);
Description
The varray_del function frees all memory chunks allocated for array elements and then frees the va object itself.
The varray_get function
Synopsis
#include <mba/varray.h>
void *varray_get(struct varray *va, unsigned int idx);
Description
The varray_get function returns a pointer to memory at index idx. The memory will be membsize bytes in size as specified in the varray_new function. The memory is initialized to 0 when the chunk backing it is allocated meaning the memory should initially be 0.
Returns
The varray_get function returns a pointer to the memory at index idx or a null pointer if an error occured in which case errno will be set appropriately.
The varray_release function
Synopsis
#include <mba/varray.h>
void varray_release(struct varray *va, unsigned int from);
Description
The varray_release function may release all memory chunks storing elements from index from and higher. This function will only free memory chunks that constitute elements at the from index and above. If the from index is the first element of a chunk, that chunk will be freed as well. This function should only be used if it is understood that the range of elements being accessed has been significantly reduced (e.g. factor of 10). In practice it is not necessary to use this function at all.
The varray_iterate function
Synopsis
#include <mba/varray.h>
void varray_iterate(void *va, iter_t *iter);
Description
The varray_iterate and varray_next functions will enumerate over every element in the array that has ever been accessed with the varray_get function. However, adjacent elements in the same memory chunk will also be returned by varray_next even if they those elements have never been accessed with varray_get. Similarly, there may be gaps in the full range that are not returned by varray_next because no element was accessed in a range necessary for the chunk of memory for that range to be allocated. The varray_iterate function initializes the iter object to point to the beginning of the array. The varray_next function returns each element in the array or NULL if all elements have been enumerated.
The varray_next function
Synopsis
#include <mba/varray.h>
void *varray_next(void *va, iter_t *iter);
Returns
The varray_next function returns a pointer to the memory of the next element in the enumeration or a null pointer if there are no more elements to be enumerated.
Copyright 2003 Michael B. Allen <mballen@erols.com>