626 lines
19 KiB
C++
626 lines
19 KiB
C++
/**
|
|
* @file llbuffer.h
|
|
* @author Phoenix
|
|
* @date 2005-09-20
|
|
* @brief Declaration of buffer and buffer arrays primarily used in I/O.
|
|
*
|
|
* $LicenseInfo:firstyear=2005&license=viewerlgpl$
|
|
* Second Life Viewer Source Code
|
|
* Copyright (C) 2010, Linden Research, Inc.
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
* License as published by the Free Software Foundation;
|
|
* version 2.1 of the License only.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with this library; if not, write to the Free Software
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
*
|
|
* Linden Research, Inc., 945 Battery Street, San Francisco, CA 94111 USA
|
|
* $/LicenseInfo$
|
|
*/
|
|
|
|
#ifndef LL_LLBUFFER_H
|
|
#define LL_LLBUFFER_H
|
|
|
|
/**
|
|
* Declaration of classes used for minimizing calls to new[],
|
|
* memcpy(), and delete[]. Typically, you would create an LLBufferArray,
|
|
* feed it data, modify and add segments as you process it, and feed
|
|
* it to a sink.
|
|
*/
|
|
|
|
#include <list>
|
|
#include <vector>
|
|
|
|
class LLMutex;
|
|
/**
|
|
* @class LLChannelDescriptors
|
|
* @brief A way simple interface to accesss channels inside a buffer
|
|
*/
|
|
class LLChannelDescriptors
|
|
{
|
|
public:
|
|
// enumeration for segmenting the channel information
|
|
enum { E_CHANNEL_COUNT = 3 };
|
|
LLChannelDescriptors() : mBaseChannel(0) {}
|
|
explicit LLChannelDescriptors(S32 base) : mBaseChannel(base) {}
|
|
S32 in() const { return mBaseChannel; }
|
|
S32 out() const { return mBaseChannel + 1; }
|
|
//S32 err() const { return mBaseChannel + 2; }
|
|
protected:
|
|
S32 mBaseChannel;
|
|
};
|
|
|
|
|
|
/**
|
|
* @class LLSegment
|
|
* @brief A segment is a single, contiguous chunk of memory in a buffer
|
|
*
|
|
* Each segment represents a contiguous addressable piece of memory
|
|
* which is located inside a buffer. The segment is not responsible
|
|
* for allocation or deallcoation of the data. Each segment is a light
|
|
* weight object, and simple enough to copy around, use, and generate
|
|
* as necessary.
|
|
* This is the preferred interface for working with memory blocks,
|
|
* since it is the only way to safely, inexpensively, and directly
|
|
* access linear blocks of memory.
|
|
*/
|
|
class LLSegment
|
|
{
|
|
public:
|
|
LLSegment();
|
|
LLSegment(S32 channel, U8* data, S32 data_len);
|
|
~LLSegment();
|
|
|
|
/**
|
|
* @brief Check if this segment is on the given channel.
|
|
*
|
|
*/
|
|
bool isOnChannel(S32 channel) const;
|
|
|
|
/**
|
|
* @brief Get the channel
|
|
*/
|
|
S32 getChannel() const;
|
|
|
|
/**
|
|
* @brief Set the channel
|
|
*/
|
|
void setChannel(S32 channel);
|
|
|
|
/**
|
|
* @brief Return a raw pointer to the current data set.
|
|
*
|
|
* The pointer returned can be used for reading or even adjustment
|
|
* if you are a bit crazy up to size() bytes into memory.
|
|
* @return A potentially NULL pointer to the raw buffer data
|
|
*/
|
|
U8* data() const;
|
|
|
|
/**
|
|
* @brief Return the size of the segment
|
|
*/
|
|
S32 size() const;
|
|
|
|
/**
|
|
* @brief Check if two segments are the same.
|
|
*
|
|
* Two segments are considered equal if they are on the same
|
|
* channel and cover the exact same address range.
|
|
* @param rhs the segment to compare with this segment.
|
|
* @return Returns true if they are equal.
|
|
*/
|
|
bool operator==(const LLSegment& rhs) const;
|
|
|
|
protected:
|
|
S32 mChannel;
|
|
U8* mData;
|
|
S32 mSize;
|
|
};
|
|
|
|
/**
|
|
* @class LLBuffer
|
|
* @brief Abstract base class for buffers
|
|
*
|
|
* This class declares the interface necessary for buffer arrays. A
|
|
* buffer is not necessarily a single contiguous memory chunk, so
|
|
* please do not circumvent the segment API.
|
|
*/
|
|
class LLBuffer
|
|
{
|
|
public:
|
|
/**
|
|
* @brief The buffer base class should have no responsibilities
|
|
* other than an interface.
|
|
*/
|
|
virtual ~LLBuffer() {}
|
|
|
|
/**
|
|
* @brief Generate a segment for this buffer.
|
|
*
|
|
* The segment returned is always contiguous memory. This call can
|
|
* fail if no contiguous memory is available, eg, offset is past
|
|
* the end. The segment returned may be smaller than the requested
|
|
* size. The segment will never be larger than the requested size.
|
|
* @param channel The channel for the segment.
|
|
* @param offset The offset from zero in the buffer.
|
|
* @param size The requested size of the segment.
|
|
* @param segment[out] The out-value from the operation
|
|
* @return Returns true if a segment was found.
|
|
*/
|
|
virtual bool createSegment(S32 channel, S32 size, LLSegment& segment) = 0;
|
|
|
|
/**
|
|
* @brief Reclaim a segment from this buffer.
|
|
*
|
|
* This method is called on a buffer object when a caller is done
|
|
* with a contiguous segment of memory inside this buffer. Since
|
|
* segments can be cut arbitrarily outside of the control of the
|
|
* buffer, this segment may not match any segment returned from
|
|
* <code>createSegment()</code>.
|
|
* @param segment The contiguous buffer segment to reclaim.
|
|
* @return Returns true if the call was successful.
|
|
*/
|
|
virtual bool reclaimSegment(const LLSegment& segment) = 0;
|
|
|
|
/**
|
|
* @brief Test if a segment is inside this buffer.
|
|
*
|
|
* @param segment The contiguous buffer segment to test.
|
|
* @return Returns true if the segment is in the bufffer.
|
|
*/
|
|
virtual bool containsSegment(const LLSegment& segment) const = 0;
|
|
|
|
/**
|
|
* @brief Return the current number of bytes allocated.
|
|
*
|
|
* This was implemented as a debugging tool, and it is not
|
|
* necessarily a good idea to use it for anything else.
|
|
*/
|
|
virtual S32 capacity() const = 0;
|
|
};
|
|
|
|
/**
|
|
* @class LLHeapBuffer
|
|
* @brief A large contiguous buffer allocated on the heap with new[].
|
|
*
|
|
* This class is a simple buffer implementation which allocates chunks
|
|
* off the heap. Once a buffer is constructed, it's buffer has a fixed
|
|
* length.
|
|
*/
|
|
class LLHeapBuffer : public LLBuffer
|
|
{
|
|
public:
|
|
/**
|
|
* @brief Construct a heap buffer with a reasonable default size.
|
|
*/
|
|
LLHeapBuffer();
|
|
|
|
/**
|
|
* @brief Construct a heap buffer with a specified size.
|
|
*
|
|
* @param size The minimum size of the buffer.
|
|
*/
|
|
explicit LLHeapBuffer(S32 size);
|
|
|
|
/**
|
|
* @brief Construct a heap buffer of minimum size len, and copy from src.
|
|
*
|
|
* @param src The source of the data to be copied.
|
|
* @param len The minimum size of the buffer.
|
|
*/
|
|
LLHeapBuffer(const U8* src, S32 len);
|
|
|
|
/**
|
|
* @brief Simple destruction.
|
|
*/
|
|
virtual ~LLHeapBuffer();
|
|
|
|
/**
|
|
* @brief Get the number of bytes left in the buffer.
|
|
*
|
|
* Note that this is not a virtual function, and only available in
|
|
* the LLHeapBuffer as a debugging aid.
|
|
* @return Returns the number of bytes left.
|
|
*/
|
|
S32 bytesLeft() const;
|
|
|
|
/**
|
|
* @brief Generate a segment for this buffer.
|
|
*
|
|
* The segment returned is always contiguous memory. This call can
|
|
* fail if no contiguous memory is available, eg, offset is past
|
|
* the end. The segment returned may be smaller than the requested
|
|
* size. It is up to the caller to delete the segment returned.
|
|
* @param channel The channel for the segment.
|
|
* @param offset The offset from zero in the buffer
|
|
* @param size The requested size of the segment
|
|
* @param segment[out] The out-value from the operation
|
|
* @return Returns true if a segment was found.
|
|
*/
|
|
virtual bool createSegment(S32 channel, S32 size, LLSegment& segment);
|
|
|
|
/**
|
|
* @brief reclaim a segment from this buffer.
|
|
*
|
|
* This method is called on a buffer object when a caller is done
|
|
* with a contiguous segment of memory inside this buffer. Since
|
|
* segments can be cut arbitrarily outside of the control of the
|
|
* buffer, this segment may not match any segment returned from
|
|
* <code>createSegment()</code>.
|
|
* This call will fail if the segment passed in is note completely
|
|
* inside the buffer, eg, if the segment starts before this buffer
|
|
* in memory or ends after it.
|
|
* @param segment The contiguous buffer segment to reclaim.
|
|
* @return Returns true if the call was successful.
|
|
*/
|
|
virtual bool reclaimSegment(const LLSegment& segment);
|
|
|
|
/**
|
|
* @brief Test if a segment is inside this buffer.
|
|
*
|
|
* @param segment The contiguous buffer segment to test.
|
|
* @return Returns true if the segment is in the bufffer.
|
|
*/
|
|
virtual bool containsSegment(const LLSegment& segment) const;
|
|
|
|
/**
|
|
* @brief Return the current number of bytes allocated.
|
|
*/
|
|
virtual S32 capacity() const { return mSize; }
|
|
|
|
protected:
|
|
U8* mBuffer;
|
|
S32 mSize;
|
|
U8* mNextFree;
|
|
S32 mReclaimedBytes;
|
|
|
|
private:
|
|
/**
|
|
* @brief Helper method to allocate a buffer and correctly set
|
|
* intertnal state of this buffer.
|
|
*/
|
|
void allocate(S32 size);
|
|
};
|
|
|
|
/**
|
|
* @class LLBufferArray
|
|
* @brief Class to represent scattered memory buffers and in-order segments
|
|
* of that buffered data.
|
|
*
|
|
* *NOTE: This class needs to have an iovec interface
|
|
*/
|
|
class LLBufferArray
|
|
{
|
|
public:
|
|
typedef std::vector<LLBuffer*> buffer_list_t;
|
|
typedef buffer_list_t::iterator buffer_iterator_t;
|
|
typedef buffer_list_t::const_iterator const_buffer_iterator_t;
|
|
typedef std::list<LLSegment> segment_list_t;
|
|
typedef segment_list_t::const_iterator const_segment_iterator_t;
|
|
typedef segment_list_t::iterator segment_iterator_t;
|
|
enum { npos = 0xffffffff };
|
|
|
|
LLBufferArray();
|
|
~LLBufferArray();
|
|
|
|
/* @name Channel methods
|
|
*/
|
|
//@{
|
|
/**
|
|
* @brief Generate the a channel descriptor which consumes the
|
|
* output for the channel passed in.
|
|
*/
|
|
static LLChannelDescriptors makeChannelConsumer(
|
|
const LLChannelDescriptors& channels);
|
|
|
|
/**
|
|
* @brief Generate the next channel descriptor for this buffer array.
|
|
*
|
|
* The channel descriptor interface is how the buffer array
|
|
* clients can know where to read and write data. Use this
|
|
* interface to get the 'next' channel set for usage. This is a
|
|
* bit of a simple hack until it's utility indicates it should be
|
|
* extended.
|
|
* @return Returns a valid channel descriptor set for input and output.
|
|
*/
|
|
LLChannelDescriptors nextChannel();
|
|
//@}
|
|
|
|
/* @name Data methods
|
|
*/
|
|
//@{
|
|
|
|
/**
|
|
* @brief Return the sum of all allocated bytes.
|
|
*/
|
|
S32 capacity() const;
|
|
|
|
// These methods will be useful once there is any kind of buffer
|
|
// besides a heap buffer.
|
|
//bool append(EBufferChannel channel, LLBuffer* data);
|
|
//bool prepend(EBufferChannel channel, LLBuffer* data);
|
|
//bool insertAfter(
|
|
// segment_iterator_t segment,
|
|
// EBufferChannel channel,
|
|
// LLBuffer* data);
|
|
|
|
/**
|
|
* @brief Put data on a channel at the end of this buffer array.
|
|
*
|
|
* The data is copied from src into the buffer array. At least one
|
|
* new segment is created and put on the end of the array. This
|
|
* object will internally allocate new buffers if necessary.
|
|
* @param channel The channel for this data
|
|
* @param src The start of memory for the data to be copied
|
|
* @param len The number of bytes of data to copy
|
|
* @return Returns true if the method worked.
|
|
*/
|
|
bool append(S32 channel, const U8* src, S32 len);
|
|
|
|
/**
|
|
* @brief Put data on a channel at the front of this buffer array.
|
|
*
|
|
* The data is copied from src into the buffer array. At least one
|
|
* new segment is created and put in the front of the array. This
|
|
* object will internally allocate new buffers if necessary.
|
|
* @param channel The channel for this data
|
|
* @param src The start of memory for the data to be copied
|
|
* @param len The number of bytes of data to copy
|
|
* @return Returns true if the method worked.
|
|
*/
|
|
bool prepend(S32 channel, const U8* src, S32 len);
|
|
|
|
/**
|
|
* @brief Insert data into a buffer array after a particular segment.
|
|
*
|
|
* The data is copied from src into the buffer array. At least one
|
|
* new segment is created and put in the array. This object will
|
|
* internally allocate new buffers if necessary.
|
|
* @param segment The segment in front of the new segments location
|
|
* @param channel The channel for this data
|
|
* @param src The start of memory for the data to be copied
|
|
* @param len The number of bytes of data to copy
|
|
* @return Returns true if the method worked.
|
|
*/
|
|
bool insertAfter(
|
|
segment_iterator_t segment,
|
|
S32 channel,
|
|
const U8* src,
|
|
S32 len);
|
|
|
|
/**
|
|
* @brief Count bytes in the buffer array on the specified channel
|
|
*
|
|
* @param channel The channel to count.
|
|
* @param start The start address in the array for counting. You
|
|
* can specify NULL to start at the beginning.
|
|
* @return Returns the number of bytes in the channel after start
|
|
*/
|
|
S32 countAfter(S32 channel, U8* start) const;
|
|
|
|
/**
|
|
* @brief Count all bytes on channel.
|
|
*
|
|
* Helper method which just calls countAfter().
|
|
* @param channel The channel to count.
|
|
* @return Returns the number of bytes in the channel.
|
|
*/
|
|
S32 count(S32 channel) const
|
|
{
|
|
return countAfter(channel, NULL);
|
|
}
|
|
|
|
/**
|
|
* @brief Read bytes in the buffer array on the specified channel
|
|
*
|
|
* You should prefer iterating over segments is possible since
|
|
* this method requires you to allocate large buffers - precisely
|
|
* what this class is trying to prevent. This method will skip
|
|
* any segments which are not on the given channel, so this method
|
|
* would usually be used to read a channel and copy that to a log
|
|
* or a socket buffer or something.
|
|
* @param channel The channel to read.
|
|
* @param start The start address in the array for reading. You
|
|
* can specify NULL to start at the beginning.
|
|
* @param dest The destination of the data read. This must be at
|
|
* least len bytes long.
|
|
* @param len[in,out] <b>in</b> How many bytes to read. <b>out</b> How
|
|
* many bytes were read.
|
|
* @return Returns the address of the last read byte.
|
|
*/
|
|
U8* readAfter(S32 channel, U8* start, U8* dest, S32& len) const;
|
|
|
|
/**
|
|
* @brief Find an address in a buffer array
|
|
*
|
|
* @param channel The channel to seek in.
|
|
* @param start The start address in the array for the seek
|
|
* operation. You can specify NULL to start the seek at the
|
|
* beginning, or pass in npos to start at the end.
|
|
* @param delta How many bytes to seek through the array.
|
|
* @return Returns the address of the last read byte.
|
|
*/
|
|
U8* seek(S32 channel, U8* start, S32 delta) const;
|
|
//@}
|
|
|
|
/* @name Buffer interaction
|
|
*/
|
|
//@{
|
|
/**
|
|
* @brief Take the contents of another buffer array
|
|
*
|
|
* This method simply strips the contents out of the source
|
|
* buffery array - segments, buffers, etc, and appends them to
|
|
* this instance. After this operation, the source is empty and
|
|
* ready for reuse.
|
|
* @param source The source buffer
|
|
* @return Returns true if the operation succeeded.
|
|
*/
|
|
bool takeContents(LLBufferArray& source);
|
|
//@}
|
|
|
|
/* @name Segment methods
|
|
*/
|
|
//@{
|
|
/**
|
|
* @brief Split a segments so that address is the last address of
|
|
* one segment, and the rest of the original segment becomes
|
|
* another segment on the same channel.
|
|
*
|
|
* After this method call,
|
|
* <code>getLastSegmentAddress(*getSegment(address)) ==
|
|
* address</code> should be true. This call will only create a new
|
|
* segment if the statement above is false before the call. Since
|
|
* you usually call splitAfter() to change a segment property, use
|
|
* getSegment() to perform those operations.
|
|
* @param address The address which will become the last address
|
|
* of the segment it is in.
|
|
* @return Returns an iterator to the segment which contains
|
|
* <code>address</code> which is <code>endSegment()</code> on
|
|
* failure.
|
|
*/
|
|
segment_iterator_t splitAfter(U8* address);
|
|
|
|
/**
|
|
* @brief Get the first segment in the buffer array.
|
|
*
|
|
* @return Returns the segment if there is one.
|
|
*/
|
|
segment_iterator_t beginSegment();
|
|
|
|
/**
|
|
* @brief Get the one-past-the-end segment in the buffer array
|
|
*
|
|
* @return Returns the iterator for an invalid segment location.
|
|
*/
|
|
segment_iterator_t endSegment();
|
|
|
|
/**
|
|
* @brief Get the segment which holds the given address.
|
|
*
|
|
* As opposed to some methods, passing a NULL will result in
|
|
* returning the end segment.
|
|
* @param address An address in the middle of the sought segment.
|
|
* @return Returns the iterator for the segment or endSegment() on
|
|
* failure.
|
|
*/
|
|
const_segment_iterator_t getSegment(U8* address) const;
|
|
|
|
/**
|
|
* @brief Get the segment which holds the given address.
|
|
*
|
|
* As opposed to some methods, passing a NULL will result in
|
|
* returning the end segment.
|
|
* @param address An address in the middle of the sought segment.
|
|
* @return Returns the iterator for the segment or endSegment() on
|
|
* failure.
|
|
*/
|
|
segment_iterator_t getSegment(U8* address);
|
|
|
|
/**
|
|
* @brief Get a segment iterator after address, and a constructed
|
|
* segment to represent the next linear block of memory.
|
|
*
|
|
* This method is a helper by giving you the largest segment
|
|
* possible in the out-value param after the address provided. The
|
|
* iterator will be useful for iteration, while the segment can be
|
|
* used for direct access to memory after address if the return
|
|
* values isnot end. Passing in NULL will return beginSegment()
|
|
* which may be endSegment(). The segment returned will only be
|
|
* zero length if the return value equals end.
|
|
* This is really just a helper method, since all the information
|
|
* returned could be constructed through other methods.
|
|
* @param address An address in the middle of the sought segment.
|
|
* @param segment[out] segment to be used for reading or writing
|
|
* @return Returns an iterator which contains at least segment or
|
|
* endSegment() on failure.
|
|
*/
|
|
segment_iterator_t constructSegmentAfter(U8* address, LLSegment& segment);
|
|
|
|
/**
|
|
* @brief Make a new segment at the end of buffer array
|
|
*
|
|
* This method will attempt to create a new and empty segment of
|
|
* the specified length. The segment created may be shorter than
|
|
* requested.
|
|
* @param channel[in] The channel for the newly created segment.
|
|
* @param length[in] The requested length of the segment.
|
|
* @return Returns an iterator which contains at least segment or
|
|
* endSegment() on failure.
|
|
*/
|
|
segment_iterator_t makeSegment(S32 channel, S32 length);
|
|
|
|
/**
|
|
* @brief Erase the segment if it is in the buffer array.
|
|
*
|
|
* @param iter An iterator referring to the segment to erase.
|
|
* @return Returns true on success.
|
|
*/
|
|
bool eraseSegment(const segment_iterator_t& iter);
|
|
|
|
/**
|
|
* @brief Lock the mutex if it exists
|
|
* This method locks mMutexp to make accessing LLBufferArray thread-safe
|
|
*/
|
|
void lock();
|
|
|
|
/**
|
|
* @brief Unlock the mutex if it exists
|
|
*/
|
|
void unlock();
|
|
|
|
/**
|
|
* @brief Return mMutexp
|
|
*/
|
|
LLMutex* getMutex();
|
|
|
|
/**
|
|
* @brief Set LLBufferArray to be shared across threads or not
|
|
* This method is to create mMutexp if is threaded.
|
|
* @param threaded Indicates this LLBufferArray instance is shared across threads if true.
|
|
*/
|
|
void setThreaded(bool threaded);
|
|
//@}
|
|
|
|
protected:
|
|
/**
|
|
* @brief Optimally put data in buffers, and reutrn segments.
|
|
*
|
|
* This is an internal function used to create buffers as
|
|
* necessary, and sequence the segments appropriately for the
|
|
* various ways to copy data from src into this.
|
|
* If this method fails, it may actually leak some space inside
|
|
* buffers, but I am not too worried about the slim possibility
|
|
* that we may have some 'dead' space which will be recovered when
|
|
* the buffer (which we will not lose) is deleted. Addressing this
|
|
* weakness will make the buffers almost as complex as a general
|
|
* memory management system.
|
|
* @param channel The channel for this data
|
|
* @param src The start of memory for the data to be copied
|
|
* @param len The number of bytes of data to copy
|
|
* @param segments Out-value for the segments created.
|
|
* @return Returns true if the method worked.
|
|
*/
|
|
bool copyIntoBuffers(
|
|
S32 channel,
|
|
const U8* src,
|
|
S32 len,
|
|
std::vector<LLSegment>& segments);
|
|
|
|
protected:
|
|
S32 mNextBaseChannel;
|
|
buffer_list_t mBuffers;
|
|
segment_list_t mSegments;
|
|
LLMutex* mMutexp;
|
|
};
|
|
|
|
#endif // LL_LLBUFFER_H
|