0a3e13aa3b8e879862b8b7a9701e779751000d8a
[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 #include <stddef.h>
32
33 typedef struct afs_atomlist afs_atomlist;
34
35 /*
36  * afs_atomlist_create() creates a new afs_atomlist.
37  *
38  * atom_size -- the number of bytes of space that afs_atomlist_get() should
39  *              return
40  *
41  * block_size -- the number of bytes that afs_atomlist_get() should allocate
42  *               at a time
43  *
44  * allocate() -- allocates memory
45  *
46  * deallocate() -- frees memory acquired via allocate()
47  *
48  * afs_atomlist_create() returns a pointer to the new afs_atomlist, or 0
49  * on error.
50  */
51
52 afs_atomlist *
53 afs_atomlist_create
54 ( size_t atom_size
55 , size_t block_size
56 , void *(*allocate)(size_t n)
57 , void (*deallocate)(void *p, size_t n)
58 );
59
60 /*
61  * afs_atomlist_destroy() destroys the given afs_atomlist, freeing it
62  * and all space that may have been allocated from it.
63  */
64 void
65 afs_atomlist_destroy
66 ( afs_atomlist *al
67 );
68
69 /*
70  * afs_atomlist_get() returns a pointer to an unused atom.
71  */
72
73 void *
74 afs_atomlist_get
75 ( afs_atomlist *al
76 );
77
78 /*
79  * afs_atomlist_put() returns the given atom to the free list in the
80  * given afs_atomlist.
81  *
82  * It is an error to put back an atom that was not requested via
83  * afs_atomlist_get().
84  *
85  * It is an error to put back an atom that is already on the free list.
86  */
87
88 void
89 afs_atomlist_put
90 ( afs_atomlist *al
91 , void *data
92 );
93
94 #endif /* ATOMLIST_H */