varray - A variable sized array.
int varray_init(struct varray *va, size_t membsize, struct allocator *al);
int varray_deinit(struct varray *va);
struct varray *varray_new(size_t membsize, struct allocator *al);
void varray_del(void *va);
void *varray_get(struct varray *va, unsigned int idx);
int varray_index(struct varray *va, void *elem);
void varray_release(struct varray *va, unsigned int from);
void varray_iterate(void *va, iter_t *iter);
void *varray_next(void *va, iter_t *iter);
(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 *
, upto 2^20 * membsize
- The varray_init function with initialize the varray
va with no initial elements. The size of each element in the array
will be membsize. The allocator al will be used to
allocate memory to back the array.
- The varray_deinit function deinitializes the varray
va and releases any storage backing the array.
- The varray_new function allocates storage for a new varray
object and initializes with the varray_init function.
- The varray_del function calls varray_deinit on the object
va and then frees the va object itself.
- 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
- The varray_index function returns the index of the element
elem. If the element is not found -1 is returned and errno
is set to EFAULT.
- 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
such that memory will not be frequently allocated and freed.
- iterate, next
- 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_init function returns 0 on success or -1 for failure in
which case errno will be set to an appropriate value.
- The varray_deinit function returns 0 on success or -1 for failure
in which case errno will be set to an appropriate value.
- The varray_new function returns the new varray object or a
null pointer if an error occurred in which case errno will be set
- 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_index function returns the index of the element or -1
and sets errno to EFAULT to indicate the element is not in
- 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.