no-stddef-in-kernel-20021009
[openafs.git] / src / util / afs_atomlist.h
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 *
55 afs_atomlist_create
56 ( size_t atom_size
57 , size_t block_size
58 , void *(*allocate)(size_t n)
59 , void (*deallocate)(void *p, size_t n)
60 );
61
62 /*
63  * afs_atomlist_destroy() destroys the given afs_atomlist, freeing it
64  * and all space that may have been allocated from it.
65  */
66 void
67 afs_atomlist_destroy
68 ( afs_atomlist *al
69 );
70
71 /*
72  * afs_atomlist_get() returns a pointer to an unused atom.
73  */
74
75 void *
76 afs_atomlist_get
77 ( afs_atomlist *al
78 );
79
80 /*
81  * afs_atomlist_put() returns the given atom to the free list in the
82  * given afs_atomlist.
83  *
84  * It is an error to put back an atom that was not requested via
85  * afs_atomlist_get().
86  *
87  * It is an error to put back an atom that is already on the free list.
88  */
89
90 void
91 afs_atomlist_put
92 ( afs_atomlist *al
93 , void *data
94 );
95
96 #endif /* ATOMLIST_H */