A class that creates and maintains a pool of memory blocks. More...
|BBlockCache (uint32 blockCount, size_t blockSize, uint32 allocationType)|
|Allocate a new memory pool. More...|
|Destroy the empty blocks in the free list. More...|
|void *||Get (size_t blockSize)|
|Get a block from the pool of free blocks. More...|
|void||Save (void *pointer, size_t blockSize)|
|Save a block of memory to the memory pool. More...|
A class that creates and maintains a pool of memory blocks.
In some performance critical code there might come a time where you require a lot of little blocks of memory that you want to access and dispose of continuously. Since allocating and freeing memory are 'expensive' operations, it is better to have a pool of memory blocks at your disposal. Luckily, the Haiku API provides a class that will act as the administrator of your memory pool, so you will not have to reinvent the wheel every time.
The principle is easy. The constructor takes the number of blocks you want to create beforehand, the size of the blocks, and the method of allocation. This can either be B_OBJECT_CACHE or B_MALLOC_CACHE. The first one uses C++ operators
delete, while the second one uses
free(). Unless you have specific demands on performance or you want to take care of freeing the objects yourself, either way works fine.
As soon as you have the memory pool, you can Get() blocks. If the pre-allocated memory blocks run out, BBlockCache will allocate new ones, so you will not have to worry about availability. As soon as you are done you can Save() the memory back into the pool. BBlockCache will make sure that no more blocks will be saved than the initial number you requested when you created the object, so be aware of that.
As soon as you got a pointer from the Get() method, you own that block of memory; this means that you have the liberty to dispose of it yourself. It also means that when you delete your BBlockCache instance, any blocks of memory that are checked out will not be destroyed. In case you might want to delete your objects yourself, make sure you free the memory the right way. If you created the object as B_OBJECT_CACHE, use
delete to free your object. If you created the object as B_MALLOC_CACHE, use
free(). Please note that it defeats the purpose of this class if your are going to free all the objects yourself since it basically means that when the pool runs out, Get() will be allocating the objects by itself.
Allocate a new memory pool.
|blockCount||The number of free memory blocks you want to allocate initially. This number is also used as the maximum number of free blocks that will be kept.|
|blockSize||The size of the blocks.|
|allocationType||Either B_OBJECT_CACHE for using |
|void * BBlockCache::Get||(||size_t||blockSize||)|
Get a block from the pool of free blocks.
If the pool runs out of free blocks, a new one will be allocated. Please note that if the size given in the
blockSize parameter is different from the size given in the constructor, a new block of memory will be created. Only sizes that match the blocks in the memory pool will come from the pool.
|blockSize||The required size of the memory block.|
NULLif locking the object failed.
|void BBlockCache::Save||(||void *||pointer,|
Save a block of memory to the memory pool.
The block of memory will only be added to the pool if the
blockSize is equal to the size the object was created with and if the maximum number of free blocks in the list will not be exceeded. If not, the memory will be freed.
Note that it is perfectly valid to pass objects other than those you got from Get(), but please note that the way it was created conforms to the way memory is allocated and freed in this pool. Therefore, only feed blocks that were created with
new if the allocation type is B_OBJECT_CACHE. Likewise, you should only use objects allocated with
malloc() when the allocation type is B_MALLOC_CACHE.