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

* book.dox Reformat according to the guidelines

Browse Source 
* 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
This commit is contained in:
Niels Sascha Reedijk
2007-04-02 11:39:10 +00:00
parent a36e40dcda
commit 9889ca4a68
6 changed files with 579 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/book.dox
+19 -18
View File
@@ -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
*/
docs/user/support/BufferIO.dox
+100 -79
View File
@@ -1,3 +1,15 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Stefano Ceccherini ([email protected])
* 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.
*/
docs/user/support/DataIO.dox
+11 -13
View File
@@ -1,16 +1,14 @@
//
// Copyright 2007, Haiku Inc. All Rights Reserved.
//
// Distributed under the terms of the MIT License.
//
//
// Documentation by:
// Niels Sascha Reedijk <[email protected]>
// Stefano Ceccherini ([email protected])
// 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 <[email protected]>
* Stefano Ceccherini ([email protected])
* Corresponds to:
* /trunk/headers/os/support/DataIO.h rev 17981
* /trunk/src/kits/support/DataIO.cpp rev 20510
*/
/*!
\file DataIO.h
docs/user/support/Flattenable.dox
+171
View File
@@ -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 <[email protected]>
* 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,
<em>if your class actually is compatible to those formats</em>, 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.
*/
docs/user/support/Locker.dox
+152 -75
View File
@@ -1,127 +1,204 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* 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 <tt>some BLocker</tt>. 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 <tt>some BLocker</tt>.
\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.
*/
docs/user/support/SupportDefs.dox
+126 -125
View File
@@ -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.
*/
//! @}