docs/user/support/BlockCache.dox

   1 /*
   2  * Copyright 2007-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
   7  *              John Scipione, jscipione@gmail.com
   8  *
   9  * Proofreading:
  10  *              David Weizades, ddewbofh@hotmail.com
  11  *              Thom Holwerda, slakje@quicknet.nl
  12  *
  13  * Corresponds to:
  14  *              headers/os/support/BlockCache.h  rev 19972
  15  *              src/kits/support/BlockCache.cpp  rev 43545
  16  */
  17
  18
  19 /*!
  20         \file BlockCache.h
  21         \ingroup support
  22         \ingroup libbe
  23         \brief Implements a mechanism to store and retrieve memory blocks.
  24 */
  25
  26
  27 /*!
  28         \var B_OBJECT_CACHE
  29         \brief Used in the constructor of BBlockCache. Determines that objects will
  30                be created using \c new[] and \c delete[].
  31
  32         \since BeOS R3
  33 */
  34
  35
  36 /*!
  37         \var B_MALLOC_CACHE
  38         \brief Used in the constructor of BBlockCache. Determines that objects will
  39                be created using \c malloc() and \c free().
  40
  41         \since BeOS R3
  42 */
  43
  44
  45 /*!
  46         \class BBlockCache
  47         \ingroup support
  48         \ingroup libbe
  49         \brief A class that creates and maintains a pool of memory blocks.
  50
  51         In some performance critical code there might come a time where you require
  52         a lot of little blocks of memory that you want to access and dispose of
  53         continuously. Since allocating and freeing memory are 'expensive'
  54         operations, it is better to have a pool of memory blocks at your disposal.
  55         Luckily, the Haiku API provides a class that will act as the administrator
  56         of your memory pool, so you will not have to reinvent the wheel every time.
  57
  58         The principle is easy. The constructor takes the number of blocks you
  59         want to create beforehand, the size of the blocks, and the method of
  60         allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE.
  61         The first one uses C++ operators \c new[] and \c delete[], while the second
  62         one uses \c malloc() and \c free(). Unless you have specific demands on
  63         performance or you want to take care of freeing the objects yourself, either
  64         way works fine.
  65
  66         As soon as you have the memory pool, you can Get() blocks. If the
  67         pre-allocated memory blocks run out, BBlockCache will allocate new ones, so
  68         you will not have to worry about availability. As soon as you are done you
  69         can Save() the memory back into the pool. BBlockCache will make sure that no
  70         more blocks will be saved than the initial number you requested when you
  71         created the object, so be aware of that.
  72
  73         As soon as you got a pointer from the Get() method, you own that block of
  74         memory; this means that you have the liberty to dispose of it yourself. It
  75         also means that when you delete your BBlockCache instance, any blocks of
  76         memory that are checked out will not be destroyed. In case you might want to
  77         delete your objects yourself, make sure you free the memory the right way.
  78         If you created the object as #B_OBJECT_CACHE, use \c delete[] to free your
  79         object. If you created the object as #B_MALLOC_CACHE, use \c free(). Please
  80         note that it defeats the purpose of this class if your are going to free all
  81         the objects yourself since it basically means that when the pool runs out,
  82         Get() will be allocating the objects by itself.
  83
  84         \note BBlockCache is thread-safe.
  85
  86         \since BeOS R3
  87 */
  88
  89
  90 /*!
  91         \fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32
  92                 allocationType)
  93         \brief Allocate a new memory pool.
  94
  95         \param blockCount The number of free memory blocks you want to allocate
  96                initially. This number is also used as the maximum number of free
  97                blocks that will be kept.
  98         \param blockSize The size of the blocks.
  99         \param allocationType Either #B_OBJECT_CACHE for using \c new[] and
 100                \c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free().
 101
 102         \since BeOS R3
 103 */
 104
 105
 106 /*!
 107         \fn BBlockCache::~BBlockCache()
 108         \brief Destroy the empty blocks in the free list.
 109
 110         Note that the blocks you checked out with Get() and not checked back in with
 111         Save() will not be freed, since ownership belongs to you. Make sure you
 112         clean up after yourself.
 113
 114         \since BeOS R3
 115 */
 116
 117
 118 /*!
 119         \fn void* BBlockCache::Get(size_t blockSize)
 120         \brief Get a block from the pool of free blocks.
 121
 122         If the pool runs out of free blocks, a new one will be allocated. Please
 123         note that if the size given in the \c blockSize parameter is different from
 124         the size given in the constructor, a new block of memory will be created.
 125         Only sizes that match the blocks in the memory pool will come from the pool.
 126
 127         \param blockSize The required size of the memory block.
 128
 129         \return Returns a pointer to a memory block, or \c NULL if locking the
 130                 object failed.
 131
 132         \since BeOS R3
 133 */
 134
 135
 136 /*!
 137         \fn void BBlockCache::Save(void* pointer, size_t blockSize)
 138         \brief Save a block of memory to the memory pool.
 139
 140         The block of memory will only be added to the pool if the \c blockSize is
 141         equal to the size the object was created with and if the maximum number of
 142         free blocks in the list will not be exceeded. If not, the memory will be
 143         freed.
 144
 145         Note that it is perfectly valid to pass objects other than those you got
 146         from Get(), but please note that the way it was created conforms to the way
 147         memory is allocated and freed in this pool. Therefore, only feed blocks that
 148         were created with \c new[] if the allocation type is #B_OBJECT_CACHE.
 149         Likewise, you should only use objects allocated with \c malloc() when the
 150         allocation type is #B_MALLOC_CACHE.
 151
 152         \since BeOS R3
 153 */