From 9889ca4a68133cf86c7c72afce0fb251294e5d67 Mon Sep 17 00:00:00 2001 From: Niels Sascha Reedijk Date: Mon, 2 Apr 2007 11:39:10 +0000 Subject: [PATCH] * book.dox Reformat according to the guidelines * BufferIO.dox Reformat according to the guidelines * DataIO.dox Reformat according to the guidelines * Flattenable.dox New documentation. * Locker.dox Finished documentation. * SupportDefs.dox Reformat according to the guidelines git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@20511 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- docs/user/book.dox | 37 ++--- docs/user/support/BufferIO.dox | 179 +++++++++++---------- docs/user/support/DataIO.dox | 24 ++- docs/user/support/Flattenable.dox | 171 ++++++++++++++++++++ docs/user/support/Locker.dox | 227 ++++++++++++++++++--------- docs/user/support/SupportDefs.dox | 251 +++++++++++++++--------------- 6 files changed, 579 insertions(+), 310 deletions(-) create mode 100644 docs/user/support/Flattenable.dox diff --git a/docs/user/book.dox b/docs/user/book.dox index 944f511cc0..a89fed4ea8 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -1,31 +1,32 @@ /*! -\mainpage The Haiku Book + \mainpage The Haiku Book -\section kits Kits and Servers + \section kits Kits and Servers -- \ref midi1 -- \ref midi2 | \link midi2_intro \em Introduction \endlink -- \ref support | \link support_intro \em Introduction \endlink + - \ref midi1 + - \ref midi2 | \link midi2_intro \em Introduction \endlink + - \ref support | \link support_intro \em Introduction \endlink -\section notes General Notes and Information -- \ref compatibility + \section notes General Notes and Information + - \ref compatibility + - \ref apidoc */ -// Define main kits +///// Define main kits ///// /*! -\defgroup midi2 MIDI 2 Kit -\brief API for producing and consuming MIDI events. -\defgroup libmidi2 (libmidi2.so) -\defgroup support Support Kit -\brief Collection of utility classes that are used throughout the API. -\defgroup libbe (libbe.so) -\defgroup libroot (libroot.so) + \defgroup midi2 MIDI 2 Kit + \brief API for producing and consuming MIDI events. + \defgroup libmidi2 (libmidi2.so) + \defgroup support Support Kit + \brief Collection of utility classes that are used throughout the API. + \defgroup libbe (libbe.so) + \defgroup libroot (libroot.so) */ -// Subgroups +///// Subgroups ///// /*! -\defgroup support_globals Global functions in the support kit -\ingroup support + \defgroup support_globals Global functions in the support kit + \ingroup support */ \ No newline at end of file diff --git a/docs/user/support/BufferIO.dox b/docs/user/support/BufferIO.dox index e1d8411108..df9d97f9c2 100644 --- a/docs/user/support/BufferIO.dox +++ b/docs/user/support/BufferIO.dox @@ -1,3 +1,15 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Stefano Ceccherini (burton666@libero.it) + * Corresponds to: + * /trunk/headers/os/support/BufferIO.h rev 19972 + * /trunk/src/kits/support/BufferIO.cpp rev 20510 + */ + /*! \file BufferIO.h \brief Provides the BBufferIO class. @@ -38,126 +50,135 @@ */ /*! -\fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize, bool ownsStream) -\brief Initialize a BBufferIO object. - -The constructor will create a buffer of the given size -and associate the object with the given BPositionIO stream. + \fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize, bool ownsStream) + \brief Initialize a BBufferIO object. + + The constructor will create a buffer of the given size + and associate the object with the given BPositionIO stream. -\param stream A pointer to a BPositionIO object. -\param bufferSize The size of the buffer that the object will allocate and use. -\param ownsStream Specifies if the object will delete the stream on destruction. + \param stream A pointer to a BPositionIO object. + \param bufferSize The size of the buffer that the object will allocate and + use. + \param ownsStream Specifies if the object will delete the stream on + destruction. */ /*! -\fn BBufferIO::~BBufferIO() -\brief Free the resources allocated by the object + \fn BBufferIO::~BBufferIO() + \brief Free the resources allocated by the object -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. + 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. */ /*! -\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. -\param buffer A pointer to a buffer where to copy the read data. -\param size The amount of bytes to read. -\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. -\retval B_BAD_VALUE The \c buffer parameter is not valid. + \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. + \param buffer A pointer to a buffer where to copy the read data. + \param size The amount of bytes to read. + \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. + \retval B_BAD_VALUE The \c buffer parameter is not valid. */ /*! -\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. -\param pos The offset into the stream where to write. -\param buffer A pointer to a buffer which contains the data to write. -\param size The amount of bytes to write. -\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. -\retval B_BAD_VALUE The \c buffer parameter is not valid. + \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. + \param pos The offset into the stream where to write. + \param buffer A pointer to a buffer which contains the data to write. + \param size The amount of bytes to write. + \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. + \retval B_BAD_VALUE The \c buffer parameter is not valid. */ /*! -\fn off_t BBufferIO::Seek(off_t position, uint32 seekMode) -\brief Set the position in the stream. - - Set the position in the stream where the Read() and Write() functions - (inherited from BPositionIO) begin reading and writing. - How the position argument is understood depends on the seek_mode flag. - - \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). + \fn off_t BBufferIO::Seek(off_t position, uint32 seekMode) + \brief Set the position in the stream. + + Set the position in the stream where the Read() and Write() functions + (inherited from BPositionIO) begin reading and writing. + How the position argument is understood depends on the seek_mode flag. + + \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). - \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. + \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. */ /*! -\fn off_t BBufferIO::Position() const -\brief Return the current position in the stream. -\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. + \fn off_t BBufferIO::Position() const + \brief Return the current position in the stream. + \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. */ /*! -\fn status_t BBufferIO::SetSize(off_t size) -\brief Call the SetSize() function of the assigned BPositionIO stream. -\param size The new size of the BPositionIO object. -\retval B_OK The stream is resized. -\retval B_NO_INIT The object is not associated with a valid BPositionIO stream. + \fn status_t BBufferIO::SetSize(off_t size) + \brief Call the SetSize() function of the assigned BPositionIO stream. + \param size The new size of the BPositionIO object. + \retval B_OK The stream is resized. + \retval B_NO_INIT The object is not associated with a valid BPositionIO + stream. */ /*! -\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. + \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. */ /*! -\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. + \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. */ /*! -\fn size_t BBufferIO::BufferSize() const -\brief Return the size of the internal buffer. -\return The size of the buffer allocated by the object. + \fn size_t BBufferIO::BufferSize() const + \brief Return the size of the internal buffer. + \return The size of the buffer allocated by the object. */ /*! -\fn bool BBufferIO::OwnsStream() const -\brief Tell if the BBufferIO object "owns" the specified stream. -\retval true The object "owns" the stream and will destroy it upon destruction. -\retval false The object does not own the stream. -\sa SetOwnsStream() + \fn bool BBufferIO::OwnsStream() const + \brief Tell if the BBufferIO object "owns" the specified stream. + \retval true The object "owns" the stream and will destroy it upon + destruction. + \retval false The object does not own the stream. + \see SetOwnsStream() */ /*! -\fn void BBufferIO::SetOwnsStream(bool owns_stream) -\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. + \fn void BBufferIO::SetOwnsStream(bool owns_stream) + \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. */ /*! -\fn void BBufferIO::PrintToStream() const -\brief Print the object to stdout. + \fn void BBufferIO::PrintToStream() const + \brief Print the object to stdout. */ diff --git a/docs/user/support/DataIO.dox b/docs/user/support/DataIO.dox index fe97a48723..6fb9a8bcaf 100644 --- a/docs/user/support/DataIO.dox +++ b/docs/user/support/DataIO.dox @@ -1,16 +1,14 @@ -// -// Copyright 2007, Haiku Inc. All Rights Reserved. -// -// Distributed under the terms of the MIT License. -// -// -// Documentation by: -// Niels Sascha Reedijk -// Stefano Ceccherini (burton666@libero.it) -// Corresponds to: -// /trunk/headers/os/support/DataIO.h rev 17981 -// /trunk/src/kits/support/DataIO.cpp rev 17981 -// +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Stefano Ceccherini (burton666@libero.it) + * Corresponds to: + * /trunk/headers/os/support/DataIO.h rev 17981 + * /trunk/src/kits/support/DataIO.cpp rev 20510 + */ /*! \file DataIO.h diff --git a/docs/user/support/Flattenable.dox b/docs/user/support/Flattenable.dox new file mode 100644 index 0000000000..3edf9af621 --- /dev/null +++ b/docs/user/support/Flattenable.dox @@ -0,0 +1,171 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation written by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/Flattenable.h rev 19972 + * /trunk/src/kits/support/Flattenable.cpp rev 12963 + */ + +/*! + \file Flattenable.h + \brief Provides the BFlattenable interface +*/ + +/*! + \class BFlattenable + \ingroup support + \ingroup libbe + \brief Interface for classes that can flatten and unflatten themselves to + 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 + 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. + + 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. + + 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 + methods handle the actual flattening and unflattening. To identify flattened + data in for example BMessage, the object has a type_code. Type codes are + four byte long integers. You can choose to flatten to one of the existing + types, if you are certain that you are compatible to those, but you'll + usually define your own type. Your best option is by using a multicharacter + constant, such as 'STRI'. Implement TypeCode() to return the type you + support. Implement FlattenedSize() to make sure that other objects can + provide the right buffers. Implement IsFixedSize() to return whether your + objects always store to a fixed size. + + See the following example: + \code +type_code CUSTOM_STRING_TYPE = 'CUST'; + +class CustomString : public BFlattenable +{ +public: + 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); }; + + 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 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 + + Have a look at TypeConstants.h for a list of all the types that the Haiku + API defines. + + The Haiku API has a second interface for storing objects, which is with + BArchivable. BArchivable is for more complex cases. Instead of one flat + datastream, it stores an object in a BMessage. In that way you can reflect + internals of a class better. It also provides an interface for instantiating + objects, that is, for objects to restore themselves from a BMessage. In + essence, BArchivable is more suitable for objects that are alive. In short + BFlattenable is for data objects, BArchivable is for 'live' objects. + + Other classes in the API that support flattening and unflattening are for + example BMessage, which enables you to conveniently write flattened data + 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. +*/ + +/*! + \fn virtual bool BFlattenable::IsFixedSize() const = 0 + \brief Pure virtual that should return whether or not flattened objects of + this type always have a fixed size. +*/ + +/*! + \fn virtual type_code BFlattenable::TypeCode() const = 0 + \brief Pure virtual that should return which 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. +*/ + +/*! + \fn virtual ssize_t BFlattenable::FlattenedSize() const = 0 + \brief Pure virtual that should return the size of the flattened object in + bytes. +*/ + +/*! + \fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const = 0 + \brief Pure virtual that should flatten the object into the supplied + \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 + larger than the size of the buffer. + + \param buffer The buffer to flatten in. + \param size The size of the buffer. + \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. +*/ + +/*! + \fn bool BFlattenable::AllowsTypeCode(type_code code) const + \brief Return whether or not the supplied type_code is supported. + + This default implementation checks the \a code argument against the type_code + returned by TypeCode(). + + \param code The type_code constant you want to check for. + \retval true The type_code is supported. + \retval false The type_code is not supported. +*/ + +/*! + \fn virtual status_t BFlattenable::Unflatten(type_code code, const void* buffer, ssize_t size) = 0 + \brief Pure virtual that should unflatten the buffer and put the contents + into the current object. + + Make sure that the supplied buffer is not \c NULL and that you actually + support the typecode. + + \param code The type_code this data is. + \param buffer The buffer to unflatten the data from. + \param size The size of the data. + \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. +*/ + +/*! + \fn virtual BFlattenable::~BFlattenable() + \brief Destructor. Does nothing. +*/ diff --git a/docs/user/support/Locker.dox b/docs/user/support/Locker.dox index 5f4a584be1..14169ae0ee 100644 --- a/docs/user/support/Locker.dox +++ b/docs/user/support/Locker.dox @@ -1,127 +1,204 @@ +/* + * 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/Locker.h rev 19972 + * /trunk/src/kits/support/Locker.cpp rev 13826 + */ + /*! -\file Locker.h -\brief Provides locking class BLocker. + \file Locker.h + \brief Provides locking class BLocker. */ /*! -\class BLocker -\ingroup support -\ingroup libbe -\brief Semaphore-type class for thread safety. + \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. + 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. + 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(): + 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; + \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; + status_t + Flower::Water(int amount) + { + if (fLock->Lock()) { + status_t status = Grow(amount * 2); + fLock->Unlock(); + return status; + } else { + return B_ERROR; + } } -} -\endcode + \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. + 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() + \brief Constructor. + + Create a new BLocker with the default name of some BLocker. 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. + + \see BLocker(const char* name, bool benaphoreStyle) for all the options. */ /*! -\fn BLocker::BLocker(const char* name) -\brief Constructor. + \fn BLocker::BLocker(const char* name) + \brief Constructor. + + Create a new BLocker with 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 B_OS_NAME_LENGTH constant, + which includes the \c \\0 character. + + \see BLocker(const char* name, bool benaphoreStyle) for all the options. */ /*! -\fn BLocker::BLocker(bool benaphoreStyle) -\brief Constructor. + \fn BLocker::BLocker(bool benaphoreStyle) + \brief Constructor. + + Creates a BLocker with the default name of some BLocker. + + \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. + + \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. + + \see BLocker(const char* name, bool benaphoreStyle) if you also want to set a + name. */ /*! -\fn BLocker::BLocker(const char* name, bool benaphoreStyle) -\brief Constructor. + \fn BLocker::BLocker(const char* name, bool benaphoreStyle) + \brief Constructor. + + \param name A NULL-terminated string that contains the name of the semaphore. + Note that the length of the names are limited to 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 it's + functioning. */ /*! -\fn virtual BLocker::~BLocker() -\brief Destructor. + \fn virtual BLocker::~BLocker() + \brief Destructor. + + 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. */ /*! -\fn bool BLocker::Lock(void) -\brief Add a lock request and block on it until we get it. + \fn bool BLocker::Lock() + \brief Add a lock request and block on it until we get it. + + \retval true Lock acquired succesfully. + \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. + + \see LockWithTimeout(bigtime_t timeout), Unlock() */ /*! -\fn status_t BLocker::LockWithTimeout(bigtime_t timeout) -\brief Add a lock request and block until we get it with a maximum time. + \fn status_t BLocker::LockWithTimeout(bigtime_t timeout) + \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), + \e relative from now. + + \see Lock(), Unlock() */ /*! -\fn void BLocker::Unlock(void) -\brief Give up the lock count. + \fn void BLocker::Unlock(void) + \brief Release the lock that's currently held. */ /*! -\fn thread_id BLocker::LockingThread(void) const -\brief Return the \c thread_id of the thread that's currently holding the lock. + \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 bool BLocker::IsLocked(void) const + \brief Check if the calling thread is actually holding the lock. + + \retval true The thread from which this method is called from is currently + holding the lock. + \retval false The object is unlocked or the lock is held by another thread. */ /*! -\fn int32 BLocker::CountLocks(void) const -\brief Return the number of recursive locks that are currently held. + \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 nt32 BLocker::CountLockRequests(void) const + \brief Return the number of threads with a pending lock request. */ /*! -\fn sem_id BLocker::Sem(void) const -\brief Return the sem_id of the semaphore this object holds. + \fn sem_id BLocker::Sem(void) const + \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. */ diff --git a/docs/user/support/SupportDefs.dox b/docs/user/support/SupportDefs.dox index b79b59a6d2..06905af9a5 100644 --- a/docs/user/support/SupportDefs.dox +++ b/docs/user/support/SupportDefs.dox @@ -1,186 +1,187 @@ /*! -\file SupportDefs.h -\ingroup support -\brief Defines basic types and definitions for the Haiku API. + \file SupportDefs.h + \ingroup support + \brief Defines basic types and definitions for the Haiku API. */ /*! -\name Short byte long Type Formats + \name Short byte long Type Formats */ //! @{ /*! -\typedef typedef signed char int8 + \typedef typedef signed char int8 */ /*! -\typedef typedef unsigned char uint8 + \typedef typedef unsigned char uint8 */ /*! -\typedef typedef volatile signed char vint8 + \typedef typedef volatile signed char vint8 */ /*! -\typedef typedef volatile unsigned char vuint8 + \typedef typedef volatile unsigned char vuint8 */ //! @} /*! -\name Short 2-byte long Type Formats + \name Short 2-byte long Type Formats */ //! @{ /*! -\typedef typedef short int16 + \typedef typedef short int16 */ /*! -\typedef typedef unsigned short uint16 + \typedef typedef unsigned short uint16 */ /*! -\typedef typedef volatile short vint16 + \typedef typedef volatile short vint16 */ /*! -\typedef typedef volatile unsigned short vuint16 + \typedef typedef volatile unsigned short vuint16 */ //! @} /*! -\name Short 4-byte long Type Formats + \name Short 4-byte long Type Formats */ //! @{ /*! -\typedef typedef long int32 + \typedef typedef long int32 */ /*! -\typedef typedef unsigned long uint32 + \typedef typedef unsigned long uint32 */ /*! -\typedef typedef volatile long vint32 + \typedef typedef volatile long vint32 */ /*! -\typedef typedef volatile unsigned long vuint32 + \typedef typedef volatile unsigned long vuint32 */ //! @} /*! -\name Short 8-byte long Type Formats + \name Short 8-byte long Type Formats */ //! @{ /*! -\typedef typedef long long int64 + \typedef typedef long long int64 */ /*! -\typedef typedef unsigned long long uint64 + \typedef typedef unsigned long long uint64 */ /*! -\typedef typedef volatile long long vint64 + \typedef typedef volatile long long vint64 */ /*! -\typedef typedef volatile unsigned long long vuint64 + \typedef typedef volatile unsigned long long vuint64 */ //! @} /*! -\name Short volatile Type Formats + \name Short volatile Type Formats */ //! @{ /*! -\typedef typedef volatile long vlong + \typedef typedef volatile long vlong */ /*! -\typedef typedef volatile int vint + \typedef typedef volatile int vint */ /*! -\typedef typedef volatile short vshort + \typedef typedef volatile short vshort */ /*! -\typedef typedef volatile char vchar + \typedef typedef volatile char vchar */ /*! -\typedef typedef volatile unsigned long vulong + \typedef typedef volatile unsigned long vulong */ /*! -\typedef typedef volatile unsigned int vuint + \typedef typedef volatile unsigned int vuint */ /*! -\typedef typedef volatile unsigned short vushort + \typedef typedef volatile unsigned short vushort */ /*! -\typedef typedef volatile unsigned char vuchar + \typedef typedef volatile unsigned char vuchar */ //! @} /*! -\name Character Type Formats + \name Character Type Formats */ //! @{ /*! -\typedef typedef unsigned char uchar + \typedef typedef unsigned char uchar */ /*! -\typedef typedef unsigned short unichar + \typedef typedef unsigned short unichar */ //! @} /*! -\name Descriptive Type Formats + \name Descriptive Type Formats */ //! @{ /*! -\typedef typedef int32 status_t -\brief Represents one of the status codes defined in Error.h + \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 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 type_code + \brief Represents a certain type of data. See TypeConstants.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. + \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. */ //! @} @@ -188,152 +189,152 @@ //////////////// Odds and ends /*! -\var const char *B_EMPTY_STRING -\brief Defines an empty string. Currently defined as the C-string "". + \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. + \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). */ /*! -\def max_c(a,b) -\brief Returns the maximum of values a and 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). + \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. + \def NULL + \brief Defines the constant \c NULL if it hasn't been defined anywhere before. */ /*! -\addtogroup support_globals + \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_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_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_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_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_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 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_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_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_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_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_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 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 + \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 FALSE + \brief Obsolete. Use \c false. */ /*! -\def TRUE -\brief Obsolete. Use \c true. + \def TRUE + \brief Obsolete. Use \c true. */ //! @}