diff --git a/docs/user/apidoc.dox b/docs/user/apidoc.dox index b2ecaa4b1d..eac7dfe639 100644 --- a/docs/user/apidoc.dox +++ b/docs/user/apidoc.dox @@ -40,7 +40,7 @@ \subsection formalrequirements_location Location of the Documentation Source - Doxygen, the tool that we use to generate the marked up documentation with, + Doxygen, the tool that we use to generate the marked up documentation, has an ingenious parser that is able to scan through both header and source files and that makes it possible to document the API directly in the headers or the source. However, the Haiku project decided not to put the @@ -75,8 +75,8 @@ \subsection formalrequirements_headerblock The Header Block Every documentation file will begin with the header block. It's basically a - copyright block, with a reference to the author and with the revision against - which the documentaton was written. + copyright block, with a reference to the author(s) and with the revision + against which the documentaton was written. \verbatim // diff --git a/docs/user/compatibility.dox b/docs/user/compatibility.dox index 84c48723c7..836a3dd90b 100644 --- a/docs/user/compatibility.dox +++ b/docs/user/compatibility.dox @@ -33,7 +33,7 @@ some specific examples: member, you might notice that it has been renamed to \link BString::fPrivateData fPrivateData \endlink. However, it's use is deprecated, and it might even be made private in the future. -- The undocumented functions defined in the headers are not implemented. +- The undocumented functions defined in Alias.h from the storage kit are not implemented. - The private Device Map API (used by OpenTracker) has been replaced by a different API (Disk Device API). - The application debugging interface is conceptually similar, but nevertheless diff --git a/docs/user/support/BufferIO.dox b/docs/user/support/BufferIO.dox index bdf858862f..e1d8411108 100644 --- a/docs/user/support/BufferIO.dox +++ b/docs/user/support/BufferIO.dox @@ -1,40 +1,40 @@ /*! -\file BufferIO.h -\brief Provides the BBufferIO class. + \file BufferIO.h + \brief Provides the BBufferIO class. */ /*! -\class BBufferIO -\ingroup support -\ingroup libbe -\brief A buffered adapter for BPositionIO objects. -\author Stefano Ceccherini \ + \class BBufferIO + \ingroup support + \ingroup libbe + \brief A buffered adapter for BPositionIO objects. + \author Stefano Ceccherini \ -This class differs from other classes derived from BPositionIO in a sense that -it does not actually provide an actual entity to be read or written to, but -rather acts like a "frontend" to a stream. This class especially comes in -handy when working with files that are constantly written and rewritten and -where you want do this writing buffered so that the hard disk or the network -will not have to be accessed so frequently. + This class differs from other classes derived from BPositionIO in a sense that + it does not actually provide an actual entity to be read or written to, but + rather acts like a "frontend" to a stream. This class especially comes in + handy when working with files that are constantly written and rewritten and + where you want do this writing buffered so that the hard disk or the network + will not have to be accessed so frequently. -This class works as follows. After constructing a BBufferIO object that you -want to be buffered, you can create this object. The constructor takes a -\c stream parameter that points to the object to be buffered. You then use -this object as a proxy to the resource you want to read of or write to. As -soon as you use ReadAt(), the buffer will be initialised to the contents -of the original stream, -and subsequent calls to the positions within the buffer will not be -routed to the original stream. In the same way WriteAt() will change -the data in the buffer, but not in the actual stream. In order to flush -the changes to the original stream, use the Flush() method. Deleting -the object when you are done with it will also flush the stream and -update the original stream. + This class works as follows. After constructing a BBufferIO object that you + want to be buffered, you can create this object. The constructor takes a + \a stream parameter that points to the object to be buffered. You then use + this object as a proxy to the resource you want to read of or write to. As + soon as you use ReadAt(), the buffer will be initialised to the contents + of the original stream, + and subsequent calls to the positions within the buffer will not be + routed to the original stream. In the same way WriteAt() will change + the data in the buffer, but not in the actual stream. In order to flush + the changes to the original stream, use the Flush() method. Deleting + the object when you are 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. + \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. */ /*! diff --git a/docs/user/support/Locker.dox b/docs/user/support/Locker.dox new file mode 100644 index 0000000000..5f4a584be1 --- /dev/null +++ b/docs/user/support/Locker.dox @@ -0,0 +1,127 @@ +/*! +\file Locker.h +\brief Provides locking class BLocker. +*/ + +/*! +\class BLocker +\ingroup support +\ingroup libbe +\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. +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 +is a lot more efficient than acquiring a semaphore, thus this type of locking +is much prefered. + +It basically works as follows. Whenever you newly created BLocker object +recieves a locking request, it atomically sets the benaphore variable to +\c 1. Then only additional calls from different threads will utilize the +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. + +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 +BLocker, but block inevitably with a semaphore. Let's pretend I call \c Water(): + +\code +status_t +Flower::Grow(int length) +{ + if (fLock->Lock()) { + fLength += lenght; + fLock->Unlock(); + return B_OK; + } else { + return B_ERROR; + } +} + +status_t +Flower::Water(int amount) +{ + if (fLock->Lock()) { + status_t status = Grow(amount * 2); + fLock->Unlock(); + return status; + } else { + return B_ERROR; + } +} +\endcode + +This code would work because BLocker keeps track of the amount of lock +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. +*/ + +/*! +\fn BLocker::BLocker() +\brief Constructor. +*/ + +/*! +\fn BLocker::BLocker(const char* name) +\brief Constructor. +*/ + +/*! +\fn BLocker::BLocker(bool benaphoreStyle) +\brief Constructor. +*/ + +/*! +\fn BLocker::BLocker(const char* name, bool benaphoreStyle) +\brief Constructor. +*/ + +/*! +\fn virtual BLocker::~BLocker() +\brief Destructor. +*/ + +/*! +\fn bool BLocker::Lock(void) +\brief Add a lock request and block on it until we get it. +*/ + +/*! +\fn status_t BLocker::LockWithTimeout(bigtime_t timeout) +\brief Add a lock request and block until we get it with a maximum time. +*/ + +/*! +\fn void BLocker::Unlock(void) +\brief Give up the lock count. +*/ + +/*! +\fn thread_id BLocker::LockingThread(void) const +\brief Return the \c thread_id of the thread that's currently holding the lock. +*/ + +/*! +\fn bool BLocker::IsLocked(void) const +\brief Check if your lock succeeded. +*/ + +/*! +\fn int32 BLocker::CountLocks(void) const +\brief Return the number of recursive locks that are currently held. +*/ + +/*! +\fn nt32 BLocker::CountLockRequests(void) const +\brief Return the number of pending lock requests. +*/ + +/*! +\fn sem_id BLocker::Sem(void) const +\brief Return the sem_id of the semaphore this object holds. +*/ diff --git a/docs/user/support/SupportDefs.dox b/docs/user/support/SupportDefs.dox new file mode 100644 index 0000000000..b79b59a6d2 --- /dev/null +++ b/docs/user/support/SupportDefs.dox @@ -0,0 +1,339 @@ +/*! +\file SupportDefs.h +\ingroup support +\brief Defines basic types and definitions for the Haiku API. +*/ + +/*! +\name Short byte long Type Formats +*/ + +//! @{ + +/*! +\typedef typedef signed char int8 +*/ + +/*! +\typedef typedef unsigned char uint8 +*/ + +/*! +\typedef typedef volatile signed char vint8 +*/ + +/*! +\typedef typedef volatile unsigned char vuint8 +*/ + +//! @} + +/*! +\name Short 2-byte long Type Formats +*/ + +//! @{ + +/*! +\typedef typedef short int16 +*/ + +/*! +\typedef typedef unsigned short uint16 +*/ + +/*! +\typedef typedef volatile short vint16 +*/ + +/*! +\typedef typedef volatile unsigned short vuint16 +*/ + +//! @} + +/*! +\name Short 4-byte long Type Formats +*/ + +//! @{ + +/*! +\typedef typedef long int32 +*/ + +/*! +\typedef typedef unsigned long uint32 +*/ + +/*! +\typedef typedef volatile long vint32 +*/ + +/*! +\typedef typedef volatile unsigned long vuint32 +*/ + +//! @} + +/*! +\name Short 8-byte long Type Formats +*/ + +//! @{ + +/*! +\typedef typedef long long int64 +*/ + +/*! +\typedef typedef unsigned long long uint64 +*/ + +/*! +\typedef typedef volatile long long vint64 +*/ + +/*! +\typedef typedef volatile unsigned long long vuint64 +*/ + +//! @} + +/*! +\name Short volatile Type Formats +*/ + +//! @{ + +/*! +\typedef typedef volatile long vlong +*/ + +/*! +\typedef typedef volatile int vint +*/ + +/*! +\typedef typedef volatile short vshort +*/ + +/*! +\typedef typedef volatile char vchar +*/ + +/*! +\typedef typedef volatile unsigned long vulong +*/ + +/*! +\typedef typedef volatile unsigned int vuint +*/ + +/*! +\typedef typedef volatile unsigned short vushort +*/ + +/*! +\typedef typedef volatile unsigned char vuchar +*/ + +//! @} + +/*! +\name Character Type Formats +*/ + +//! @{ + +/*! +\typedef typedef unsigned char uchar +*/ + +/*! +\typedef typedef unsigned short unichar +*/ + +//! @} + +/*! +\name Descriptive Type Formats +*/ + +//! @{ + +/*! +\typedef typedef int32 status_t +\brief Represents one of the status codes defined in Error.h +*/ + +/*! +\typedef typedef int64 bigtime_t +\brief Represents time. The unit depends on the context of the function. +*/ + +/*! +\typedef typedef uint32 type_code +\brief Represents a type code. See TypeCode.h for possible values. +*/ + +/*! +\typedef typedef uint32 perform_code +\brief Unused. Defined by Be to support 'hidden' commands or + extensions to classes. The Haiku API has none of these. +*/ + +//! @} + +//////////////// Odds and ends + +/*! +\var const char *B_EMPTY_STRING +\brief Defines an empty string. Currently defined as the C-string "". +*/ + +/*! +\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). +*/ + +/*! +\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). +*/ + +/*! +\def NULL +\brief Defines the constant \c NULL if it hasn't been defined anywhere before. +*/ + +/*! +\addtogroup support_globals +*/ + +//! @{ + +/*! +\fn int32 atomic_set(vint32 *value, int32 newValue) +\brief Undocumented. +\sa atomic_set64() for a version that works on \c long \c long +\sa atomic_test_and_set(), atomic_add(), atomic_and(), + atomic_or(), atomic_get() +*/ + +/*! +\fn int32 atomic_test_and_set(vint32 *value, int32 newValue, int32 testAgainst) +\brief Undocumented. +\sa atomic_test_and_set64() for a version that works on \c long \c long +\sa atomic_set(), atomic_add(), atomic_and(), + atomic_or(), atomic_get() +*/ + +/*! +\fn int32 atomic_add(vint32 *value, int32 addValue) +\brief Undocumented. +\sa atomic_add64() for a version that works on \c long \c long +\sa atomic_set(), atomic_test_and_set(), atomic_and(), + atomic_or(), atomic_get() +*/ + +/*! +\fn int32 atomic_and(vint32 *value, int32 andValue) +\brief Undocumented. +\sa atomic_and64() for a version that works on \c long \c long +\sa atomic_set(), atomic_test_and_set(), atomic_add(), + atomic_or(), atomic_get() +*/ + + +/*! +\fn int32 atomic_or(vint32 *value, int32 orValue) +\brief Undocumented. +\sa atomic_or64() for a version that works on \c long \c long +\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(), + atomic_get() +*/ + +/*! +\fn int32 atomic_get(vint32 *value) +\brief Undocumented. +\sa atomic_get64() for a version that works on \c long \c long +\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(), + atomic_or() +*/ + +/*! +\fn int64 atomic_set64(vint64 *value, int64 newValue) +\brief Undocumented. +\sa atomic_set() for a version that works on an \c int32 +\sa atomic_test_and_set64(), atomic_add64(), atomic_and64(), + atomic_or64(), atomic_get64() +*/ + +/*! +\fn int64 atomic_test_and_set64(vint64 *value, int64 newValue, int64 testAgainst) +\brief Undocumented. +\sa atomic_test_and_set() for a version that works on an \c int32 +\sa atomic_set64(), atomic_add64(), atomic_and64(), + atomic_or64(), atomic_get64() +*/ + +/*! +\fn int64 atomic_add64(vint64 *value, int64 addValue) +\brief Undocumented. +\sa atomic_add() for a version that works on an \c int32 +\sa atomic_set64(), atomic_test_and_set64(), atomic_and64(), + atomic_or64(), atomic_get64() +*/ + +/*! +\fn int64 atomic_and64(vint64 *value, int64 andValue) +\brief Undocumented. +\sa atomic_and() for a version that works on an \c int32 +\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), + atomic_or64(), atomic_get64() +*/ + +/*! +\fn int64 atomic_or64(vint64 *value, int64 orValue) +\brief Undocumented. +\sa atomic_or() for a version that works on an \c int32 +\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(), + atomic_get64() +*/ + +/*! +\fn int64 atomic_get64(vint64 *value) +\brief Undocumented. +\sa atomic_get() for a version that works on an \c int32 +\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(), + atomic_or64() +*/ + +//! @} + +/*! +\fn void* get_stack_frame(void) +\brief This is internal, I guess. Else this needs to be documented. +\internal +*/ + +//! @{ + +/*! +\def FALSE +\brief Obsolete. Use \c false. +*/ + +/*! +\def TRUE +\brief Obsolete. Use \c true. +*/ + +//! @} diff --git a/docs/user/support/stopwatch.dox b/docs/user/support/stopwatch.dox index 05b40e464f..bfaa5e9492 100644 --- a/docs/user/support/stopwatch.dox +++ b/docs/user/support/stopwatch.dox @@ -42,7 +42,7 @@ information on the elapsed time to standard output. /*! \fn void BStopWatch::Suspend() -\brief Suspends the timer. +\brief Suspend the timer. \sa Resume() */ diff --git a/docs/user/support/string.dox b/docs/user/support/string.dox index 1cd57f74ff..4a08436d6f 100644 --- a/docs/user/support/string.dox +++ b/docs/user/support/string.dox @@ -1,16 +1,23 @@ +// +// Copyright 2007, Haiku Inc. All Rights Reserved. +// +// Distributed under the terms of the MIT License. +// +// // Documentation by: // Niels Sascha Reedijk // Corresponds to: // /trunk/headers/os/support/String.h rev 19731 // /trunk/src/kits/support/String.cpp rev 19731 +// /*! \file String.h -\brief Implements the BString class and global operators and functions for handling strings. +\brief Defines the BString class and global operators and functions for handling strings. */ /*! -\class BString +\class BString String.h \ingroup support \ingroup libbe \brief String class supporting common string operations. @@ -26,7 +33,7 @@ takes care to allocate and free memory for you, so it will always be /*! \var char* BString::fPrivateData -\brief BString's storage for data +\brief BString's storage for data. This member is deprecated and might even go \c private in future releases. @@ -563,7 +570,7 @@ This method calls operator+=(const char *str). \fn void BString::MoveInto(char *into, int32 from, int32 length) \brief Move the BString data (or part of it) into the given buffer. \param into The buffer where to move the object. -\param from The offset (zero based) where to begin the move +\param from The offset (zero based) where to begin the move. \param length The amount of bytes to move. */ diff --git a/docs/user/support/support_intro.dox b/docs/user/support/support_intro.dox index d3734c51f7..e06063611f 100644 --- a/docs/user/support/support_intro.dox +++ b/docs/user/support/support_intro.dox @@ -1,43 +1,31 @@ /*! -\page support_intro Introduction to the Support Kit + \page support_intro Introduction to the Support Kit -The Support Kit provides a handy set of functions and classes that you can -use in your applications. Have a look at the overview, or go straight to -the complete \link support list of components \endlink of this kit. + The Support Kit provides a handy set of functions and classes that you can + use in your applications. Have a look at the overview, or go straight to + the complete \link support list of components \endlink of this kit. -\section Overview -
    -
  • Threading utility classes:
    • -
      -
    • BLocker
      • -
    • BAutolock
      • -
    • Thread Local Storage
      • -
    -
  • Archiving and IO:
    • -
      -
    • BArchivable (\link support_archiving tutorial\endlink)
      • -
    • BFlattenable
      • -
    • BDataIO
      • -
        -
      • BPositionIO
        • -
          -
        • BBufferIO
          • -
        • BMemoryIO
          • -
        • BMallocIO
          • -
        -
      -
    -
  • Container classes:
    • -
      -
    • BBlockCache
      • -
    • BList
      • -
    • BString
      • -
    -
  • BStopWatch
    • -
  • \ref support_globals "Global functions"
    • -
  • \ref TypeConstants.h "Common types and constants"
    • -
  • Error codes for all kits
    • -
