[hcoop/debian/openafs.git] / src / util / afs_atomlist.h

/*
 * Copyright 2000, International Business Machines Corporation and others.
 * All Rights Reserved.
 *
 * This software has been released under the terms of the IBM Public
 * License.  For details, see the LICENSE file in the top-level source
 * directory or online at http://www.openafs.org/dl/license10.html
 */

/*
 * An afs_atomlist is a memory allocation facility.
 *
 * You can request atoms of storage from the list, and return them to
 * the list when you are done with them.  All the atoms in a given atom
 * list are the same size.
 *
 * The reason to use an afs_atomlist instead of allocating and freeing
 * memory directly is to avoid memory fragmentation.  Storage for the
 * atoms is allocated in blocks of the given size, then handed out as
 * requested.
 *
 * When the atom list is destroyed, all the atoms allocated from it are
 * freed, regardless of whether they have been returned to the list.
 *
 * The caller is responsible for doing any required locking.
 */

#ifndef ATOMLIST_H
#define ATOMLIST_H

#ifndef KERNEL
#include <stddef.h>
#endif

typedef struct afs_atomlist afs_atomlist;

/*
 * afs_atomlist_create() creates a new afs_atomlist.
 *
 * atom_size -- the number of bytes of space that afs_atomlist_get() should
 *              return
 *
 * block_size -- the number of bytes that afs_atomlist_get() should allocate
 *               at a time
 *
 * allocate() -- allocates memory
 *
 * deallocate() -- frees memory acquired via allocate()
 *
 * afs_atomlist_create() returns a pointer to the new afs_atomlist, or 0
 * on error.
 */

afs_atomlist *afs_atomlist_create(size_t atom_size, size_t block_size,
				  void *(*allocate) (size_t n)
				  , void (*deallocate) (void *p, size_t n)
    );

/*
 * afs_atomlist_destroy() destroys the given afs_atomlist, freeing it
 * and all space that may have been allocated from it.
 */
void
  afs_atomlist_destroy(afs_atomlist * al);

/*
 * afs_atomlist_get() returns a pointer to an unused atom.
 */

void *afs_atomlist_get(afs_atomlist * al);

/*
 * afs_atomlist_put() returns the given atom to the free list in the
 * given afs_atomlist.
 *
 * It is an error to put back an atom that was not requested via
 * afs_atomlist_get().
 *
 * It is an error to put back an atom that is already on the free list.
 */

void
  afs_atomlist_put(afs_atomlist * al, void *data);

#endif /* ATOMLIST_H */
Commit	Line	Data
805e021f CE	1	/*
	2	* Copyright 2000, International Business Machines Corporation and others.
	3	* All Rights Reserved.
	4	*
	5	* This software has been released under the terms of the IBM Public
	6	* License. For details, see the LICENSE file in the top-level source
	7	* directory or online at http://www.openafs.org/dl/license10.html
	8	*/
	9
	10	/*
	11	* An afs_atomlist is a memory allocation facility.
	12	*
	13	* You can request atoms of storage from the list, and return them to
	14	* the list when you are done with them. All the atoms in a given atom
	15	* list are the same size.
	16	*
	17	* The reason to use an afs_atomlist instead of allocating and freeing
	18	* memory directly is to avoid memory fragmentation. Storage for the
	19	* atoms is allocated in blocks of the given size, then handed out as
	20	* requested.
	21	*
	22	* When the atom list is destroyed, all the atoms allocated from it are
	23	* freed, regardless of whether they have been returned to the list.
	24	*
	25	* The caller is responsible for doing any required locking.
	26	*/
	27
	28	#ifndef ATOMLIST_H
	29	#define ATOMLIST_H
	30
	31	#ifndef KERNEL
	32	#include <stddef.h>
	33	#endif
	34
	35	typedef struct afs_atomlist afs_atomlist;
	36
	37	/*
	38	* afs_atomlist_create() creates a new afs_atomlist.
	39	*
	40	* atom_size -- the number of bytes of space that afs_atomlist_get() should
	41	* return
	42	*
	43	* block_size -- the number of bytes that afs_atomlist_get() should allocate
	44	* at a time
	45	*
	46	* allocate() -- allocates memory
	47	*
	48	* deallocate() -- frees memory acquired via allocate()
	49	*
	50	* afs_atomlist_create() returns a pointer to the new afs_atomlist, or 0
	51	* on error.
	52	*/
	53
	54	afs_atomlist *afs_atomlist_create(size_t atom_size, size_t block_size,
	55	void (allocate) (size_t n)
	56	, void (deallocate) (void p, size_t n)
	57	);
	58
	59	/*
	60	* afs_atomlist_destroy() destroys the given afs_atomlist, freeing it
	61	* and all space that may have been allocated from it.
	62	*/
	63	void
	64	afs_atomlist_destroy(afs_atomlist * al);
65
66	/*
67	* afs_atomlist_get() returns a pointer to an unused atom.
68	*/
69
70	void afs_atomlist_get(afs_atomlist al);
71
72	/*
73	* afs_atomlist_put() returns the given atom to the free list in the
74	* given afs_atomlist.
75	*
76	* It is an error to put back an atom that was not requested via
77	* afs_atomlist_get().
78	*
79	* It is an error to put back an atom that is already on the free list.
80	*/
81
82	void
83	afs_atomlist_put(afs_atomlist * al, void *data);
84
85	#endif /* ATOMLIST_H */