20. 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^20 * membsize).

20.1. Varray functions

These functions should be used to manage varray objects.

The varray_init function
Synopsis


  #include <mba/varray.h>
  int varray_init(struct varray *va, size_t membsize, struct allocator *al);

Description
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.
Returns
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
Synopsis


  #include <mba/varray.h>
  int varray_deinit(struct varray *va);

Description
The varray_deinit function deinitializes the varray va and releases any storage backing the array.
Returns
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
Synopsis


  #include <mba/varray.h>
  struct varray *varray_new(size_t membsize, struct allocator *al);

Description
The varray_new function allocates storage for a new varray object and initializes with the varray_init function.
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 calls varray_deinit on the object va 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_index function
Synopsis


  #include <mba/varray.h>
  int varray_index(struct varray *va, void *elem);

Description
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.
Returns
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 array.

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 such that memory will not be frequently allocated and freed.

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.