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

FreeBSD Manual Pages


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

       suba - Sub-allocate memory from larger chunk of memory.

       #include	<mba/suba.h>

       struct allocator	*suba_init(void	*mem, size_t size, int rst, size_t mincell);
       void *suba_alloc(struct allocator *suba,	size_t size, int zero);
       int suba_free(struct allocator *suba, void *ptr);
       void *suba_addr(const struct allocator *suba, const ref_t ref);
       ref_t suba_ref(const struct allocator *suba, const void *ptr);

       The  suba(3m)  module  provides a "sub-allocator" that can allocate and
       free memory from	a larger fixed size chunk of memory. This allocator is
       lock-less  but  reentrant meaning it will be faster but more considera-
       tion is necessary for coordinating multiple threads as opposed  to  the
       standard	C library allocator.

       All  objects within the allocator are tracked using offsets relative to
       the beginning of	the sub-allocator and all offsets and state are	stored
       as  part	of the memory being sub-allocated. Thus	the memory backing the
       allocator can be	copied and  deleted  without  being  deinitialized  to
       achive  a  variety of useful effects. The memory	of an allocator	can be
       copied temporarily to implement	transaction  control  or  checkpoints.
       Complex	data  structures  can  be manipulated by multiple processes in
       shared memory. When used	with the POSIX mmap(2)	function  (or  Windows
       equivalent), sophisticated (but non-portable) data archives can be cre-
       ated easily.

       A very simple and effective use for suba(3m) is as a  sub-allocator  of
       stack  memory that is implicitly	freed when the function	returns	as the
       follow code example illustrates:

		  unsigned char	chunk[0x3FFF]; /* 16K */
		  struct allocator *al = suba_init(chunk, 0x3FFF, 1, 0);
		  struct hashmap map;

		  hashmap_init(&map, 0,	hash_text, cmp_text, NULL, al);

		  /* use hashmap and allocator ... */

		  return 0; /* no cleanup necessary; all memory	on stack. */

       init   The suba_init function initializes a new	sub-allocator  or  at-
	      taches  to  an  existing allocator. The memory pointed to	by the
	      mem parameter must be at least size bytes. When the rst  parame-
	      ter is non-zero, the beginning of	this memory is "reset" meaning
	      it is initialized	with the struct	allocator structure  (discard-
	      ing  any existing	allocation state). The remaining memory, which
	      is size bytes minus the  header,	constitutes  the  "heap"  from
	      which  memory  will be allocated and freed. If the rst parameter
	      is zero, the existing header is used which presumably came  from
	      shared  memory  or a disk	file. If the mincell parameter is non-
	      zero, no memory "cell" will be less than	this  value  (i.e.  if
	      mincell  is  32  alloc-ing  5 bytes results in a 32 byte cell to
	      back it).	The mincell parameter will be increased	to  accomodate
	      memory  alignment	 requirements  if necessary. Larger values for
	      mincell can be faster but	results	in poorer memory utilization.

       alloc  The suba_alloc function returns a	 pointer  to  memory  of  size
	      bytes  from  the sub-allocator identified	by the suba parameter.
	      If the zero parameter is non-zero, the memory  will  be  set  to

       free   The  suba_free  function frees the memory	pointed	to by ptr back
	      into the allocator identified by suba parameter.

       addr   The suba_addr function converts an offset, relative to  the  be-
	      ginning  of the sub-allocator, of	the object idenfied by the ref
	      parameter	to a pointer in	the current processes  address	space.
	      This function is equivalent to the expression (char *)suba + ref
	      but with bounds checking.

       ref    The suba_ref function converts a pointer ptr that	points	to  an
	      object  allocated	 from the sub-allocator	identified by the suba
	      parameter	to an offset relative to the beginning of the  sub-al-
	      locator.	This  function	is  equivalent to the expression (char
	      *)ptr - (char *)suba but with bounds checking. See theSuba func-
	      tionssection  for	 a description of when it is necessary to con-
	      vert pointer to a	reference.

       init   The suba_init function returns a sub-allocator that can be  used
	      directly with the	other suba(3m) functions or with the more gen-
	      eral allocator(3m) functions used	by other modules in this pack-
	      age.  If an error	occurs a null pointer is returned and errno is
	      set accordingly.

       free   On success, 0 is returned. On error, -1 is returned,  and	 errno
	      is set appropriately.

       addr   The  suba_addr  function	returns	a pointer to the object	refer-
	      enced by ref or NULL if the reference was	invalid.

       ref    The suba_ref function returns an offset to the object pointed to
	      by ptr or	0 if the pointer was invalid.

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


Want to link to this manual page? Use this URL:

home | help