Update according to the latest guideline changes. These files already
passed phase 3, so they wouldn't be updated during the regular process. I guess the other files will get that update. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21833 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
@@ -3,124 +3,133 @@
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Niels Sascha Reedijk <[email protected]>
|
||||
* Niels Sascha Reedijk, [email protected]
|
||||
*
|
||||
* Proofreading:
|
||||
* David Weizades <[email protected]>
|
||||
* Thom Holwerda <[email protected]>
|
||||
* David Weizades, [email protected]
|
||||
* Thom Holwerda, [email protected]
|
||||
*
|
||||
* Corresponds to:
|
||||
* /trunk/headers/os/support/BlockCache.h rev 19972
|
||||
* /trunk/src/kits/support/BlockCache.cpp rev 4568
|
||||
*/
|
||||
|
||||
|
||||
|
||||
/*!
|
||||
\file BlockCache.h
|
||||
\brief Implements a mechanism to store and retrieve memory blocks.
|
||||
\file BlockCache.h
|
||||
\brief Implements a mechanism to store and retrieve memory blocks.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var B_OBJECT_CACHE
|
||||
\brief Used in the constructor of BBlockCache. Determines that objects will
|
||||
be created using \c new[] and \c delete[].
|
||||
\var B_OBJECT_CACHE
|
||||
\brief Used in the constructor of BBlockCache. Determines that objects will
|
||||
be created using \c new[] and \c delete[].
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var B_MALLOC_CACHE
|
||||
\brief Used in the constructor of BBlockCache. Determines that objects will
|
||||
be created using \c malloc() and \c free().
|
||||
\var B_MALLOC_CACHE
|
||||
\brief Used in the constructor of BBlockCache. Determines that objects will
|
||||
be created using \c malloc() and \c free().
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\class BBlockCache
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief 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 \c new[] and \c delete[], while the second
|
||||
one uses \c malloc() and \c 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 \c delete[] to free your
|
||||
object. If you created the object as #B_MALLOC_CACHE, use \c 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.
|
||||
|
||||
\note BBlockCache is thread-safe.
|
||||
\class BBlockCache
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief 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 \c new[] and \c delete[], while the second
|
||||
one uses \c malloc() and \c 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 \c delete[] to free your
|
||||
object. If you created the object as #B_MALLOC_CACHE, use \c 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.
|
||||
|
||||
\note BBlockCache is thread-safe.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType)
|
||||
\brief Allocate a new memory pool.
|
||||
|
||||
\param 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.
|
||||
\param blockSize The size of the blocks.
|
||||
\param allocationType Either #B_OBJECT_CACHE for using \c new[] and
|
||||
\c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free().
|
||||
\fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32
|
||||
allocationType)
|
||||
\brief Allocate a new memory pool.
|
||||
|
||||
\param 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.
|
||||
\param blockSize The size of the blocks.
|
||||
\param allocationType Either #B_OBJECT_CACHE for using \c new[] and
|
||||
\c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free().
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BBlockCache::~BBlockCache()
|
||||
\brief Destroy the empty blocks in the free list.
|
||||
|
||||
Note that the blocks you checked out with Get() and not checked back in with
|
||||
Save() will not be freed, since ownership belongs to you. Make sure you clean
|
||||
up after yourself.
|
||||
\fn BBlockCache::~BBlockCache()
|
||||
\brief Destroy the empty blocks in the free list.
|
||||
|
||||
Note that the blocks you checked out with Get() and not checked back in with
|
||||
Save() will not be freed, since ownership belongs to you. Make sure you
|
||||
clean up after yourself.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void *BBlockCache::Get(size_t blockSize)
|
||||
\brief 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 \c 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.
|
||||
|
||||
\param blockSize The required size of the memory block.
|
||||
\return Returns a pointer to a memory block, or \c NULL if locking the object
|
||||
failed.
|
||||
\fn void *BBlockCache::Get(size_t blockSize)
|
||||
\brief 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 \c 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.
|
||||
|
||||
\param blockSize The required size of the memory block.
|
||||
\return Returns a pointer to a memory block, or \c NULL if locking the
|
||||
object failed.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void BBlockCache::Save(void *pointer, size_t blockSize)
|
||||
\brief Save a block of memory to the memory pool.
|
||||
|
||||
The block of memory will only be added to the pool if the \c 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 \c new[] if the allocation type is #B_OBJECT_CACHE. Likewise,
|
||||
you should only use objects allocated with \c malloc() when the allocation
|
||||
type is #B_MALLOC_CACHE.
|
||||
\fn void BBlockCache::Save(void *pointer, size_t blockSize)
|
||||
\brief Save a block of memory to the memory pool.
|
||||
|
||||
The block of memory will only be added to the pool if the \c 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 \c new[] if the allocation type is #B_OBJECT_CACHE.
|
||||
Likewise, you should only use objects allocated with \c malloc() when the
|
||||
allocation type is #B_MALLOC_CACHE.
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user