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 *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 */