i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update according to the latest guideline changes. These files already

Browse Source 
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
2007-08-06 09:32:27 +00:00
parent ff3d9bfa2a
commit 55f7db1bd9
3 changed files with 595 additions and 520 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/support/Archivable.dox
+42 -22
View File
@@ -3,22 +3,24 @@
* Distributed under the terms of the MIT License.
*
* Author:
* Niels Sascha Reedijk <[email protected]>
* Niels Sascha Reedijk, [email protected]
*
* Proofreader:
* David Weizades <[email protected]>
* Thom Holwerda <[email protected]>
* David Weizades, [email protected]
* Thom Holwerda, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 19972
* /trunk/src/kits/support/Archivable.cpp rev 19095
*/
/*!
\file Archivable.h
\brief Provides the BArchivable interface.
*/
/*!
\class BArchivable
\ingroup support
@@ -32,58 +34,65 @@
BArchivable differs from BFlattenable in that BFlattenable is designed to
store objects into flat streams of data, the main objective being storage to
disk. The objective of this interface, however, is to store objects that will
be restored to other objects. To illustrate this point, BArchivable messages
know how to restore themselves whereas BFlattenables have a datatype which
you need to map to classes manually.
disk. The objective of this interface, however, is to store objects that
will be restored to other objects. To illustrate this point, BArchivable
messages know how to restore themselves whereas BFlattenables have a
datatype which you need to map to classes manually.
Archiving is done with the Archive() method. If your class supports it, the
caller can request it to store into a deep archive, meaning that all child
objects in it will be stored. Extracting the archive works with the
Instantiate() method, which is static. Since the interface is designed to
extract objects without the caller knowing what kind of object it actually is,
the global function #instantiate_object() instantiates a message without you
manually having to determine the class the message is from. This adds
considerable flexibility and allows BArchivable to be used in combination with
other add-ons.
extract objects without the caller knowing what kind of object it actually
is, the global function #instantiate_object() instantiates a message without
you manually having to determine the class the message is from. This adds
considerable flexibility and allows BArchivable to be used in combination
with other add-ons.
To provide this interface in your classes you should publicly inherit this
class. You should implement Archive() and Instantiate(), and provide one
constructor that takes one BMessage argument.
*/
/*!
\fn BArchivable::BArchivable(BMessage* from)
\brief Constructor. Does nothing.
If you inherit this interface you should provide at least one constructor that
takes one BMessage argument.
If you inherit this interface you should provide at least one constructor
that takes one BMessage argument.
*/
/*!
\fn BArchivable::BArchivable()
\brief Constructor. Does nothing.
*/
/*!
\fn BArchivable::~BArchivable()
\brief Destructor. Does nothing.
*/
/*!
\fn virtual status_t BArchivable::Archive(BMessage* into, bool deep = true) const
\fn virtual status_t BArchivable::Archive(BMessage* into,
bool deep = true) const
\brief Archive the object into a BMessage.
You should call this method from your derived implementation as it adds the
data needed to instantiate your object to the message.
\param into The message you store your object in.
\param deep If \c true, all children of this object should be stored as well.
Only pay attention to this parameter if you actually have child objects.
\param deep If \c true, all children of this object should be stored as
well. Only pay attention to this parameter if you actually have child
objects.
\retval B_OK The archiving succeeded.
\retval "error codes" The archiving did not succeed.
*/
/*!
\fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
\brief Static member to restore objects from messages.
@@ -96,11 +105,12 @@
\retval You should return a pointer to your object, or \c NULL if you
fail.
\warning The default implementation will always return \c NULL. Even though
it is possible to store plain BArchive objects, it is impossible to restore
them.
it is possible to store plain BArchive objects, it is impossible to
restore them.
\see instantiate_object(BMessage *from)
*/
/*!
\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
\brief Internal method.
@@ -108,18 +118,21 @@
API issues. Currently nothing of interest is implemented.
*/
///// Global methods /////
/*!
\addtogroup support_globals
@{
*/
/*!
\typedef typedef BArchivable* (*instantiation_func)(BMessage*)
\brief Internal definition of a function that can instantiate objects that
have been created with the BArchivable API.
*/
/*!
\fn BArchivable* instantiate_object(BMessage *from, image_id *id)
\brief Instantiate an archived object with the object being defined in a
@@ -134,6 +147,7 @@
at the kernel API for further information.
*/
/*!
\fn BArchivable* instantiate_object(BMessage *from)
\brief Instantiate an archived object.
@@ -144,33 +158,39 @@
\param from The archived object.
\return The object returns a pointer to the instantiated object, or \c NULL
if the instantiation failed. The global \c errno variable will contain the
reason why it failed.
if the instantiation failed. The global \c errno variable will contain
the reason why it failed.
\see instantiate_object(BMessage *from, image_id *id)
*/
/*!
\fn bool validate_instantiation(BMessage* from, const char* className)
\brief Internal function that checks if the \a className is the same as the
one stored in the \a from message.
*/
/*!
\fn instantiation_func find_instantiation_func(const char* className, const char* signature)
\fn instantiation_func find_instantiation_func(const char* className,
const char* signature)
\brief Internal function that searches for the instantiation func with a
specific signature. Use instantiate_object() instead.
*/
/*!
\fn instantiation_func find_instantiation_func(const char* className)
\brief Internal function that searches for the instantiation func of a
specific class. Use instantiate_object() instead.
*/
/*!
\fn instantiation_func find_instantiation_func(BMessage* archive)
\brief Internal function that searches for the instantiation func that
works on the specified \a archive. Use instantiate_object() instead.
*/
//! @}
docs/user/support/BlockCache.dox
+39 -30
View File
@@ -3,46 +3,50 @@
* 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.
*/
/*!
\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().
*/
/*!
\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.
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
@@ -54,17 +58,17 @@
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.
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
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,
@@ -73,8 +77,10 @@
\note BBlockCache is thread-safe.
*/
/*!
\fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType)
\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
@@ -85,29 +91,32 @@
\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.
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.
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.
\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.
@@ -117,10 +126,10 @@
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.
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.
*/
docs/user/support/List.dox
+79 -33
View File
@@ -3,23 +3,25 @@
* 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]>
* John Drinkwater <[email protected]>
* David Weizades, [email protected]
* Thom Holwerda, [email protected]
* John Drinkwater, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/List.h rev 19972
* /trunk/src/kits/support/List.cpp rev 18649
*/
/*!
\file List.h
\brief Defines the BList class.
*/
/*!
\class BList
\ingroup support
@@ -34,36 +36,38 @@
itself.
BList contains a list of items that will grow and shrink depending on how
many items are in it. So you will not have to do any of the memory management
nor any ordering. These properties makes it useful in a whole range of
situations such as the interface kit within the BListView class.
many items are in it. So you will not have to do any of the memory
management nor any ordering. These properties makes it useful in a whole
range of situations such as the interface kit within the BListView class.
A note on the ownership of the objects might come in handy. BList never
assumes ownership of the objects. As such, removing items from the list will
only remove the entries from the list; it will not delete the items
themselves. Similarly, you should also make sure that before you might delete
an object that is in a list, you will have to remove it from the list first.
themselves. Similarly, you should also make sure that before you might
delete an object that is in a list, you will have to remove it from the list
first.
\warning This class is not thread-safe.
The class implements methods to add, remove, reorder, retrieve, and query
items as well as some advanced methods which let you perform a task on all the
items in the list.
items as well as some advanced methods which let you perform a task on all
the items in the list.
*/
/*!
\fn BList::BList(int32 count = 20)
\brief Create a new list with a number of empty slots.
The memory management of this class allocates new memory per block. The
\c count parameter can be tweaked to determine the size of these blocks.
In general, if you know your list is only going to contain a certain number of
items at most, you can pass that value. If you expect your list to have very
few items, it is safe to choose a low number. This is to prevent the list from
taking up unneeded memory. If you expect the list to contain a large number
of items, choose a higher value. Every time the memory is full, all the items
have to be copied into a new piece of allocated memory, which is an expensive
operation.
In general, if you know your list is only going to contain a certain number
of items at most, you can pass that value. If you expect your list to have
very few items, it is safe to choose a low number. This is to prevent the
list from taking up unneeded memory. If you expect the list to contain a
large number of items, choose a higher value. Every time the memory is full,
all the items have to be copied into a new piece of allocated memory, which
is an expensive operation.
If you are unsure, you do not have to worry too much. Just make sure you do
not use a lot of lists, and as long as the list is not used in one of the
@@ -73,11 +77,13 @@
\param count The size of the blocks allocated in memory.
*/
/*!
\fn BList::BList(const BList& anotherList)
\brief Copy constructor. Copy a complete list into this one.
*/
/*!
\fn BList::~BList()
\brief Destroy the list.
@@ -86,17 +92,21 @@
only the list will be freed, not the objects that are held in it.
*/
/*!
\fn BList& BList::operator=(const BList &list)
\brief Copy another list into this object.
*/
/*!
\name Adding and Removing Items
*/
//! @{
/*!
\fn bool BList::AddItem(void *item, int32 index)
\brief Add an item at a certain position.
@@ -109,6 +119,7 @@
\see AddItem(void *item)
*/
/*!
\fn bool BList::AddItem(void *item)
\brief Append an item to the list.
@@ -119,22 +130,24 @@
\see AddItem(void *item, int32 index)
*/
/*!
\fn bool BList::AddList(const BList *list, int32 index)
\brief Add items from another list to this list at a certain position.
Note that the \a list parameter is \c const, so the original list will not be
altered.
Note that the \a list parameter is \c const, so the original list will not
be altered.
\param list The list to be added.
\param index The position in the current list where the new item(s) should be
put.
\param index The position in the current list where the new item(s) should
be put.
\retval true The list was added.
\retval false Failed to insert the list, due to the fact that resizing our
list failed.
\see AddList(const BList *list)
*/
/*!
\fn bool BList::AddList(const BList *list)
\brief Append a list to this list.
@@ -144,11 +157,12 @@
\param list The list to be appended.
\retval true The list was appended.
\retval false Failed to append the list, due to the fact that resizing of our
list failed.
\retval false Failed to append the list, due to the fact that resizing of
our list failed.
\see AddList(const BList *list, int32 index)
*/
/*!
\fn bool BList::RemoveItem(void *item)
\brief Remove an item from the list.
@@ -159,6 +173,7 @@
\see RemoveItem(int32 index)
*/
/*!
\fn void * BList::RemoveItem(int32 index)
\brief Remove the item at \a index from the list.
@@ -169,6 +184,7 @@
\see RemoveItem(void *item)
*/
/*!
\fn bool BList::RemoveItems(int32 index, int32 count)
\brief Remove a number of items starting at a certain position.
@@ -182,6 +198,7 @@
\retval false Failed to remove the items because the index was invalid.
*/
/*!
\fn bool BList::ReplaceItem(int32 index, void *newItem)
\brief Replace an item with another one.
@@ -192,6 +209,7 @@
\retval false The index was invalid.
*/
/*!
\fn void BList::MakeEmpty()
\brief Clear all the items from the list.
@@ -199,24 +217,29 @@
Please note that this does not free the items.
*/
//! @}
/*!
\name Reordering Items
*/
//! @{
/*!
\fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
\brief Sort the items with the use of a supplied comparison function.
The function should take two \c const pointers as arguments and should return
an integer.
The function should take two \c const pointers as arguments and should
return an integer.
For an example, see the Compare(const BString *, const BString *) function.
*/
/*!
\fn bool BList::SwapItems(int32 indexA, int32 indexB)
\brief Swap two items.
@@ -227,6 +250,7 @@
\retval false Swap failed because one of the indexes was invalid.
*/
/*!
\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
\brief Move an item to a new place
@@ -248,14 +272,18 @@ A C D E F G B H I J
\retval false Move failed due to the indexes being invalid.
*/
//! @}
/*!
\name Retrieving Items
*/
//! @{
/*!
\fn void *BList::ItemAt(int32 index) const
\brief Get an item.
@@ -266,6 +294,7 @@ A C D E F G B H I J
\see ItemAtFast(int32 index) const
*/
/*!
\fn void *BList::FirstItem() const
\brief Get the first item.
@@ -274,6 +303,7 @@ A C D E F G B H I J
\see LastItem() const
*/
/*!
\fn void *BList::ItemAtFast(int32 index) const
\brief Get an item.
@@ -285,6 +315,7 @@ A C D E F G B H I J
\return A pointer to the item.
*/
/*!
\fn void *BList::LastItem() const
\brief Get the last item.
@@ -292,38 +323,44 @@ A C D E F G B H I J
\see FirstItem() const
*/
/*!
\fn void *BList::Items() const
\brief Return the internal list of objects.
This method will return a pointer to the internal pointer list. This means
that you should be careful what you are doing, since you are working with the
internals of the class directly.
that you should be careful what you are doing, since you are working with
the internals of the class directly.
It is not a good idea to make any changes to the list, since that will mess
up the internal consistency.
\warning If there is anything you want, for which you need the list of
objects, please realize that that probably means that what you want to do is
a bad idea to begin with and that you should avoid this method. The list of
objects does not belong to you. See also DoForEach() for an alternate
method.
objects, please realize that that probably means that what you want to
do is a bad idea to begin with and that you should avoid this method.
The list of objects does not belong to you. See also DoForEach() for an
alternate method.
\return The internal list of pointers.
*/
//! @}
/*!
\name Querying for Items
*/
//! @{
/*!
\fn bool BList::HasItem(void *item) const
\brief Check if an item is in the list.
*/
/*!
\fn int32 BList::IndexOf(void *item) const
\brief Get the index of an item.
@@ -331,24 +368,30 @@ A C D E F G B H I J
\return The index of the item, or -1 when the item is not in the list.
*/
/*!
\fn int32 BList::CountItems() const
\brief Get the number of items in the list.
*/
/*!
\fn bool BList::IsEmpty() const
\brief Check if there are items in the list.
*/
//! @}
/*!
\name Iterating over the List
*/
//! @{
/*!
\fn void BList::DoForEach(bool (*func)(void* item))
\brief Perform an action on every item in the list.
@@ -356,10 +399,12 @@ A C D E F G B H I J
If one of the actions on the items fails it means that the \a func function
returned \c false and the processing of the list will be stopped.
\param func A function that takes a \c void * argument and returns a boolean.
\param func A function that takes a \c void * argument and returns a
boolean.
\see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
*/
/*!
\fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
\brief Perform an action on every item in the list with an argument.
@@ -374,4 +419,5 @@ A C D E F G B H I J
\see DoForEach(bool (*func)(void* item))
*/
//! @}