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