Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
varray(3m)		     MBA Library Functions		    varray(3m)

NAME
       varray -	A variable sized array.

SYNOPSIS
       #include	<mba/varray.h>

       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);

DESCRIPTION
       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 in-
       creasingly larger chunks	(32 * membsize,	64 * membsize, 128 * membsize,
       upto 2^20 * membsize).

       init   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.

       deinit The varray_deinit	function deinitializes the varray va  and  re-
	      leases any storage backing the array.

       new    The  varray_new  function	allocates storage for a	new varray ob-
	      ject and initializes with	the varray_init	function.

       del    The varray_del function calls varray_deinit on the object	va and
	      then frees the va	object itself.

       get    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  ini-
	      tially be	0.

       index  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.

       release
	      The  varray_release function may release all memory chunks stor-
	      ing 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  ac-
	      cessed  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 mem-
	      ory  chunk  will	also  be  returned by varray_next even if they
	      those elements have never	been accessed with varray_get.	 Simi-
	      larly, there may be gaps in the full range that are not returned
	      by varray_next because no	element	was accessed in	a range	neces-
	      sary 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 enu-
	      merated.

RETURNS
       init   The  varray_init function	returns	0 on success or	-1 for failure
	      in which case errno will be set to an appropriate	value.

       deinit The varray_deinit	function returns 0 on success or -1 for	 fail-
	      ure in which case	errno will be set to an	appropriate value.

       new    The  varray_new function returns the new varray object or	a null
	      pointer if an error occurred in which case errno will be set ap-
	      propriately.

       get    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.

       index  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.

       next   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.

libmba-0.9.1			 Apr 29, 2005			    varray(3m)

NAME | SYNOPSIS | DESCRIPTION | RETURNS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=varray&sektion=3m&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help