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

Update Support Kit docs, add \since

Browse Source 
Also add preliminary documentation for BObjectList.
This commit is contained in:
John Scipione
2014-06-24 19:30:54 -04:00
parent 29e8fa5922
commit c4b9309a99
17 changed files with 2695 additions and 1080 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/support/Architecture.dox
+34 -17
View File
@@ -1,13 +1,14 @@
/*
* Copyright 2013, Haiku, Inc. All rights reserved.
* Copyright 2013-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* John Scipione, [email protected]
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/PathFinder.h hrev46390
* src/kits/storage/PathFinder.cpp hrev46390
* headers/os/support/Architecture.h hrev47419
* src/kits/support/Architecture.cpp hrev47419
*/
@@ -16,7 +17,7 @@
\ingroup support
\ingroup libbe
\brief Provides functions for getting the primary and secondary
architectures of the system.
architectures of the system.
*/
@@ -30,6 +31,8 @@
\return The name of the caller's architecture.
\see get_primary_architecture()
\since Haiku R1
*/
@@ -40,6 +43,8 @@
This is the packaging architecture the main system has been built for.
\return The name of the system's primary architecture.
\since Haiku R1
*/
@@ -56,12 +61,15 @@
if it would be possible to install the support for gcc 4.
\param architectures A pre-allocated array of size \a count where the names
of the secondary architectures will be stored. Can be \c NULL, if
\a count is 0.
of the secondary architectures will be stored. Can be \c NULL, if
\a count is 0.
\param count The size of the \a architectures array.
\return The actual number of secondary architectures. May be greater than
\a count, but at most \a count names will be written to
\a architectures.
\a count, but at most \a count names will be written to
\a architectures.
\since Haiku R1
*/
@@ -75,13 +83,16 @@
Note that this version can fail when running out of memory.
\param _architectures Reference to a BStringList that will be set to the
list of names of secondary architectures. On error the list will be
emptied.
list of names of secondary architectures. On error the list will be
emptied.
\return A status code.
\retval B_OK Everything went fine.
\retval B_NO_MEMORY A memory allocation failed.
\see get_secondary_architectures(const char**,size_t)
\since Haiku R1
*/
@@ -89,24 +100,24 @@
\fn size_t get_architectures(const char** architectures,
size_t count)
\brief Returns the names of the system's primary and secondary
architectures.
architectures.
This is a convenience function that returns both the primary architecture
as returned by get_primary_architecture() and the secondary architectures
as returned by get_secondary_architectures() in the provided array.
\param architectures A pre-allocated array of size \a count where the names
of the architectures will be stored. Can be \c NULL, if \a count is 0.
of the architectures will be stored. Can be \c NULL if \a count is 0.
\param count The size of the \a architectures array.
\return The actual number of architectures. May be greater than \a count,
but at most \a count names will be written to \a architectures.
but at most \a count names will be written to \a architectures.
*/
/*!
\fn status_t get_architectures(BStringList& _architectures)
\brief Returns the names of the system's primary and secondary
architectures.
architectures.
This is a C++ interface similar to
get_architectures(const char**,size_t). Instead of returning the
@@ -114,13 +125,16 @@
Note that this version can fail when running out of memory.
\param _architectures Reference to a BStringList that will be set to the
list of names of primary and secondary architectures. On error the list
will be emptied.
list of names of primary and secondary architectures. On error the
list will be emptied.
\return A status code.
\retval B_OK Everything went fine.
\retval B_NO_MEMORY A memory allocation failed.
\see get_architectures(const char**,size_t)
\since Haiku R1
*/
@@ -135,6 +149,9 @@
inconclusive the name of the primary architecture is returned.
\param path The path to be analyzed. It doesn't necessarily have to point to
an existing file or directory.
an existing file or directory.
\return The name of the architecture determined from \a path.
\since Haiku R1
*/
docs/user/support/Archivable.dox
+190 -91
View File
@@ -5,6 +5,7 @@
* Authors:
* Niels Sascha Reedijk, [email protected]
* Alex Wilson, [email protected]
* John Scipione, [email protected]
*
* Proofreader:
* David Weizades, [email protected]
@@ -21,7 +22,7 @@
\ingroup support
\ingroup libbe
\brief Provides the BArchivable interface and declares the BArchiver and
BUnarchiver classes.
BUnarchiver classes.
*/
@@ -64,6 +65,8 @@
You should also consider implementing the AllArchived() and AllUnarchived()
methods, which were designed to ease archiving and unarchiving in such
a situation.
\since BeOS R3
*/
@@ -76,36 +79,43 @@
that takes one BMessage argument. In that constructor, you should call
your parent class' archive constructor (even if your parent class is
BArchivable).
\since BeOS R3
*/
/*!
\fn BArchivable::BArchivable()
\brief Constructor. Does nothing.
\since BeOS R3
*/
/*!
\fn BArchivable::~BArchivable()
\brief Destructor. Does nothing.
\since BeOS R3
*/
/*!
\fn virtual status_t BArchivable::Archive(BMessage* into,
bool deep = true) const
\fn virtual status_t BArchivable::Archive(BMessage* into, bool deep) 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 archived as
well.
well.
\retval B_OK The archive operation was successful.
\retval B_BAD_VALUE \c NULL \a archive message.
\retval B_ERROR The archive operation failed.
\since BeOS R3
*/
@@ -117,17 +127,22 @@
your class. The automatic functions, such as #instantiate_object() and
BUnarchiver::InstantiateObject() will not choose the wrong class but manual
calls to this member might be faulty. You can verify that \c archive
stores an object of your calss with the validate_instantiation() function.
stores an object of your class with the validate_instantiation() function.
\param archive The message with the data of the object to restore.
\return A pointer to a BArchivable object.
\retval You should return a pointer to the object you create with
\c archive, or \c NULL if unarchival fails.
\c archive, or \c NULL if the unarchival fails.
\warning The default implementation will always return \c NULL. Even though
it is possible to store plain BArchivable objects, it is impossible to
restore them.
restore them.
\see instantiate_object(BMessage *from)
\see instantiate_object(BMessage*)
\see BUnarchiver::InstantiateObject()
\since BeOS R3
*/
@@ -137,13 +152,16 @@
compatibility purposes).
\internal This method is defined for binary compatibility purposes, it is
used to ensure that the correct AllUnarchived() and AllArchived()
methods are called for objects, as those methods are new to Haiku.
used to ensure that the correct AllUnarchived() and AllArchived()
methods are called for objects, as those methods are new to
Haiku.
\param d The perform code.
\param arg A pointer to store some data.
\returns A status code.
\since Haiku R1
*/
@@ -158,10 +176,12 @@
their parent class, the same as for the Archive() method.
\warning To guarantee that your AllUnarchived() method will be called
during unarchival, you must create a BUnarchiver object in your
archive constructor.
during unarchival, you must create a BUnarchiver object in your
archive constructor.
\see BUnarchiver, BUnarchiver::Finish()
\since Haiku R1
*/
@@ -184,6 +204,8 @@
method implementation, and \b NOT your AllArchived() method.
\see BArchiver BArchiver::Finish()
\since Haiku R1
*/
@@ -195,7 +217,7 @@
\ingroup support
\ingroup libbe
\brief A class that simplifies the archiving of complicated BArchivable
hierarchies.
hierarchies.
The BArchiver class is a small class that is used for archiving of
complicated BArchivable hierarchies. Such a hierarchy may include
@@ -208,19 +230,25 @@
present in your original hierarchy.
The objects you archive can be retrieved using a BUnarchiver object.
\since Haiku R1
*/
/*!
\fn BArchiver::BArchiver(BMessage* archive)
\brief Constructs a BArchiver object that manages \c archive.
\since Haiku R1
*/
/*!
\fn BArchiver::~BArchiver()
\brief Destroys a BArchiver object. If the BArchiver object has not had its
Finish() method called, this will be done now.
Finish() method called, this will be done now.
\since Haiku R1
*/
@@ -228,12 +256,12 @@
\fn status_t BArchiver::AddArchivable(const char* name,
BArchivable* archivable, bool deep = true)
\brief Adds a reference to \c archivable to the archive used to
construct this BArchiver. May call \c archivable's Archive() method.
construct this BArchiver. May call \c archivable's Archive() method.
\param name Where this reference will be stored in the archive.
\param archivable The BArchivable* object that to reference.
\param deep Passed to \c archivable->Archive() if \c archivable must
be archived.
be archived.
Adds a reference to \c archivable to your archive. If \c archivable has
not yet been archived, then its Archive() method is called. BArchiver
@@ -241,9 +269,11 @@
method or the GetTokenForArchivable() methods.
\warning If you manually archive an object, and then pass it to
AddArchivable() or GetTokenForArchivable(), it will be archived again,
and when unarchived you will end up with two different BArchivable
objects.
AddArchivable() or GetTokenForArchivable(), it will be archived
again, and when unarchived you will end up with two different
BArchivable objects.
\since Haiku R1
*/
@@ -251,12 +281,12 @@
\fn status_t BArchiver::GetTokenForArchivable(BArchivable* archivable,
bool deep, int32& _token);
\brief Get a token representing a BArchivable object for this archiving
session.
session.
\param archivable The BArchivable object for which you wish to get a
token.
token.
\param deep Controls how \c archivable will be archived, if it has not yet
been archived in this session.
been archived in this session.
\param[out] _token The token representing \c archivable is stored here.
Retrieves or creates a token to represent \c archivable in this archiving
@@ -265,8 +295,10 @@
Archive() method.
\warning If you manually archive an object, and then pass it to
GetTokenForArchivable(), it will be archived again, and when unarchived
you will end up with two different BArchivable objects.
GetTokenForArchivable(), it will be archived again, and when
unarchived you will end up with two different BArchivable objects.
\since Haiku R1
*/
@@ -274,46 +306,58 @@
\fn status_t BArchiver::GetTokenForArchivable(BArchivable* archivable,
int32 &_token)
\brief Equivalent to calling the expanded GetTokenForArchivable(
BArchivable*, bool, int32&), with the deep parameter equal to true.
BArchivable*, bool, int32&), with the deep parameter equal to
\c true.
\see GetTokenForArchivable(BArchivable*, bool, int32&)
\since Haiku R1
*/
/*!
\fn bool BArchiver::IsArchived(BArchivable* archivable);
\brief Returns whether \c archivable has already been archived in this
session.
session.
\return Whether or not the object has already been archived.
\retval true \c archivable has been archived in this archiving session.
\retval false \c archivable has not been archived in this archiving session.
\since Haiku R1
*/
/*!
\fn status_t BArchiver::Finish(status_t err = B_OK);
\brief Report any archiving errors and possibly complete the archiving
session.
\return The first error reported in this archiving session, or B_OK.
session.
This method may finish an archiving session (triggering the call of all
archived objects' AllArchived() methods) if the following conditions
are true:
\li No errors have been reported to this or any other BArchiver object
within this session.
\li This is the last remaining BArchiver that has not had its Finish()
method invoked.
- No errors have been reported to this or any other BArchiver object
within this session.
- This is the last remaining BArchiver that has not had its Finish()
method invoked.
If you call this method with an error code not equal to B_OK, then this
archiving session has failed, archived objects will not have their
AllArchived() methods called, and any subsequent calls to this method
on any BArchiver objects in this session will return your error code.
\return The first error reported in this archiving session, or \c B_OK.
\since Haiku R1
*/
/*!
\fn const BMessage* BArchiver::ArchiveMessage() const
\fn const BMessage* BArchiver::ArchiveMessage() const
\brief Returns the BMessage* used to construct this BArchiver. This is
the archive that AddArchivable() modifies.
the archive that AddArchivable() modifies.
\since Haiku R1
*/
@@ -325,7 +369,7 @@
\ingroup support
\ingroup libbe
\brief A class that simplifies the unarchiving of complicated BArchivable
hierarchies.
hierarchies.
The BUnarchiver class is a small class used to recover BArchivable objects
that have been archived with the BArchiver class. It also provides ownership
@@ -343,9 +387,11 @@
BUnarchiver helper classes, and want to maintain backwards compatibility
with old archive, this can be done using the IsArchiveManaged() method.
\warning Calling methods on your BUnarchiver with a legacy archive (one that
was not managed by a BArchiver during archival) will result in a
call to debugger().
\warning Calling methods on your BUnarchiver with a legacy archive (one
that was not managed by a BArchiver during archival) will result
in a call to debugger().
\since Haiku R1
*/
@@ -354,15 +400,18 @@
\brief Constructs a BUnarchiver object to manage \c archive.
\note To guarantee that your AllUnarchived() method will be called during
archival, you must create a BUnarchiver object in your archive
constructor. It is necessary to do this even if you won't use the
BUnarchiver object in your archive constructor.
archival, you must create a BUnarchiver object in your archive
constructor. It is necessary to do this even if you won't use the
BUnarchiver object in your archive constructor.
\warning Do not construct a BUnarchiver object without first calling
BUnarchiver::PrepareArchive() on \c archive. It is only safe to build a
BUnarchiver without this call in your AllUnarchived() implementation.
BUnarchiver::PrepareArchive() on \c archive. It is only safe to
build a BUnarchiver without this call in your AllUnarchived()
implementation.
\see BUnarchiver::PrepareArchive()
\since Haiku R1
*/
@@ -371,17 +420,21 @@
\brief Destroys a BUnarchiver object.
Calls this objects Finish() method, if it has not yet been called.
\since Haiku R1
*/
/*!
\fn status_t BUnarchiver::EnsureUnarchived(int32 token)
\brief Ensure the object represented by \a token is unarchived and
instantiated.
instantiated.
\param token the object \a token
\returns A status code.
\since Haiku R1
*/
@@ -389,35 +442,41 @@
\fn status_t BUnarchiver::EnsureUnarchived(const char* name,
int32 index = 0)
\brief Ensure the object archived under \a name at \a index is unarchived
and instantiated.
and instantiated.
\param name The archive \a name.
\param index The archive \a index.
\returns A status code.
\since Haiku R1
*/
/*!
\fn bool BUnarchiver::IsInstantiated(int32 token)
\brief Checks whether the object represented by \c token has been
instantiated in this session.
instantiated in this session.
\param token The object \a token.
\returns \c true if instantiated, \c false otherwise
\since Haiku R1
*/
/*!
\fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0)
\brief Checks whether the object archived under \a name at \a index has been
instantiated in this session.
instantiated in this session.
\param name The archive \a name.
\param index The arcive \a token.
\returns \c true if instantiated, \c false otherwise.
\since Haiku R1
*/
@@ -431,18 +490,20 @@
If the retrieved object is not of the type T, then this method will fail.
If this method fails, you will not receive ownership of the object, no
matter what you specified in \c owning.
\tparam T The type of \a object you wish to find.
\param token The \a token you got for this object from
BArchiver::GetTokenForArchivable() during archival.
BArchiver::GetTokenForArchivable() during archival.
\param owning Whether or not you wish to take ownership of the
retrieved object.
retrieved object.
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
\since Haiku R1
*/
@@ -456,12 +517,14 @@
\tparam T The type of \a object you wish to find.
\param token The \a token you got for this object from
BArchiver::GetTokenForArchivable() during archival.
BArchiver::GetTokenForArchivable() during archival.
\param object The return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
\since Haiku R1
*/
@@ -469,7 +532,7 @@
\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
int32 index, ownership_policy owning, T*& object)
\brief Recover an object that had previously been archived using
the BArchiver::AddArchivable() method.
the BArchiver::AddArchivable() method.
If the object has not yet been instantiated, and this request is not
coming from an AllUnarchived() implementation, the object will be
@@ -478,20 +541,22 @@
If the retrieved object is not of the type T, then this method will fail.
If this method fails, you will not receive ownership of the object, no
matter what you specified in \c owning.
\tparam T The type of object you wish to find.
\param name The name that was passed to BArchiver::AddArchivable() when
adding this object.
adding this object.
\param index The index of the object you wish to recover (\c 0-based,
like BMessage::FindData().
like BMessage::FindData().
\param owning Dictates whether or not you wish to take ownership of the
retrieved object.
retrieved object.
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
\since Haiku R1
*/
@@ -499,19 +564,21 @@
\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
int32 index, T*& object)
\brief Recover and take ownership of an object that had previously been
archived using the BArchiver::AddArchivable() method.
archived using the BArchiver::AddArchivable() method.
\tparam T The type of object you wish to find.
\param name The name that was passed to BArchiver::AddArchivable() when
adding this object.
adding this object.
\param index The index of the object you wish to recover (\c 0-based,
like #BMessage::FindData().
like #BMessage::FindData().
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
\since Haiku R1
*/
@@ -519,21 +586,23 @@
\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
ownership_policy owning, T*& object)
\brief Recover an object at index \c 0 that had previously been
archived using the BArchiver::AddArchivable() method.
archived using the BArchiver::AddArchivable() method.
Equivalent to calling FindObject(name, \c 0, owning, object).
\tparam T The type of \a object you wish to find.
\param name The name that was passed to BArchiver::AddArchivable() when
adding this object.
adding this object.
\param owning Dictates whether or not you wish to take ownership of the
retrieved object.
retrieved object.
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
\since Haiku R1
*/
@@ -544,33 +613,35 @@
previously been archived using the BArchiver::AddArchivable() method.
Equivalent to calling FindObject(name, \c 0,
BUnarchiver::B_ASSUME_OWNERSHIP, object).
BUnarchiver::B_ASSUME_OWNERSHIP, object).
\tparam T The type of \a object you wish to find.
\param name The name that was passed to BArchiver::AddArchivable() when
adding this object.
adding this object.
\param object Return parameter for the retrieved \a object of type T.
\returns A status code.
\retval B_OK The \a object retrieved was of type T.
\retval B_BAD_TYPE The \a object retrieved was not of type T.
\since Haiku R1
*/
/*!
\fn status_t BUnarchiver::Finish(status_t err = B_OK);
\brief Report any unarchiving errors and possibly complete the archiving
session.
session.
This method may finish an unarchiving session (triggering the call of all
instantiated objects' AllUnarchived() methods) if the following conditions
are true:
\li No errors have been reported to this or any other BUnarchiver
object within this session.
\li This is the last remaining BUnarchiver that has not had its
Finish() method invoked.
- No errors have been reported to this or any other BUnarchiver
object within this session.
- This is the last remaining BUnarchiver that has not had its
Finish() method invoked.
If you call this method with an error code not equal to B_OK, then this
unarchiving session has failed, instantiated objects will not have their
@@ -581,11 +652,13 @@
the root object).
\return The first error reported in this unarchiving session, or \c B_OK.
\since Haiku R1
*/
/*!
\fn const BMessage* BUnarchiver::ArchiveMessage() const
\fn const BMessage* BUnarchiver::ArchiveMessage() const
\brief Returns the BMessage* used to construct this BUnarchiver.
This is the archive that FindObject() uses.
@@ -623,6 +696,8 @@ MyArchivableClas::MyArchivableClass(BMessage* archive)
\returns Whether \a archive was managed by a BArchiver object.
\retval true if \a archive was managed by a BArchiver object.
\retval false otherwise.
\since Haiku R1
*/
@@ -650,6 +725,8 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
\param archive The archive you wish to have prepared.
\return The same #BMessage as is passed in.
\since Haiku R1
*/
@@ -661,16 +738,20 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
\a archivable.
\param archivable The \a archivable object.
\since Haiku R1
*/
/*!
\fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable)
\brief Relinquish ownership of \a archivable. If \a archivable remains
unclaimed at the end of the unarchiving session, it will be deleted
(unless it is the root object).
unclaimed at the end of the unarchiving session, it will be deleted
(unless it is the root object).
\param archivable The \a archivable object.
\since Haiku R1
*/
@@ -678,7 +759,7 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
\fn template<class T> status_t BUnarchiver::InstantiateObject(
BMessage* from, T*& object)
\brief Attempt to instantiate an object of type T from BMessage*
\a from.
\a from.
If the instantiated object is not of type T, then it will be deleted,
and this method will return \c B_BAD_TYPE. This method is similar to
@@ -691,6 +772,8 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
\since Haiku R1
*/
@@ -708,45 +791,55 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
/*!
\typedef typedef BArchivable* (*instantiation_func)(BMessage*)
\brief Internal definition of a function that can instantiate objects that
have been created with the BArchivable API.
have been created with the BArchivable API.
\since BeOS R3
*/
/*!
\fn BArchivable* instantiate_object(BMessage *from, image_id *id)
\brief Instantiate an archived object with the object being defined in a
different application or library.
different application or library.
This function is similar to instantiate_object(BMessage *from), except that
it takes the \a id argument referring to an image where the object might be
stored.
stored.
\note Images are names for executable files. Image id's refer to these
executable files that have been loaded by your application. Have a look
at the kernel API for further information.
executable files that have been loaded by your application. Have a
look at the kernel API for further information.
\since BeOS R3
*/
/*!
\fn BArchivable* instantiate_object(BMessage *from)
\brief Instantiate an archived object.
This global function will determine the base class, based on the \a from
argument, and it will call the Instantiate() function of that object to
restore it.
restore it.
\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)
\since BeOS R3
*/
/*!
\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.
one stored in the \a from message.
\since BeOS R3
*/
@@ -754,21 +847,27 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
\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.
specific signature. Use instantiate_object() instead.
\since Haiku R1
*/
/*!
\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.
specific class. Use instantiate_object() instead.
\since BeOS R3
*/
/*!
\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.
works on the specified \a archive. Use instantiate_object() instead.
\since BeOS R3
*/
docs/user/support/Autolock.dox
+53 -30
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2007-2013 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/Autolock.h rev 33370
@@ -41,35 +42,38 @@
status_t
Receiver::HandleCall(Call *call)
{
... work on call data ...
fDataLocker->Lock()
... perform changes ...
if (!success)
{
fDataLocker->Unlock();
return B_ERROR;
}
fDataLocker->Unlock()
return B_OK;
... work on call data ...
fDataLocker->Lock()
... perform changes ...
if (!success) {
fDataLocker->Unlock();
return B_ERROR;
}
fDataLocker->Unlock()
return B_OK;
}
\endcode
With the BAutolock this example can be rewritten as follows:
With the BAutolock this example can be rewritten as follows:
\code
status_t
Receiver::HandleCall(Call *call)
{
... work on call data ...
BAutolock autolock(fDataLocker);
... perform changes ...
if (!success)
return B_ERROR;
return B_OK;
... work on call data ...
BAutolock autolock(fDataLocker);
... perform changes ...
if (!success)
return B_ERROR;
return B_OK;
}
\endcode
@@ -77,37 +81,47 @@ Receiver::HandleCall(Call *call)
the function. Because the destruction of the object causes it to unlock
the BLocker or BLooper, you don't have to manually make sure that every
exit from the function is properly unlocked.
\since BeOS R3
*/
/*!
\fn BAutolock::BAutolock(BLooper *looper)
\fn BAutolock::BAutolock(BLooper* looper)
\brief Create an object and lock the BLooper
\since BeOS R3
*/
/*!
\fn BAutolock::BAutolock(BLocker *locker)
\fn BAutolock::BAutolock(BLocker* locker)
\brief Create an object and lock the BLocker
\since BeOS R3
*/
/*!
\fn BAutolock::BAutolock(BLocker &locker)
\fn BAutolock::BAutolock(BLocker& locker)
\brief Create an object and lock the BLocker
\since BeOS R3
*/
/*!
\fn BAutolock::~BAutolock()
\brief Destroy the object and unlock the associated BLocker or BLooper
\since BeOS R3
*/
/*!
\fn bool BAutolock::IsLocked()
\brief Verify whether the associated BLocker or BLooper are actually
locked.
\brief Verify whether the associated BLocker or BLooper are actually
locked.
Basically you may assume that when the object is created, you are
almost always sure the actual locking succeeds. It might fail if the
@@ -116,27 +130,36 @@ Receiver::HandleCall(Call *call)
If you expect this to happen, you can use this method to help you
protect yourself from any harm.
\return Whether or not the BLocker or BLooper is locked.
\retval true The lock was acquired.
\retval false Failed to acquire the lock.
\since BeOS R3
*/
/*!
\fn bool BAutolock::Lock()
\brief Lock the BAutolock if it has not already happened
Note that unlike BLocker, the object is not locked with lock count. That
means that if the lock is already taken, this method returns \c true
without any action.
\return Whether or not the BLocker or BLooper was locked.
\retval true The lock was acquired (or had already been acquired).
\retval false Failed to acquire the lock.
\since Haiku R1
*/
/*!
\fn void BAutolock::Unlock()
\brief Unlock the BAutolock if the lock is being held
\brief Unlock the BAutolock if the lock is being held.
If the lock is not held, the method does nothing.
\since Haiku R1
*/
docs/user/support/Beep.dox
+15 -1
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/Beep.h rev 19972
@@ -21,6 +22,8 @@
\ingroup support
\ingroup libbe
\brief Functions to generate sounds from the computer.
\since BeOS R3
*/
@@ -35,26 +38,37 @@
/*!
\fn status_t beep()
\brief Invoke the standard system beep to alert users.
From Beep.h and in libbe.so.
\see system_beep() and add_system_beep_event()
\since BeOS R3
*/
/*!
\fn status_t system_beep(const char* eventName)
\brief Invokes the sound for event \a eventName.
You can add the events using add_system_beep_event().
From Beep.h and in libbe.so.
\since BeOS R5
*/
/*!
\fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0)
\brief Adds an event to the media server.
Call this method to add a specific event to the media server.
From Beep.h and in libbe.so.
\param eventName The name of the event.
\param flags Currently unused. Pass \c 0.
\since BeOS R5
*/
docs/user/support/BlockCache.dox
+26 -10
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Proofreading:
* David Weizades, [email protected]
@@ -15,7 +16,7 @@
*/
/*!
/*!
\file BlockCache.h
\ingroup support
\ingroup libbe
@@ -26,14 +27,18 @@
/*!
\var B_OBJECT_CACHE
\brief Used in the constructor of BBlockCache. Determines that objects will
be created using \c new[] and \c delete[].
be created using \c new[] and \c delete[].
\since BeOS R3
*/
/*!
\var B_MALLOC_CACHE
\brief Used in the constructor of BBlockCache. Determines that objects will
be created using \c malloc() and \c free().
be created using \c malloc() and \c free().
\since BeOS R3
*/
@@ -77,6 +82,8 @@
Get() will be allocating the objects by itself.
\note BBlockCache is thread-safe.
\since BeOS R3
*/
@@ -86,11 +93,13 @@
\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.
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().
\c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free().
\since BeOS R3
*/
@@ -101,11 +110,13 @@
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.
\since BeOS R3
*/
/*!
\fn void *BBlockCache::Get(size_t blockSize)
\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
@@ -114,13 +125,16 @@
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.
object failed.
\since BeOS R3
*/
/*!
\fn void BBlockCache::Save(void *pointer, size_t blockSize)
\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
@@ -134,4 +148,6 @@
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.
\since BeOS R3
*/
docs/user/support/BufferIO.dox
+73 -36
View File
@@ -1,10 +1,11 @@
/*
* Copyright 2007,Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Stefano Ceccherini, [email protected]
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/BufferIO.h rev 38225
@@ -47,15 +48,18 @@
done with it will also flush the stream and update the original stream.
\note This class is not meant to be used in cases where the
original stream requires to be in a consistent state. Neither should
this class be used as a way to perform 'atomic' writes, because the
object might need to do partial writes if it needs to 'move' the
buffer. This happens for instance if the original stream is bigger
than the buffer.
original stream requires to be in a consistent state. Neither should
this class be used as a way to perform 'atomic' writes, because the
object might need to do partial writes if it needs to 'move' the
buffer. This happens for instance if the original stream is bigger
than the buffer.
\since Haiku R1
*/
/*!
\fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize,
\fn BBufferIO::BBufferIO(BPositionIO* stream, size_t bufferSize,
bool ownsStream)
\brief Initialize a BBufferIO object.
@@ -64,11 +68,14 @@
\param stream A pointer to a BPositionIO object.
\param bufferSize The size of the buffer that the object will allocate and
use.
use.
\param ownsStream Specifies if the object will delete the stream on
destruction.
destruction.
\since Haiku R1
*/
/*!
\fn BBufferIO::~BBufferIO()
\brief Free the resources allocated by the object
@@ -76,11 +83,13 @@
Flush pending changes to the stream and free the allocated memory.
If the \c owns_stream property is \c true, the destructor also
deletes the stream associated with the BBufferIO object.
\since Haiku R1
*/
/*!
\fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size)
/*!
\fn ssize_t BBufferIO::ReadAt(off_t pos, void* buffer, size_t size)
\brief Read the specified amount of bytes at the given position.
\param pos The offset into the stream where to read.
@@ -89,11 +98,14 @@
\return The amount of bytes actually read, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
stream.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
\since Haiku R1
*/
/*!
/*!
\fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write the specified amount of bytes at the given position.
@@ -103,11 +115,14 @@
\return The amount of bytes actually written, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
stream.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
\since Haiku R1
*/
/*!
/*!
\fn off_t BBufferIO::Seek(off_t position, uint32 seekMode)
\brief Set the position in the stream.
@@ -117,22 +132,25 @@
\param position The position where you want to seek.
\param seekMode Can have three values:
- \c SEEK_SET The position passed is an offset from the beginning of
the stream; in other words, the current position is set to
position. For this mode, position should be a positive value.
- \c SEEK_CUR The position argument is an offset from the current
position; the value of the argument is added to the current
position.
- \c SEEK_END. The position argument is an offset from the end of the
stream. In this mode the position argument should be negative
(or zero).
- \c SEEK_SET The position passed is an offset from the beginning
of the stream; in other words, the current position is set to
position. For this mode, position should be a positive value.
- \c SEEK_CUR The position argument is an offset from the current
position; the value of the argument is added to the current
position.
- \c SEEK_END. The position argument is an offset from the end of
the stream. In this mode the position argument should be negative
(or zero).
\return The current position as an offset in bytes from the beginning of
the stream.
the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
stream.
\since Haiku R1
*/
/*!
\fn off_t BBufferIO::Position() const
\brief Return the current position in the stream.
@@ -140,9 +158,12 @@
\return The current position as an offset in bytes
from the beginning of the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
stream.
\since Haiku R1
*/
/*!
\fn status_t BBufferIO::SetSize(off_t size)
\brief Call the SetSize() function of the assigned BPositionIO stream.
@@ -152,23 +173,30 @@
\returns A status code.
\retval B_OK The stream is resized.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
stream.
\since Haiku R1
*/
/*!
\fn status_t BBufferIO::Flush()
\brief Write pending modifications to the stream.
\return The amount of bytes written, or if it failed it will return an error
code.
\return The amount of bytes written, or if it failed it will return an
error code.
\since Haiku R1
*/
/*!
\fn BPositionIO *BBufferIO::Stream() const
/*!
\fn BPositionIO* BBufferIO::Stream() const
\brief Return a pointer to the stream specified on construction.
\return A pointer to the BPositionIO stream specified on construction.
\since Haiku R1
*/
@@ -177,18 +205,23 @@
\brief Return the size of the internal buffer.
\return The size of the buffer allocated by the object.
\since Haiku R1
*/
/*!
\fn bool BBufferIO::OwnsStream() const
\brief Tell if the BBufferIO object "owns" the specified stream.
\brief Return whether or not the BBufferIO object "owns" the stream.
\return Whether or not the BBufferIO object "owns" the stream.
\retval true The object "owns" the stream and will destroy it upon
destruction.
destruction.
\retval false The object does not own the stream.
\see SetOwnsStream()
\since Haiku R1
*/
@@ -197,11 +230,15 @@
\brief Set the \c owns_stream property of the object.
\param owns_stream If you pass \c true, the object will delete the stream
upon destruction, if you pass \c false it will not.
upon destruction, if you pass \c false it will not.
\since Haiku R1
*/
/*!
\fn void BBufferIO::PrintToStream() const
\brief Print the object to stdout.
\brief Print the object to standard output.
\since Haiku R1
*/
docs/user/support/DataIO.dox
+158 -56
View File
@@ -5,10 +5,11 @@
* Authors:
* Stefano Ceccherini, [email protected]
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/DataIO.h rev 38226
* src/kits/support/DataIO.cpp rev 42177
* headers/os/support/DataIO.h hrev47418
* src/kits/support/DataIO.cpp hrev47418
*/
@@ -16,13 +17,14 @@
\file DataIO.h
\ingroup support
\ingroup libbe
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO
and BMemoryIO classes.
Pure virtual BDataIO and BPositioIO classes provide
the protocol for Read()/Write()/Seek().
Pure virtual BDataIO and BPositioIO classes provide the protocol for
Read(), Write(), and Seek().
BMallocIO and BMemoryIO classes implement the protocol,
as does BFile in the Storage Kit.
BMallocIO and BMemoryIO classes implement the protocol, as does BFile in
the Storage Kit.
*/
@@ -34,7 +36,7 @@
\ingroup support
\ingroup libbe
\brief Abstract interface for objects that provide read and write access to
data.
data.
The interface provided by this class applies to objects or data that are
limited to reading and writing data. Classes derived from this class should
@@ -46,23 +48,29 @@
Objects and data that support more advanced operations like seeking or
reading at writing at defined positions should derive their classes from
BPositionIO, which inherits this class.
\since BeOS R3
*/
/*!
\fn BDataIO::BDataIO()
\brief This constructor does nothing.
\since BeOS R3
*/
/*!
\fn BDataIO::~BDataIO()
\brief This destructor does nothing.
\since BeOS R3
*/
/*!
\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size)
\fn virtual ssize_t BDataIO::Read(void* buffer, size_t size)
\brief Reads data from the object into a buffer.
Your implementation should copy data into \c buffer, with the maximum size
@@ -71,26 +79,31 @@
The default implementation is a no-op returning \c B_NOT_SUPPORTED.
\return You should return the amount of bytes actually read, or an error
code in case of failure.
code in case of failure.
\since BeOS R3
*/
/*!
\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size)
\fn virtual ssize_t BDataIO::Write(const void* buffer, size_t size)
\brief Writes data from a buffer to the object.
Your implementation should copy data from \c buffer, with the maximum size
of \c size.
of \c size.
The default implementation is a no-op returning \c B_NOT_SUPPORTED.
\return You should return the amount of bytes actually written, or an error
code in case of failure.
\return You should return the amount of bytes actually written, or an error
code in case of failure.
\since BeOS R3
*/
/*!
\fn virtual status_t BDataIO::ReadExactly(void* buffer, size_t size, size_t* _bytesRead)
\fn virtual status_t BDataIO::ReadExactly(void* buffer, size_t size,
size_t* _bytesRead)
\brief Reads an exact amount of data from the object into a buffer.
This is a convenience wrapper method for Read() for code that expects the
@@ -99,21 +112,25 @@
read any more data (i.e. returns 0).
\param buffer Pointer to pre-allocated storage of at least \a size bytes
into which the data shall be read. Won't be dereferenced, when \a size
is 0.
into which the data shall be read. Won't be dereferenced, when
\a size is 0.
\param size The number of bytes to be read.
\param _bytesRead Optional pointer to a pre-allocated size_t into which the
number of bytes actually read will be written. When the method returns
\c B_OK this will always be \a size. Can be \c NULL.
\return An error code indicated whether the method succeeded.
number of bytes actually read will be written. When the method
returns \c B_OK this will always be \a size. Can be \c NULL.
\return An error code indicating whether or not the method succeeded.
\retval B_OK All data have been read.
\retval B_PARTIAL_READ Read() didn't fail, but couldn't provide as many
bytes as requested.
bytes as requested.
\since Haiku R1
*/
/*!
\fn virtual status_t BDataIO::WriteExactly(const void* buffer, size_t size, size_t* _bytesWritten)
\fn virtual status_t BDataIO::WriteExactly(const void* buffer, size_t size,
size_t* _bytesWritten)
\brief Writes an exact amount of data from a buffer to the object.
This is a convenience wrapper method for Write() for code that expects the
@@ -122,15 +139,18 @@
write any more data (i.e. returns 0).
\param buffer Pointer to a buffer of at least \a size bytes containing the
data to be written. Won't be dereferenced, when \a size is 0.
data to be written. Won't be dereferenced, when \a size is 0.
\param size The number of bytes to be written.
\param _bytesWritten Optional pointer to a pre-allocated size_t into which
the number of bytes actually written will be written. When the method
returns \c B_OK this will always be \a size. Can be \c NULL.
the number of bytes actually written will be written. When the
method returns \c B_OK this will always be \a size. Can be \c NULL.
\return An error code indicated whether the method succeeded.
\retval B_OK All data have been written.
\retval B_PARTIAL_READ Write() didn't fail, but couldn't write as many
bytes as provided.
bytes as provided.
\since Haiku R1
*/
@@ -142,7 +162,7 @@
\ingroup support
\ingroup libbe
\brief Abstract interface that provides advanced read, write and seek access
to data.
to data.
The interface of this object applies to objects or data that allows
position-aware reading and writing of data. Classes that derive from this
@@ -158,29 +178,37 @@
default implementation is to read or write the data at the current
position indicated by Position(). Re-implement the methods if you require
a different behavior.
\since Haiku R1
*/
/*!
\fn BPositionIO::BPositionIO()
\brief This constructor does nothing.
\since Haiku R1
*/
/*!
\fn virtual BPositionIO::~BPositionIO()
\brief This destructor does nothing.
\since Haiku R1
*/
/*!
\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
\fn virtual ssize_t BPositionIO::Read(void* buffer, size_t size)
\brief Read data from current position.
This method is derived from BDataIO. The default implementation reads data
from the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Read() for what is
expected of this method.
\since BeOS R3
*/
@@ -192,28 +220,36 @@
to the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Write() for what is
expected of this method.
\since BeOS R3
*/
/*!
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void* buffer,
size_t size) = 0
\brief Pure virtual to read data from a certain position.
Your implementation should copy data from the position indicated by
\a position into the \a buffer with the maximum size of \a size.
\return The amount of bytes actually read, or an error code.
\since BeOS R3
*/
/*!
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer,
size_t size) = 0
\brief Pure virtual to write data to a certain position.
Your implementation should copy data from \a buffer to the position indicated
by \a buffer with the maximum size of \a size.
\return The amount of bytes actually written, or an error code.
\since BeOS R3
*/
@@ -226,11 +262,15 @@
\param position An integer that defines a position.
\param seekMode You will get one of the following values:
- \c SEEK_SET Set the cursor to the position indicated by \c position.
- \c SEEK_END Set the cursor to the end of the buffer, and go
\c position beyond that.
- \c SEEK_CUR Set the cursor the the current position plus \c position.
- \c SEEK_SET Set the cursor to the position indicated by
\c position.
- \c SEEK_END Set the cursor to the end of the buffer, and go
\c position beyond that.
- \c SEEK_CUR Set the cursor the the current position plus
\c position.
\return The new position.
\since BeOS R3
*/
@@ -239,6 +279,8 @@
\brief Pure virtual to return the current position of the cursor.
\return Your implementation should return the current position of the cursor.
\since BeOS R3
*/
@@ -250,7 +292,9 @@
the size to be changed, reimplement this method.
\return Return \c B_OK if everything succeeded, else return the appropriate
error code.
error code.
\since BeOS R3
*/
@@ -266,8 +310,13 @@
your class.
\param[out] size The size of the object is put into this parameter.
\return This method returns \c B_OK on success or an error code on error.
\see SetSize()
\see Seek()
\since BeOS R3
*/
@@ -291,6 +340,8 @@
This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
Position() interface from BPositionIO.
\since BeOS R3
*/
@@ -300,8 +351,11 @@
\param data A pointer to the buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(const void *buffer, size_t length) for a read-only
implementation.
implementation.
\since BeOS R3
*/
@@ -311,13 +365,18 @@
\param buffer A pointer to the \c const (read-only) buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
\since BeOS R3
*/
/*!
\fn BMemoryIO::~BMemoryIO()
\brief The destructor does nothing.
\since BeOS R3
*/
@@ -328,9 +387,12 @@
\param[in] pos The offset where to start reading data.
\param[out] buffer The buffer to copy the read bytes into.
\param[in] size The size of the \a buffer.
\return The amount of read bytes or an error code.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
construction is invalid.
construction is invalid.
\since BeOS R3
*/
@@ -341,10 +403,13 @@
\param pos The offset to write to.
\param buffer The buffer to copy the bytes from.
\param size The number of bytes to write.
\return The amount of bytes written or an error code.
\retval B_NOT_ALLOWED The object is constructed as a read-only object.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
construction is invalid.
construction is invalid.
\since BeOS R3
*/
@@ -353,20 +418,27 @@
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seek_mode The mode determines where the cursor is placed.
Possibilities:
- \c SEEK_SET The cursor is set to \a position.
- \c SEEK_CUR The \a position is added to the current position of the
cursor.
- \c SEEK_END The cursor is put at the end of the data, plus
\a position added to it.
\param seek_mode The mode determines where the cursor is placed.
Possibilities include:
- \c SEEK_SET The cursor is set to \a position.
- \c SEEK_CUR The \a position is added to the current position of
the cursor.
- \c SEEK_END The cursor is put at the end of the data, plus
\a position added to it.
\return The new position.
\since BeOS R3
*/
/*!
\fn off_t BMemoryIO::Position() const
\brief Return the current position.
\return The current position as an off_t.
\since BeOS R3
*/
@@ -387,6 +459,8 @@
\retval B_OK The buffer is resized.
\retval B_NOT_ALLOWED The buffer is read-only.
\retval B_ERROR The \c size is larger than the size of the buffer.
\since BeOS R3
*/
@@ -415,19 +489,26 @@
If you require a BPositionIO derived object that works on buffers you
provide, have a look at BMemoryIO.
\since BeOS R3
*/
/*!
\fn BMallocIO::BMallocIO()
\brief Create a new memory buffer with block size 256.
\see SetBlockSize()
\since BeOS R3
*/
/*!
\fn BMallocIO::~BMallocIO()
\brief Destroy the object and free the internal buffer.
\since BeOS R3
*/
@@ -438,8 +519,11 @@
\param[in] pos Offset into the data where to read from.
\param[out] buffer The buffer to copy the read bytes in.
\param [in] size Size of the buffer.
\return The number of read bytes, or \c B_BAD_VALUE if
the provided \a buffer is invalid.
the provided \a buffer is invalid.
\since BeOS R3
*/
@@ -450,8 +534,11 @@
\param pos Offset into the data where to write to.
\param buffer The buffer to copy from.
\param size The size of the buffer.
\return The number of bytes written or \c B_BAD_VALUE if the provided.
\a buffer is invalid.
\a buffer is invalid.
\since BeOS R3
*/
@@ -461,18 +548,23 @@
\param position The position to move the cursor to.
\param seekMode The mode determines where the cursor is placed. Possibilities:
- \c SEEK_SET The cursor is set to \a position.
- \c SEEK_CUR The \c position is added to the current position of the
cursor.
- \c SEEK_END The cursor is put at the end of the data, plus
\a position added to it.
\return The new position.
- \c SEEK_SET The cursor is set to \a position.
- \c SEEK_CUR The \c position is added to the current position of the
cursor.
- \c SEEK_END The cursor is put at the end of the data, plus
\a position added to it.
\return The new position as an off_t.
\since BeOS R3
*/
/*!
\fn off_t BMallocIO::Position() const
\brief Return the position of the cursor.
\since BeOS R3
*/
@@ -484,8 +576,12 @@
than the current size, the data will be cleared.
\param size The new size of the buffer.
\return A status code.
\retval B_OK Resizing the data succeeded.
\retval B_NO_MEMORY Failed to allocate the necessary memory.
\since BeOS R3
*/
@@ -493,21 +589,25 @@
\fn void BMallocIO::SetBlockSize(size_t blockSize)
\brief Change the block size to a certain value.
This class allocates memory in blocks. If you are in performance-critical
This class allocates memory in blocks. If you are in performance-critical
code you might want to tweak this setting to create a better performance in
case you know you are going to allocate more than the default blocksize of
case you know you are going to allocate more than the default block size of
256.
\param blockSize The new block size.
\since BeOS R3
*/
/*!
\fn const void *BMallocIO::Buffer() const
\fn const void* BMallocIO::Buffer() const
\brief Return a pointer to the internal buffer.
As with any pointer to internal buffers the Haiku API exposes,
make sure you don't change anything since it doesn't belong to you.
\since BeOS R3
*/
@@ -518,4 +618,6 @@
This number doesn't have to be the same size as the buffer is. Because memory
is allocated in blocks the actual size of the buffer may be greater, but this
method only returns the number of bytes that are actually used.
\since BeOS R3
*/
docs/user/support/Flattenable.dox
+64 -40
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk <[email protected]>
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/Flattenable.h rev 39675
@@ -24,21 +25,21 @@
\ingroup support
\ingroup libbe
\brief Interface for classes that can flatten and unflatten themselves to
a stream of bytes.
a stream of bytes.
It is convenient that objects can be stored as a flat stream of bytes. In
this way, they can be written to disk, exchanged between applications or send
over networks. This ability, which is known in many other programming
languages as marshalling, is not native in C++. The Haiku API has created a
universal interface that classes have if they are able to be flattened. This
over networks. This ability, known as marshaling in many other programming
languages, is not native to C++. The Haiku API has created a universal
interface that classes have if they are able to be flattened. This
class defines the interface. This class does nothing on its own, and
therefore contains pure virtuals. By inheriting this class and inmplementing
the methods in your own class, you will be able to use your objects as
flattenable objects throughout the Haiku API.
therefore contains pure virtual functions. By inheriting this class and
implementing the methods in your own class, you will be able to use your
objects as flattenable objects throughout the Haiku API.
Flattened objects can be used for example when sending messages within an
application or between applications. The BMessage class uses the interface
to store and transmit custom classes.
to store and transmit custom classes.
If you want to be able to flatten your objects, you will need to implement
various methods. Flatten() and Unflatten() are where the magic happen. These
@@ -56,33 +57,37 @@
\code
type_code CUSTOM_STRING_TYPE = 'CUST';
class CustomString : public BFlattenable
{
class CustomString : public BFlattenable {
public:
char data[100];
char data[100];
// From BFlattenable
bool IsFixedSize() const { return false; };
type_code TypeCode() const { return CUSTOM_STRING_TYPE; };
ssize_t FlattenedSize() const { return strlen(data); };
// from BFlattenable
bool IsFixedSize() const { return false; };
type_code TypeCode() const { return CUSTOM_STRING_TYPE; };
ssize_t FlattenedSize() const { return strlen(data); };
status_t Flatten(void* buffer, ssize_t size) const
{
if ((strlen(data) + 1) < size)
return B_BAD_VALUE;
memcpy(buffer, data, size);
return B_OK;
};
status_t Flatten(void* buffer, ssize_t size) const
{
if ((strlen(data) + 1) < size)
return B_BAD_VALUE;
status_t Unflatten(type_code code, const void* buffer, ssize_t size)
{
if (code != CUSTOM_STRING_TYPE)
return B_BAD_TYPE;
if (size > 100)
return B_NO_MEMORY;
memcpy(data, buffer, size);
return B_OK;
};
memcpy(buffer, data, size);
return B_OK;
};
status_t Unflatten(type_code code, const void* buffer, ssize_t size)
{
if (code != CUSTOM_STRING_TYPE)
return B_BAD_TYPE;
if (size > 100)
return B_NO_MEMORY;
memcpy(data, buffer, size);
return B_OK;
};
};
\endcode
@@ -102,13 +107,20 @@ public:
to disk. Another example is BPath. Because of that you can store paths and
send them over via messages. Throughout the Haiku API you will find classes
that provide the flattening interface.
\since BeOS R3
*/
/*!
\fn virtual bool BFlattenable::IsFixedSize() const
\brief Pure virtual that should return whether or not flattened objects of
this type always have a fixed size.
\brief Pure virtual that should return whether or not flattened objects of
this type always have a fixed size.
\return Should return whether or not the flattened objects of this type
always have a fixed size.
\since BeOS R3
*/
@@ -117,22 +129,26 @@ public:
\brief Pure virtual that returns the type_code this class flattens to.
\return Either one of the existing typecodes found in TypeConstants.h
if your class actually is compatible to those formats, or a
custom four-byte integer constant if not.
if your class actually is compatible to those formats, or a
custom four-byte integer constant if not.
\since BeOS R3
*/
/*!
\fn virtual ssize_t BFlattenable::FlattenedSize() const
\brief Pure virtual that should return the size of the flattened object in
bytes.
bytes.
\since BeOS R3
*/
/*!
\fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const
\brief Pure virtual that should flatten the object into the supplied
\a buffer.
\a buffer.
Please make sure that you check that the supplied buffer is not a \c NULL
pointer. Also make sure that the size of the flattened object does isn't
@@ -144,6 +160,8 @@ public:
\retval B_OK The object was flattened.
\retval B_NO_MEMORY The buffer was smaller than required.
\retval B_BAD_VALUE The buffer was a \c NULL pointer.
\since BeOS R3
*/
@@ -159,6 +177,8 @@ public:
\returns Whether or not the supplied type_code is supported.
\retval true The type_code is supported.
\retval false The type_code is not supported.
\since BeOS R3
*/
@@ -166,7 +186,7 @@ public:
\fn virtual status_t BFlattenable::Unflatten(type_code code,
const void* buffer, ssize_t size)
\brief Pure virtual that should unflatten the buffer and put the contents
into the current object.
into the current object.
Make sure that the supplied buffer is not \c NULL and that you actually
support the typecode.
@@ -179,10 +199,14 @@ public:
\retval B_OK The object is unflattened.
\retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid.
\retval B_BAD_TYPE You don't support data with this \a code.
\since BeOS R3
*/
/*!
\fn virtual BFlattenable::~BFlattenable()
\brief Destructor. Does nothing.
\since Haiku R1
*/
docs/user/support/List.dox
+269 -94
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Proofreading:
* David Weizades, [email protected]
@@ -11,8 +12,8 @@
* John Drinkwater, [email protected]
*
* Corresponds to:
* headers/os/support/List.h rev 34520
* src/kits/support/List.cpp rev 34520
* headers/os/support/List.h hrev47418
* src/kits/support/List.cpp hrev47418
*/
@@ -29,7 +30,7 @@
\ingroup support
\ingroup libbe
\brief An ordered container that is designed to hold generic \c void*
objects.
objects.
This class is designed to be used for a variety of tasks. Unlike similar
implementations in other libraries, this class is not based on templates
@@ -54,8 +55,14 @@
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.
\see BObjectList for a templated version of BList that adds type safety,
optional object ownership, search, and insert operations.
\since BeOS R3
*/
/*!
\fn BList::BList(int32 count = 20)
\brief Create a new list with a number of empty slots.
@@ -76,104 +83,186 @@
values.
\param count The size of the blocks allocated in memory.
\since BeOS R3
*/
/*!
\fn BList::BList(const BList& anotherList)
\fn BList::BList(const BList& other)
\brief Copy constructor. Copy a complete list into this one.
\param other The list to copy from.
\since BeOS R3
*/
/*!
\fn BList::~BList()
\brief Destroy the list.
Please note that as BList does not assume ownership of the objects,
only the list will be freed, not the objects that are held in it.
\since BeOS R3
*/
/*!
\fn BList& BList::operator=(const BList &list)
\brief Copy another list into this object.
\name Operators
*/
//! @{
/*!
\fn BList& BList::operator=(const BList &other)
\brief Copy another list into this object.
\since BeOS R3
*/
/*!
\fn bool BList::operator==(const BList& other) const
\brief Returns whether or not the BList and \a other are equal.
Equal means that they are the same object or their contents are the same.
\return \c true if the lists are equal, \c false if they are NOT equal.
\since Haiku R1
*/
/*!
\fn bool BList::operator!=(const BList& other) const
\brief Returns whether or not the BList and \a other are NOT equal.
\return \c true if the lists are NOT equal, \c false if they are equal.
\since Haiku R1
*/
//! @}
/*!
\name Adding and Removing Items
*/
//! @{
/*!
\fn bool BList::AddItem(void *item, int32 index)
\brief Add an item at a certain position.
\param item The item to add.
\param index The place in the list.
/*!
\fn bool BList::AddItem(void* item, int32 index)
\brief Add \a item at the specified \a index.
\param item The \a item to add.
\param index The place in the list to add the \a item.
\return Whether or not the item was added.
\retval true The item was added.
\retval false Item was not added. Either the index is negative or invalid,
or resizing the list failed.
\see AddItem(void *item)
or resizing the list failed.
\see AddItem(void*)
\since BeOS R3
*/
/*!
\fn bool BList::AddItem(void *item)
\brief Append an item to the list.
\param item The item to add.
\retval true The item was appended.
\retval false Item was not appended, since resizing the list failed.
\see AddItem(void *item, int32 index)
/*!
\fn bool BList::AddItem(void* item)
\brief Append the \a item to the end of the list.
\param item The item to append.
\return Whether or not the \a item was appended.
\retval true The \a item was appended.
\retval false \a item was not appended, since resizing the BList failed.
\see AddItem(void*, int32)
\since BeOS R3
*/
/*!
\fn bool BList::AddList(const BList *list, int32 index)
\brief Add items from another list to this list at a certain position.
\fn bool BList::AddList(const BList* list, int32 index)
\brief Add a \a list of items to this list at the specified \a index.
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.
\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)
\param list The \a list to be added.
\param index The position in the current \a list where the new item(s)
are added.
\return Whether or not the \a list was added.
\retval true The \a list was added.
\retval false Failed to insert the \a list resizing failed.
\see AddList(const BList*)
\since BeOS R3
*/
/*!
\fn bool BList::AddList(const BList *list)
\brief Append a list to this list.
\fn bool BList::AddList(const BList* list)
\brief Append a \a list of items to this list.
Note that the \a list parameter is a \c const, so the original list will not
be altered.
\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.
\see AddList(const BList *list, int32 index)
\param list The \a list to be added.
\return Whether or not the \a list was added.
\retval true The \a list was appended.
\retval false Failed to append the list, resizing failed.
\see AddList(const BList*, int32)
\since BeOS R3
*/
/*!
\fn bool BList::RemoveItem(void *item)
\brief Remove an item from the list.
\param item The item that should be removed.
\retval true The item was found and removed.
\retval false The item was not in this list and thus not removed.
\see RemoveItem(int32 index)
/*!
\fn bool BList::RemoveItem(void* item)
\brief Remove \a item from the list.
\param item The \a item to be removed.
\return Whether or not the \a item was removed.
\retval true The \a item was found and removed.
\retval false The \a item was not in this list and thus not removed.
\see RemoveItem(int32)
\since BeOS R3
*/
/*!
\fn void * BList::RemoveItem(int32 index)
\fn void* BList::RemoveItem(int32 index)
\brief Remove the item at \a index from the list.
\param index The item that should be removed.
\return The pointer to the item that was removed, or \c NULL in case the
index was invalid.
\see RemoveItem(void *item)
\param index The \a index of the item to be removed.
\return The pointer to the item that was removed, or \c NULL if the
\a index was invalid.
\see RemoveItem(void*)
\since BeOS R3
*/
/*!
\fn bool BList::RemoveItems(int32 index, int32 count)
\brief Remove a number of items starting at a certain position.
@@ -183,122 +272,171 @@
\param index The offset in the list where removal should start.
\param count The number of items to remove.
\return Whether or not the items were removed.
\retval true Removal succeeded.
\retval false Failed to remove the items because the index was invalid.
\since BeOS R3
*/
/*!
\fn bool BList::ReplaceItem(int32 index, void *newItem)
\fn bool BList::ReplaceItem(int32 index, void* item)
\brief Replace an item with another one.
\param index The offset in the list where to put the item.
\param newItem The new item to put in the list.
\retval true Item replaced.
\retval false The index was invalid.
\param index The offset in the list where to put the \a item.
\param item The new \a item to put in the list.
\return Whether or not the item was replaced.
\retval true The item was replaced.
\retval false The \a index was invalid.
\since Haiku R1
*/
/*!
\fn void BList::MakeEmpty()
\brief Clear all the items from the list.
Please note that this does not free the items.
\note This does not free the items.
\since BeOS R3
*/
//! @}
/*!
\name Reordering Items
*/
//! @{
/*!
\fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
\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.
For an example, see the Compare(const BString *, const BString *) function.
\since BeOS R3
*/
/*!
\fn bool BList::SwapItems(int32 indexA, int32 indexB)
\brief Swap two items.
\brief Swap the items at \a indexA and \a indexB.
\param indexA The first item.
\param indexB The second item.
\return Whether or not the items were swapped.
\retval true Swap succeeded.
\retval false Swap failed because one of the indexes was invalid.
\since Haiku R1
*/
/*!
\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
\brief Move an item to a new place
\brief Move the item at \a fromIndex to the position of \a toIndex.
This moves a list item from position A to position B, moving the appropriate
block of list elements to make up for the move. For example, in the array:
\verbatim
\verbatim
A B C D E F G H I J
\endverbatim
\endverbatim
Moving 1(B)->6(G) would result in this:
\verbatim
\verbatim
A C D E F G B H I J
\endverbatim
\endverbatim
\param fromIndex The original location.
\param toIndex The new location.
\return Whether or not the items were moved.
\retval true Move succeeded.
\retval false Move failed due to the indexes being invalid.
\since Haiku R1
*/
//! @}
/*!
\name Retrieving Items
*/
//! @{
/*!
\fn void *BList::ItemAt(int32 index) const
\brief Get an item.
\fn void* BList::ItemAt(int32 index) const
\brief Return a pointer to the item at the given \a index.
\param index The item to retrieve.
\return A pointer to the item in that position, or \c NULL if the index is
out of bounds.
\return A pointer to the item in that position, or \c NULL if the
\a index is out of bounds.
\see ItemAtFast(int32 index) const
\since BeOS R3
*/
/*!
\fn void *BList::FirstItem() const
\brief Get the first item.
\fn void* BList::FirstItem() const
\brief Return a pointer to the first item in the list.
\return A pointer to the first item or \c NULL if the list is empty.
\see LastItem() const
\since BeOS R3
*/
/*!
\fn void *BList::ItemAtFast(int32 index) const
\brief Get an item.
\fn void* BList::ItemAtFast(int32 index) const
\brief Return a pointer to the item at \a index.
This method does not perform any boundary checks when it retrieves an item.
Use this method in a performance critical area of your program where you are
sure you will not get an invalid item.
\return A pointer to the item.
\since Haiku R1
*/
/*!
\fn void *BList::LastItem() const
\brief Get the last item.
\fn void* BList::LastItem() const
\brief Return a pointer to the last item in the list.
\return A pointer to the last item or \c NULL if the list is empty.
\see FirstItem() const
\since BeOS R3
*/
/*!
\fn void *BList::Items() 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
@@ -309,51 +447,80 @@ A C D E F G B H I J
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.
\return The internal list of pointers.
\sa DoForEach() for an alternate method.
\since BeOS R3
*/
//! @}
/*!
\name Querying for Items
\name Querying 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.
\fn bool BList::HasItem(void* item) const
\brief Return whether or not \a item is in the list.
\return \c true if the \a item was in the list, \c false otherwise.
\since BeOS R3
*/
/*!
\fn int32 BList::IndexOf(void* item) const
\brief Return the index of \a item.
\return The index of the item, or -1 when the item is not in the list.
\since BeOS R3
*/
/*!
\fn int32 BList::CountItems() const
\brief Get the number of items in the list.
\brief Returns the number of items in the list.
\return The number of items in the list as an int32.
\since BeOS R3
*/
/*!
\fn bool BList::IsEmpty() const
\brief Check if there are items in the list.
\brief Return whether or not there are items in the list.
\return \c true if the list was empty, \c false otherwise.
\since BeOS R3
*/
//! @}
/*!
\name Iterating over the List
\name Iterating Over Items
*/
//! @{
/*!
\fn void BList::DoForEach(bool (*func)(void* item))
\brief Perform an action on every item in the list.
@@ -361,23 +528,31 @@ 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.
\see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
\param func A pointer to a function that takes a \c void* argument and
returns a bool.
\see DoForEach(bool (*func)(void*, void*), void*)
\since BeOS R3
*/
/*!
\fn void BList::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.
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 with the first \c void* argument being the item
and the second \c void* being the argument that you supply. It should
return a boolean value on whether it succeeded or not.
and the second \c void* being the argument that you supply. It
should return a boolean value on whether it succeeded or not.
\param arg2 An argument to supply to \a func.
\see DoForEach(bool (*func)(void* item))
\see DoForEach(bool (*func)(void*))
\since BeOS R3
*/
//! @}
docs/user/support/Locker.dox
+86 -48
View File
@@ -1,15 +1,17 @@
/*
* Copyright 2007-2013 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/Locker.h rev 36218
* src/kits/support/Locker.cpp rev 32758
*/
/*!
\file Locker.h
\ingroup support
@@ -25,7 +27,7 @@
\brief Semaphore-type class for thread safety.
The BLocker interface is not merely a wrapper around a semaphore, but it
also has two advantages. First of all, it implements a benaphore.
also has two advantages. First of all, it implements a benaphore.
A benaphore is in some ways more speed efficient,
because before it uses the internal semaphore, it first checks against a
variable that is only operated on with atomic operations. Setting a variable
@@ -38,7 +40,7 @@
semaphore. You can imagine that in many cases where you protect
of data that \em might be accessed by two or more concurrent threads, but
the chances of it happening being very small, the benaphore benefits the
most from it's speed.
most from it's speed.
The other feature of BLocker that improves basic semaphore handling is that
it allows for recursive locks. The following piece of code works with a
@@ -53,9 +55,8 @@ Flower::Grow(int length)
fLength += length;
fLock->Unlock();
return B_OK;
} else {
} else
return B_ERROR;
}
}
status_t
@@ -65,9 +66,8 @@ Flower::Water(int amount)
status_t status = Grow(amount * 2);
fLock->Unlock();
return status;
} else {
} else
return B_ERROR;
}
}
\endcode
@@ -75,71 +75,81 @@ Flower::Water(int amount)
requests from the same thread. A normal semaphore would block in \c Grow()
because the semaphore would be acquired already. Please do make sure you
pair every Lock() with an Unlock() though, or you'll create a deadlock.
\sa BAutolock
\since BeOS R3
*/
/*!
\fn BLocker::BLocker()
\brief Constructor.
\brief Create a new BLocker with the default name "some BLocker" and
benaphore-style locking.
Create a new BLocker with the default name of some BLocker. This
BLocker will use the benaphore-style locking.
This BLocker will use the benaphore-style locking.
\note For debugging purposes, it's extremely convenient to actually give a
name to the object. In case of a deadlock, it's easier to track down which
BLocker object might have caused the problems.
name to the object. In case of a deadlock, it's easier to track down
which BLocker object might have caused the problems.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
\see BLocker(const char*, bool) for all the options.
\since BeOS R3
*/
/*!
\fn BLocker::BLocker(const char* name)
\brief Constructor.
Create a new BLocker with benaphore-style locking.
\brief Creates a new BLocker with the given \a name and benaphore-style
locking.
\param name A NULL-terminated string that contains the name of the
semaphore. Note that the length of the names are limited to
\c B_OS_NAME_LENGTH constant, which includes the \c \\0
character.
semaphore. Note that the length of the names are limited to
\c B_OS_NAME_LENGTH constant, which includes the \c \\0
character.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
\since BeOS R3
*/
/*!
\fn BLocker::BLocker(bool benaphoreStyle)
\brief Constructor.
Creates a BLocker with the default name of <tt>some BLocker</tt>.
\brief Creates a BLocker with the default name "some BLocker" and the given
locking style.
\note For debugging purposes, it's extremely convenient to actually give a
name to the object. In case of a deadlock, it's easier to track down
which BLocker object might have caused the problems.
name to the object. In case of a deadlock, it's easier to track down
which BLocker object might have caused the problems.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If you
pass \c false, the object will completely rely on semaphores for
it's functioning.
style (which is the default option for other constructors). If you
pass \c false, the object will completely rely on semaphores for
it's functioning.
\see BLocker(const char* name, bool benaphoreStyle) if you also want
to set a name.
to set a name.
\since BeOS R4
*/
/*!
\fn BLocker::BLocker(const char* name, bool benaphoreStyle)
\brief Constructor.
\brief Creates a new BLocker with the given \a name and locking style.
\param name A NULL-terminated string that contains the name of the
semaphore. Note that the length of the names are limited to
\c B_OS_NAME_LENGTH constant, which includes the \c \\0
character.
semaphore. Note that the length of the names are limited to
\c B_OS_NAME_LENGTH constant, which includes the \c \\0
character.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If
you pass \c false, the object will completely rely on semaphores
for its functioning.
style (which is the default option for other constructors). If
you pass \c false, the object will completely rely on semaphores
for its functioning.
\since BeOS R4
*/
@@ -150,16 +160,20 @@ Flower::Water(int amount)
Release the internal semaphore. Because of this, any pending Lock() calls
from other threads be cancelled. The return code will be \c false for
those calls.
\since BeOS R3
*/
/*!
\fn status_t BLocker::InitCheck() const
\brief Check whether the locker has properly initialized
\retval B_OK The semaphore has been properly initialized
\retval (negative) Any other error value that is related to semaphore
initialization
\return A status code, \c B_OK if the semaphore has been properly
initialized or any other error (negative) value related
to semaphore initialization.
\since Haiku R1
*/
@@ -169,10 +183,12 @@ Flower::Water(int amount)
\retval true Lock acquired successfully.
\retval false Failed to acquire the lock. Most probable cause is that the
object is deleted. This frees the semaphore and releases the
pending Lock() requests.
object is deleted. This frees the semaphore and releases the
pending Lock() requests.
\see LockWithTimeout(bigtime_t timeout), Unlock()
\since BeOS R3
*/
@@ -181,22 +197,28 @@ Flower::Water(int amount)
\brief Add a lock request and block until we get it or until it times out.
\param timeout This is a timeout in microseconds (one millionth of a
second) relative to now.
second) relative to now.
\see Lock(), Unlock()
\since BeOS R3
*/
/*!
\fn void BLocker::Unlock(void)
\brief Release the lock that's currently held.
\since BeOS R3
*/
/*!
\fn thread_id BLocker::LockingThread(void) const
\brief Return the \c thread_id of the thread that's currently holding the
lock.
lock.
\since BeOS R3
*/
@@ -204,21 +226,32 @@ Flower::Water(int amount)
\fn bool BLocker::IsLocked(void) const
\brief Check if the calling thread is actually holding the lock.
\return Whether or not the calling thread is holding the lock.
\retval true The thread from which this method is called from is currently
holding the lock.
holding the lock.
\retval false The object is unlocked or the lock is held by another thread.
\since BeOS R3
*/
/*!
\fn int32 BLocker::CountLocks(void) const
\brief Return the number of recursive locks that are currently held.
\return the number of currently held recursive locks as an int32.
\since BeOS R3
*/
/*!
\fn nt32 BLocker::CountLockRequests(void) const
\fn int32 BLocker::CountLockRequests(void) const
\brief Return the number of threads with a pending lock request.
\return The number of threads with a pending lock request as an int32.
\since BeOS R3
*/
@@ -227,7 +260,12 @@ Flower::Water(int amount)
\brief Return the sem_id of the semaphore this object holds.
\warning Like any other internal objects that the Haiku API might expose,
this semaphore id should in general be left alone. You should not use any
of the public low-level semaphore functions on this semaphore, because it
will harm the internal consistency of the object.
this semaphore id should in general be left alone. You should not
use any of the public low-level semaphore functions on this
semaphore, because it will harm the internal consistency of the
object.
\return The sem_id of the semaphore this object holds.
\since BeOS R3
*/
docs/user/support/ObjectList.dox
+509
View File
@@ -0,0 +1,509 @@
/*
* Copyright 2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/ObjectList.h hrev40252
*/
/*!
\file ObjectList.h
\ingroup support
\ingroup libbe
\brief Defines the BObjectList class.
*/
/*!
\class BObjectList
\ingroup support
\ingroup libbe
\brief BObjectList is a wrapper around BList that adds type safety,
optional object ownership, search, and insert operations.
\since Haiku R1
*/
/*!
\fn template<class T> BObjectList<T>::BObjectList(int32 itemsPerBlock,
bool owning)
\brief Creates a new BObjectList.
\param itemsPerBlock The number of items per block to allocate.
\param owning Whether or not the BObjectList deletes its items when
it is emptied or deleted.
\since Haiku R1
*/
/*!
\fn template<class T> BObjectList<T>::BObjectList(
const BObjectList<T>& list)
\brief Creates a new BObjectList as a copy of another \a list.
\param list The \a list to copy from.
\since Haiku R1
*/
/*!
\fn template<class T> BObjectList<T>::~BObjectList()
\brief Deletes the list.
If the list owns its items they are deleted too.
\since Haiku R1
*/
/*!
\name Operators
*/
//! @{
/*!
\fn template<class T> BObjectList<T>& BObjectList<T>::operator=(
const BObjectList<T>& list)
\brief Creates a new BObjectList as a copy of another \a list by
overloading the = operator.
\param list The \a list to copy from.
\since Haiku R1
*/
//! @}
/*!
\name Adding and Removing Items
*/
//! @{
/*!
\fn template<class T> bool BObjectList<T>::AddItem(T* item)
\brief Append the \a item to the end of the list.
\param item The \a item to append.
\return Whether or not the \a item was appended.
\retval true The \a item was appended.
\retval false \a item was not appended, since resizing the BObjectList
failed.
\since Haiku R1
*/
/*!
\fn template<class T> bool BObjectList<T>::AddItem(T* item, int32 index)
\brief Add \a item at the specified \a index.
\param item The \a item to add.
\param index The place in the list to add the \a item.
\return Whether or not the item was added.
\retval true The item was added.
\retval false Item was not added. Either the index is negative or invalid,
or resizing the BObjectList failed.
\since Haiku R1
*/
/*!
\fn template<class T> bool BObjectList<T>::AddList(BObjectList<T>* list)
\brief Append a \a list of items to this list.
The original list is not altered.
\param list The \a list to be added.
\return Whether or not the \a list was added.
\retval true The \a list was added.
\retval false Failed to append the list, resizing failed.
\since Haiku R1
*/
/*!
\fn template<class T> bool BObjectList<T>::AddList(BObjectList<T>* list,
int32 index)
\brief Add a \a list of items to this list at the specified \a index.
The original list is not altered.
\param list The \a list to be added.
\param index The position in the current \a list where the new item(s) are
added.
\return Whether or not the \a list was added.
\retval true The \a list was added.
\retval false Failed to insert the \a list resizing failed.
\since Haiku R1
*/
/*!
\fn template<class T> bool BObjectList<T>::RemoveItem(T* item,
bool deleteIfOwning)
\brief Remove \a item from the list.
\param item The \a item to be removed.
\param deleteIfOwning Also delete the \a item if owned.
\return Whether or not the \a item was removed.
\retval true The \a item was found and removed.
\retval false The \a item was not in this list and thus not removed.
\since Haiku R1
*/
/*!
\fn template<class T> T* BObjectList<T>::RemoveItemAt(int32 index)
\brief Remove the item at \a index from the list.
\param index The \a index of the item to be removed.
\return The pointer to the item that was removed, or \c NULL if the
\a index was invalid.
\since Haiku R1
*/
/*!
\fn template<class T> inline T* BObjectList<T>::ItemAt(int32 index) const
\brief Return a pointer to the item at the given \a index.
\param index The item to retrieve.
\return A pointer to the item in that position, or \c NULL if the
\a index is out of bounds.
\since Haiku R1
*/
/*!
\fn template<class T> bool BObjectList<T>::ReplaceItem(int32 index, T* item)
\brief Replace an item with another one.
\param index The offset in the list where to put the \a item.
\param item The new \a item to put in the list.
\return Whether or not the item was replaced.
\retval true The item was replaced.
\retval false The \a index was invalid.
\since Haiku R1
*/
/*!
\fn template<class T> void BObjectList<T>::MakeEmpty(bool deleteIfOwning)
\brief Clear all the items from the list.
\param deleteIfOwning Also deletes items if owned.
\since Haiku R1
*/
//! @}
/*!
\name Reordering Items
*/
//! @{
/*!
\fn template<class T> T* BObjectList<T>::SwapWithItem(int32 index, T* item)
\brief Swap the \a item with the item at \a index.
\param index The offset in the list where to put the \a item.
\param item The new \a item to put in the list.
\return A pointer to the item in that position, or \c NULL if the
\a index is out of bounds.
\since Haiku R1
*/
/*!
\fn template<class T> bool BObjectList<T>::MoveItem(int32 from, int32 to)
\brief Move the item at \a from to the position of \a to.
\param from The index to move the item \a from.
\param to The index to move the item \a to.
\return Whether or not the items were moved.
\retval true The items were moved.
\retval false The \a from or \a to index was invalid.
\see BList::MoveItem()
\since Haiku R1
*/
//! @}
/*!
\name Querying Items
*/
//! @{
/*!
\fn template<class T> int32 BObjectList<T>::IndexOf(const T* item) const
\brief Return the index of \a item.
\return The index of the item, or -1 when the item is not in the list.
\since Haiku R1
*/
/*!
\fn template<class T> T* BObjectList<T>::FirstItem() const
\brief Return a pointer to the first item in the list.
\return A pointer to the first item or \c NULL if the list is empty.
\see BObjectList<T>::LastItem() const
\since Haiku R1
*/
/*!
\fn template<class T> T* BObjectList<T>::LastItem() const
\brief Return a pointer to the last item in the list.
\return A pointer to the last item or \c NULL if the list is empty.
\see BObjectList<T>::FirstItem() const
\since Haiku R1
*/
/*!
\fn template<class T> bool BObjectList<T>::HasItem(const T* item) const
\brief Return whether or not \a item is in the list.
\return \c true if the \a item was in the list, \c false otherwise.
\since Haiku R1
*/
/*!
\fn template<class T> bool BObjectList<T>::IsEmpty() const
\brief Return whether or not there are items in the list.
\return \c true if the list was empty, \c false otherwise.
\since Haiku R1
*/
/*!
\fn template<class T> int32 BObjectList<T>::CountItems() const
\brief Returns the number of items in the list.
\return The number of items in the list as an int32.
\since Haiku R1
*/
//! @}
/*!
\name Iterating Over Items
*/
//! @{
/*!
\fn template<class T> T* BObjectList<T>::EachElement(EachFunction func,
void* params)
\brief Perform an action on each item in the list.
\param func A function that takes a \c void* argument and returns a
boolean.
\param params parameters for \a func.
\return A pointer to the item.
\since Haiku R1
*/
/*!
\fn template<class T> const T* BObjectList<T>::EachElement(
ConstEachFunction func, void* params) const
\brief Perform an action on each item in the list.
\param func A function that takes a \c void* argument and returns a
boolean.
\param params parameters for \a func.
\return A pointer to the item.
\since Haiku R1
*/
//! @}
/*!
\name Finding Items
*/
//! @{
/*!
\fn template<class T> const T* BObjectList<T>::FindIf(
const UnaryPredicate<T>& predicate) const
\brief Find items that match \a predicate.
\return A const pointer to T.
\since Haiku R1
*/
/*!
\fn template<class T> T* BObjectList<T>::FindIf(
const UnaryPredicate<T>& predicate)
\brief Find items that match \a predicate.
\return A pointer to T.
\since Haiku R1
*/
/*!
\fn template<class T> T* BObjectList<T>::BinarySearch(const T& key,
CompareFunction func) const
\brief Search for \a key in the list of items using the supplied comparison
function via a binary search algorithm.
\param key The \a key to search for.
\param func The comparison function to use.
\return A pointer to T.
\since Haiku R1
*/
/*!
\fn template<class T> T* BObjectList<T>::BinarySearch(const T& key,
CompareFunctionWithState func, void* state) const
\brief Search for \a key in the list of items using the supplied comparison
function via a binary search algorithm.
\param key The \a key to search for.
\param func The comparison function to use.
\param state Additional information used to search for the item.
\return A pointer to T.
\since Haiku R1
*/
//! @}
/*!
\name Reordering Items
*/
//! @{
/*!
\fn template<class T> void BObjectList<T>::SortItems(
CompareFunction function)
\brief Sort the items with the use of a supplied comparison \a function.
\param function The \a function used to sort the items.
\since Haiku R1
*/
/*!
\fn template<class T> void BObjectList<T>::SortItems(
CompareFunctionWithState function, void* state)
\brief Sort the items with the use of a supplied comparison \a function and
addtional \a state.
\param function The \a function used to sort the items.
\param state Additional information used to sort the items.
\since Haiku R1
*/
/*!
\fn template<class T> void BObjectList<T>::HSortItems(
CompareFunction function)
\brief Sort the items with the use of a supplied comparison \a function.
\param function The \a function used to sort the items.
\since Haiku R1
*/
/*
\fn template<class T> void BObjectList<T>::HSortItems(
CompareFunctionWithState function, void* state)
\param function The \a function used to sort the items.
\param state Additional information used to sort the items.
\since Haiku R1
*/
//! @}
docs/user/support/StopWatch.dox
+20 -2
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation written by:
@@ -37,11 +37,13 @@
Reset() to reset the timer back to 0 clearing all lap info. When the
object is destroyed the timing information is streamed to standard out
unless you set the \a silent parameter to \c true in the constructor.
\since BeOS R3
*/
/*!
\fn BStopWatch::BStopWatch(const char *name, bool silent)
\fn BStopWatch::BStopWatch(const char* name, bool silent)
\brief Constructs a BStopWatch object and starts the timer.
This method creates a new BStopWatch object. As soon as the object is
@@ -55,6 +57,8 @@
anonymous stop watch.
\param silent Pass \c true to suppress time information from streaming to
standard output when the object is destroyed.
\since BeOS R3
*/
@@ -64,6 +68,8 @@
If \a silent was set to \c false in the constructor then this method
will print elapsed time information to standard output.
\since BeOS R3
*/
@@ -72,6 +78,8 @@
\brief Resume the timer from a suspended state.
\see Suspend()
\since BeOS R3
*/
@@ -80,6 +88,8 @@
\brief Suspend the timer.
\see Resume()
\since BeOS R3
*/
@@ -97,6 +107,8 @@
the time that has passed since the last lap). Any call to Lap()
beyond the 10th lap will overwrite the last value. Calling Lap()
while the timer is suspended does nothing and returns 0.
\since BeOS R3
*/
@@ -105,6 +117,8 @@
\brief Gets the elapsed time the object has counted.
\return The elapsed time in microseconds.
\since BeOS R3
*/
@@ -114,6 +128,8 @@
Resets the stop watch clearing the start time and stored laps and
restarts the timer.
\since BeOS R3
*/
@@ -125,4 +141,6 @@
string.
\return the name of the stop watch set in the constructor.
\since BeOS R3
*/
docs/user/support/String.dox
+965 -551
View File
File diff suppressed because it is too large Load Diff
docs/user/support/SupportDefs.dox
+87 -37
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/SupportDefs.h rev 35018
@@ -202,13 +203,17 @@
/*!
\typedef typedef int32 status_t
\brief Represents one of the status codes defined in Error.h
\brief Represents one of the status codes defined in Error.h.
\since BeOS R3
*/
/*!
\typedef typedef int64 bigtime_t
\brief Represents time. The unit depends on the context of the function.
\since BeOS R3
*/
@@ -221,7 +226,9 @@
/*!
\typedef typedef uint32 type_code
\brief Represents a certain type of data. See TypeConstants.h for
possible values.
possible values.
\since Haiku R1
*/
@@ -230,11 +237,13 @@
\brief Defined to support 'hidden' commands or extensions to classes.
The Haiku API has none of these.
\since Haiku R1
*/
//! @}
/*!
\name Format strings for printf() and scanf()
@@ -547,7 +556,7 @@
*/
/*!
/*!
\def B_PRIdDEV
\brief dev_t
*/
@@ -571,7 +580,7 @@
*/
/*!
/*!
\def B_PRIdTIME
\brief time_t
*/
@@ -588,10 +597,12 @@
//////////////// Odds and ends
/*!
\var const char *B_EMPTY_STRING
\var const char* B_EMPTY_STRING
\brief Defines an empty string. Currently defined as the string "".
\since BeOS R3
*/
@@ -599,8 +610,10 @@
\def min_c(a,b)
\brief Returns the minimum of the values a and b.
\note When including this header in a C file, use the C equivalent called
\c min(a,b).
\note When including this header in a C file, use the C equivalent called
\c min(a,b).
\since Haiku R1
*/
@@ -608,14 +621,18 @@
\def max_c(a,b)
\brief Returns the maximum of values a and b.
\note When including this header in a C file, use the C equivalent called
\c max(a,b).
\note When including this header in a C file, use the C equivalent called
\c max(a,b).
\since Haiku R1
*/
/*!
\def NULL
\brief Defines the constant \c NULL if it hasn't already been defined.
\since BeOS R3
*/
@@ -627,7 +644,8 @@
//! @{
/*! \fn void atomic_set(int32* value, int32 newValue)
/*!
\fn void atomic_set(int32* value, int32 newValue)
\brief Atomically set the variable \a value to \a newvalue.
This is a thread-safe way of performing the \c *value \c = \c newValue
@@ -641,17 +659,19 @@
\sa atomic_and()
\sa atomic_or(),
\sa atomic_get()
\since Haiku R1
*/
/*! \fn int32 atomic_get_and_set(int32* value, int32 newValue)
\brief Atomically set the variable \a value to \a newvalue and return the
old value.
old value.
This is a thread-safe way of performing the \c *value \c = \c newValue
operation. You should use these function when two or more threads might
access the variable simultaneously. You don't have to use a semaphore or a
mutex in this case.
mutex in this case.
\return The original value of \c value.
@@ -662,18 +682,20 @@
\sa atomic_and()
\sa atomic_or(),
\sa atomic_get()
\since Haiku R1
*/
/*! \fn int32 atomic_test_and_set(int32* value, int32 newValue,
int32 testAgainst)
\brief Atomically set the variable \a value to \a newValue if the current
value is \a testAgainst.
This is a thread-safe way of conditionally performing the \c *value \c +=
value is \a testAgainst.
This is a thread-safe way of conditionally performing the \c *value \c +=
\c newValue operation. You should use these function when two or more
threads might access the variable simultaneously. You don't have to use
a semaphore or a mutex in this case.
a semaphore or a mutex in this case.
\return The original value of \c value.
@@ -684,6 +706,8 @@
\sa atomic_and()
\sa atomic_or()
\sa atomic_get()
\since Haiku R1
*/
@@ -694,7 +718,7 @@
This is a thread-safe way of performing the \c *value \c += \c addValue
operation. You should use these function when two or more threads might
access the variable simultaneously. You don't have to use a semaphore or a
mutex in this case.
mutex in this case.
\return The original value of \c value.
@@ -705,17 +729,19 @@
\sa atomic_and()
\sa atomic_or()
\sa atomic_get()
\since BeOS R3
*/
/*! \fn int32 atomic_and(int32* value, int32 andValue)
\brief Atomically perform a bitwise AND operation of \a andValue to the
\brief Atomically perform a bitwise AND operation of \a andValue to the
variable \a andValue.
This is a thread-safe way of performing the \c *value \c &amp;= \c andValue
operation. You should use these function when two or more threads might
access the variable simultaneously. You don't have to use a semaphore or a
mutex in this case.
mutex in this case.
\return The original value of \c value.
@@ -726,19 +752,20 @@
\sa atomic_add()
\sa atomic_or()
\sa atomic_get()
*/
\since BeOS R3
*/
/*!
\fn int32 atomic_or(int32* value, int32 orValue)
\brief Atomically perform a bitwise OR operation of \a orValue to the
variable \a andValue.
\brief Atomically perform a bitwise OR operation of \a orValue to the
variable \a andValue.
This is a thread-safe way of performing the \c *value \c |= \c orValue
operation. You should use these function when two or more threads might
access the variable simultaneously. You don't have to use a semaphore or a
mutex in this case.
mutex in this case.
\return The original value of \c value.
@@ -749,6 +776,8 @@
\sa atomic_add()
\sa atomic_and()
\sa atomic_get()
\since BeOS R3
*/
@@ -770,6 +799,8 @@
\sa atomic_add()
\sa atomic_and()
\sa atomic_or()
\since Haiku R1
*/
@@ -789,18 +820,20 @@
\sa atomic_and64()
\sa atomic_or64()
\sa atomic_get64()
\since Haiku R1
*/
/*!
\fn int64 atomic_get_and_set64(int64* value, int64 newValue)
\brief Atomically set the variable \a value to \a newvalue and return
the old value.
the old value.
This is a thread-safe way of performing the \c *value \c = \c newValue
operation. You should use these function when two or more threads might
access the variable simultaneously. You don't have to use a semaphore or a
mutex in this case.
mutex in this case.
\return The original value of \c value.
@@ -811,6 +844,8 @@
\sa atomic_and64()
\sa atomic_or64()
\sa atomic_get64()
\since Haiku R1
*/
@@ -818,12 +853,12 @@
\fn int64 atomic_test_and_set64(int64* value, int64 newValue,
int64 testAgainst)
\brief Atomically set the variable \a value to \a newValue if the current
value is \a testAgainst.
value is \a testAgainst.
This is a thread-safe way of conditionally performing the \c *value
\c += \c newValue operation. You should use these function when two
or more threads might access the variable simultaneously. You don't
have to use a semaphore or a mutex in this case.
have to use a semaphore or a mutex in this case.
\return The original value of \c value.
@@ -834,6 +869,8 @@
\sa atomic_and64()
\sa atomic_or64()
\sa atomic_get64()
\since Haiku R1
*/
@@ -844,8 +881,8 @@
This is a thread-safe way of performing the \c *value \c += \c addValue
operation. You should use these function when two or more threads might
access the variable simultaneously. You don't have to use a semaphore or a
mutex in this case.
mutex in this case.
\return The original value of \c value.
\sa atomic_add() for a version that works on an \c int32.
@@ -855,13 +892,15 @@
\sa atomic_and64()
\sa atomic_or64()
\sa atomic_get64()
\since Haiku R1
*/
/*!
\fn int64 atomic_and64(int64* value, int64 andValue)
\brief Atomically perform a bitwise AND operation of \a andValue to the
variable \a andValue.
variable \a andValue.
This is a thread-safe way of performing the \c *value \c &amp;= \c andValue
operation. You should use these function when two or more threads might
@@ -877,17 +916,20 @@
\sa atomic_add64()
\sa atomic_or64()
\sa atomic_get64()
\since Haiku R1
*/
/*! \fn int64 atomic_or64(int64* value, int64 orValue)
/*!
\fn int64 atomic_or64(int64* value, int64 orValue)
\brief Atomically perform a bitwise OR operation of \a orValue to the
variable \a andValue.
variable \a andValue.
This is a thread-safe way of performing the \c *value \c |= \c orValue
operation. You should use these function when two or more threads might
access the variable simultaneously. You don't have to use a semaphore or a
mutex in this case.
mutex in this case.
\return The original value of \c value.
@@ -898,6 +940,8 @@
\sa atomic_add64()
\sa atomic_and64()
\sa atomic_get64()
\since Haiku R1
*/
@@ -919,6 +963,8 @@
\sa atomic_add64()
\sa atomic_and64()
\sa atomic_or64()
\since Haiku R1
*/
@@ -943,12 +989,16 @@
/*!
\def FALSE
\brief Obsolete. Use \c false.
\since BeOS R3
*/
/*!
\def TRUE
\brief Obsolete. Use \c true.
\since BeOS R3
*/
docs/user/support/TLS.dox
+28 -13
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2007 Haiku Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/TLS.h rev 19972
@@ -64,18 +65,22 @@ public:
\note
-# It is impossible to get data other than from your thread.
-# There is a limit to the number of TLS variables you can allocate. This
limit is define by #TLS_MAX_KEYS, but do realize that you share this
limit with all the libraries your application is linked to.
limit is define by #TLS_MAX_KEYS, but do realize that you share this
limit with all the libraries your application is linked to.
-# The actual global variables, in the example \c gThreadName and
\c gThreadData, are only indexes. You cannot use these variables to
access data without the TLS API.
\c gThreadData, are only indexes. You cannot use these variables to
access data without the TLS API.
\since BeOS R5
*/
/*!
\def TLS_MAX_KEYS
\brief The maximum number of thread local storage variables. This number is
process wide.
process wide.
\since BeOS R5
*/
@@ -87,42 +92,50 @@ public:
you can reuse in every thread.
\return A unique index to which you can associate per thread data. If we
overrun the maximum number of keys, as defined by #TLS_MAX_KEYS,
the function will return \c B_NO_MEMORY.
overrun the maximum number of keys, as defined by #TLS_MAX_KEYS,
the function will return \c B_NO_MEMORY.
\sa tls_get()
\sa tls_set()
\sa tls_address()
\since BeOS R5
*/
/*!
\fn void *tls_get(int32 index)
\fn void* tls_get(int32 index)
\brief Retrieve the data stored for this thread at the provided \a index.
\param index The \a index that you retrieved with tls_allocate().
\return The data you set using tls_set() for this thread, or \c NULL if there
is no data set, or the \a index is invalid.
is no data set, or the \a index is invalid.
\sa tls_allocate()
\sa tls_set()
\since BeOS R5
*/
/*!
\fn void **tls_address(int32 index)
\fn void** tls_address(int32 index)
\brief Retrieve the pointer that refers to the data of this thread at the
provided \a index.
You can use this pointer to directly manipulate your thread data.
\param index The \a index that you retrieved with tls_allocate().
\return The pointer to where your thread's data is, or \c NULL if the index
is invalid.
is invalid.
\sa tls_allocate()
\sa tls_set()
\sa tls_get()
\since BeOS R5
*/
@@ -135,8 +148,10 @@ public:
\param index The \a index that you retrieved with tls_allocate().
\param value The data that should be associated with the index for this
thread.
thread.
\sa tls_allocate()
\sa tls_get()
\since BeOS R5
*/
docs/user/support/TypeConstants.dox
+66 -3
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/TypeConstants.h rev 43506
@@ -14,10 +15,10 @@
\file TypeConstants.h
\ingroup support
\ingroup libbe
\brief Represents typecodes that are used in various part of the Haiku API.
\brief Represents type codes that are used in various part of the Haiku API.
The type codes all refer to a specified type, except one. B_ANY_TYPE can
refer to literaly any type. This type could be used in case you send or receive
refer to literally any type. This type could be used in case you send or receive
data of which you don't know the type, but you want to send or receive it
anyway.
*/
@@ -26,6 +27,8 @@
/*!
\var B_ANY_TYPE
\brief General type when the exact contents is not yet known.
\since Haiku R1
*/
@@ -34,6 +37,8 @@
\brief Reference to a BAtomic class that was going to be in BeOS R6.
Unused in Haiku.
\since Haiku R1
*/
@@ -42,102 +47,136 @@
\brief Reference to a BAtomic class that was going to be in BeOS R6.
Unused in Haiku.
\since Haiku R1
*/
/*!
\var B_BOOL_TYPE
\brief Boolean value.
\since Haiku R1
*/
/*!
\var B_CHAR_TYPE
\brief Represents the \c char type.
\since Haiku R1
*/
/*!
\var B_COLOR_8_BIT_TYPE
\brief Represents a one-byte color.
\since Haiku R1
*/
/*!
\var B_DOUBLE_TYPE
\brief Represents the \c double type.
\since Haiku R1
*/
/*!
\var B_FLOAT_TYPE
\brief Represents the \c float type.
\since Haiku R1
*/
/*!
\var B_GRAYSCALE_8_BIT_TYPE
\brief Represents a byte-long grayscale value.
\since Haiku R1
*/
/*!
\var B_INT16_TYPE
\brief Represents a \c short type.
\since Haiku R1
*/
/*!
\var B_INT32_TYPE
\brief Represents a \c long type.
\since Haiku R1
*/
/*!
\var B_INT64_TYPE
\brief Represents a \c long \c long type.
\since Haiku R1
*/
/*!
\var B_INT8_TYPE
\brief Represents a \c char type used for integer storage.
\since Haiku R1
*/
/*!
\var B_LARGE_ICON_TYPE
\brief Represents a large icon.
\since Haiku R1
*/
/*!
\var B_MEDIA_PARAMETER_GROUP_TYPE
\brief Represents the BParameterGroup type from the media kit.
\since Haiku R1
*/
/*!
\var B_MEDIA_PARAMETER_TYPE
\brief Represents the BParameter type from the media kit.
\since Haiku R1
*/
/*!
\var B_MEDIA_PARAMETER_WEB_TYPE
\brief Represents the BParameterWeb type from the media kit.
\since Haiku R1
*/
/*!
\var B_MESSAGE_TYPE
\brief Represents a BMessage type.
\since Haiku R1
*/
/*!
\var B_MESSENGER_TYPE
\brief Represents a BMessenger type.
\since Haiku R1
*/
@@ -155,72 +194,96 @@
/*!
\var B_URL_HTTP
\brief application/x-vnd.Be.URL.http
\since Haiku R1
*/
/*!
\var B_URL_HTTPS
\brief application/x-vnd.Be.URL.https
\since Haiku R1
*/
/*!
\var B_URL_FTP
\brief application/x-vnd.Be.URL.ftp
\since Haiku R1
*/
/*!
\var B_URL_GOPHER
\brief application/x-vnd.Be.URL.gopher
\since Haiku R1
*/
/*!
\var B_URL_MAILTO
\brief application/x-vnd.Be.URL.mailto
\since Haiku R1
*/
/*!
\var B_URL_NEWS
\brief application/x-vnd.Be.URL.news
\since Haiku R1
*/
/*!
\var B_URL_NNTP
\brief application/x-vnd.Be.URL.nntp
\since Haiku R1
*/
/*!
\var B_URL_TELNET
\brief application/x-vnd.Be.URL.telnet
\since Haiku R1
*/
/*!
\var B_URL_RLOGIN
\brief application/x-vnd.Be.URL.rlogin
\since Haiku R1
*/
/*!
\var B_URL_TN3270
\brief application/x-vnd.Be.URL.tn3270
\since Haiku R1
*/
/*!
\var B_URL_WAIS
\brief application/x-vnd.Be.URL.wais
\since Haiku R1
*/
/*!
\var B_URL_FILE
\brief application/x-vnd.Be.URL.file
\since Haiku R1
*/
docs/user/support/parsedate.dox
+52 -51
View File
@@ -1,12 +1,13 @@
/*
* Copyright 2007 Haiku, Inc. All rights reserved.
* Copyright 2007-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler
* Axel Dörfler
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/support/parsedate.h rev 19972
* headers/os/support/parsedate.h rev 19972
*/
@@ -36,20 +37,20 @@
Here are some examples of input strings that parsedate() will be able
to convert along with some notes:
- "last friday", "this wednesday", "next July"
"last", "next", and "this" refer to the week or year (depending
on the context). So "last friday" means last week's friday.
"This wednesday" is referring to this week's wednesday, no matter
if it has already passed or not.
"Next July" refers to next year's July. All of these dates are
parsed relative to the specified time (usually "now"), and will
be set to the first moment of that time span: "next monday" is
monday, 0:00:00, midnight.
"last", "next", and "this" refer to the week or year (depending
on the context). So "last friday" means last week's friday.
"This wednesday" is referring to this week's wednesday, no matter
if it has already passed or not.
"Next July" refers to next year's July. All of these dates are
parsed relative to the specified time (usually "now"), and will
be set to the first moment of that time span: "next monday" is
monday, 0:00:00, midnight.
- "now" just returns the time all calculations are relative to.
- "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing,
that is, current time plus exactly 5 minutes.
that is, current time plus exactly 5 minutes.
- "5 weeks" means in 5 weeks from now on.
- "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August
5th, 2003, again at 0:00 midnight.
5th, 2003, again at 0:00 midnight.
- "Thursday 3:00" means this week's thursday, at 3 o'clock.
\anchor parsedateFormats
@@ -84,8 +85,8 @@
not a valid meridian specifier), or "4:66" (minutes out of range).
\note At the time of this writing, the parsedate() functions are not
localized and will only recognize English time specifications
following the examples above.
localized and will only recognize English time specifications
following the examples above.
*/
@@ -129,15 +130,15 @@
\fn time_t parsedate(const char *dateString, time_t relativeTo)
\brief Parses \a dateString relative to \a relativeTo
Parses the given \a dateString relative to the time
specified by \a relativeTo using the internal formats
table.
Parses the given \a dateString relative to the time specified by
\a relativeTo using the internal formats table.
\param dateString the date that should be parsed, i.e. "next thursday".
\param relativeTo all relative dates will be relative to this time, if -1
is passed, the current time will be used.
\return the parsed time value or -1 if the \a dateString
could not be parsed.
is passed, the current time will be used.
\return The parsed time value or -1 if the \a dateString could not be
parsed.
*/
@@ -145,55 +146,55 @@
\fn time_t parsedate_etc(const char *dateString, time_t relativeTo,
int *_storedFlags)
\brief Parses <span class="var">dateString</span> relative to
<span class="var">relativeTo</span>
<span class="var">relativeTo</span>
This does basically the same as parsedate(), but will set the following
flags in <span class="var">_storedFlags</span>:
\htmlonly
<table border=1>
<!-- ToDo: this certainly is a hack -->
<tr><th bgcolor="#eeeeee">Constant</th><th bgcolor="#eeeeee">Meaning</th></tr>
<tr><td class="mdname1">PARSEDATE_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_DAY_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_MINUTE_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_INVALID_DATE</td>
<td>
\endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly
This flag will only be set if the function returns -1.
</td></tr>
</table>
\endhtmlonly
\htmlonly
<table border=1>
<!-- ToDo: this certainly is a hack -->
<tr><th bgcolor="#eeeeee">Constant</th><th bgcolor="#eeeeee">Meaning</th></tr>
<tr><td class="mdname1">PARSEDATE_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_DAY_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_MINUTE_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_INVALID_DATE</td>
<td>
\endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly
This flag will only be set if the function returns -1.
</td></tr>
</table>
\endhtmlonly
*/
/*!
\fn void set_dateformats(const char *formatTable[])
\fn void set_dateformats(const char* formatTable[])
\brief sets the internal format table for parsedate()
This function let you set the format table which is used by parsedate().
When <span class="var">formatTable</span> is NULL, the standard built-in format table will be set again.
\param formatTable the NULL terminated formats list. This list must stay
valid when using parsedate() - it is not copied, but directly used.
When <span class="var">formatTable</span> is NULL, the standard built-in
format table will be set again.
\see
\ref parsedateFormats Format!
\param formatTable the NULL terminated formats list. This list must stay
valid when using parsedate() - it is not copied, but directly used.
\see \ref parsedateFormats Format!
*/
/*!
\fn const char **get_dateformats(void)
\fn const char** get_dateformats(void)
\brief returns the internal format table currently used by parsedate()
Returns the internal format table currently used by parsedate() - this is
either a pointer to the built-in one, or one that you have previously
set using set_dateformats().
\see
\ref set_dateformats()
\see \ref set_dateformats()
*/