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