+ \section Overview + - Threading utility classes: + - BLocker + - BAutolock + - Thread Local Storage + - Archiving and IO: + - BArchivable (\link support_archiving tutorial\endlink) + - BFlattenable + - BDataIO + - BPositionIO + - BBufferIO + - BMemoryIO + - BMallocIO + - Container classes: + - BBlockCache + - BList + - BString + - BStopWatch + - \ref support_globals "Global functions" + - \ref TypeConstants.h "Common types and constants" + - Error codes for all kits */ // Short listing of documents that belong to this module so that people can diff --git a/docs/user/support/typeconstants.dox b/docs/user/support/typeconstants.dox index 35c1cc7c07..ac1a212422 100644 --- a/docs/user/support/typeconstants.dox +++ b/docs/user/support/typeconstants.dox @@ -1,6 +1,12 @@ /*! \file TypeConstants.h \ingroup support +\brief Represents typecodes 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 +data of which you don't know the type, but you want to send or receive it +anyway. */ /*! @@ -8,56 +14,6 @@ \brief General type when the exact contents is not yet known. */ -/*! -\var B_BOOL_TYPE -\brief Boolean value -*/ - -/*! -\var B_CHAR_TYPE -\brief Represents the \c char type -*/ - -/*! -\var B_COLOR_8_BIT_TYPE -\brief Represents a one-byte colour -*/ - -/*! -\var B_DOUBLE_TYPE -\brief Represents the \c double type -*/ - -/*! -\var B_FLOAT_TYPE -\brief Represents the \c float type -*/ - -/*! -\var B_GRAYSCALE_8_BIT_TYPE -\brief Represents a byte-long grayscale value -*/ - -/*! -\var B_INT16_TYPE -\brief Represents a \c short type -*/ - -/*! -\var B_INT32_TYPE -\brief Represents a \c long type -*/ - -/*! -\var B_INT64_TYPE -\brief Represents a \c long \c long type -*/ - -/*! -\var B_INT8_TYPE -\brief Represents a \c char type used for integer storage -*/ - /*! \var B_ATOM_TYPE \brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. @@ -68,6 +24,86 @@ \brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. */ +/*! +\var B_BOOL_TYPE +\brief Boolean value. +*/ + +/*! +\var B_CHAR_TYPE +\brief Represents the \c char type. +*/ + +/*! +\var B_COLOR_8_BIT_TYPE +\brief Represents a one-byte colour. +*/ + +/*! +\var B_DOUBLE_TYPE +\brief Represents the \c double type. +*/ + +/*! +\var B_FLOAT_TYPE +\brief Represents the \c float type. +*/ + +/*! +\var B_GRAYSCALE_8_BIT_TYPE +\brief Represents a byte-long grayscale value. +*/ + +/*! +\var B_INT16_TYPE +\brief Represents a \c short type. +*/ + +/*! +\var B_INT32_TYPE +\brief Represents a \c long type. +*/ + +/*! +\var B_INT64_TYPE +\brief Represents a \c long \c long type. +*/ + +/*! +\var B_INT8_TYPE +\brief Represents a \c char type used for integer storage. +*/ + +/*! +\var B_LARGE_ICON_TYPE +\brief Represents a large icon. +*/ + +/*! +\var B_MEDIA_PARAMETER_GROUP_TYPE +\brief Represents the BParameterGroup type from the media kit. +*/ + +/*! +\var B_MEDIA_PARAMETER_TYPE +\brief Represents the BParameter type from the media kit. +*/ + +/*! +\var B_MEDIA_PARAMETER_WEB_TYPE +\brief Represents the BParameterWeb type from the media kit. +*/ + +/*! +\var B_MESSAGE_TYPE +\brief Represents a BMessage type. +*/ + +/*! +\var B_MESSENGER_TYPE +\brief Represents a BMessenger type. +*/ + // Todo: the rest of the types /*! @{