diff options
Diffstat (limited to 'image/SourceBuffer.h')
| -rw-r--r-- | image/SourceBuffer.h | 499 |
1 files changed, 499 insertions, 0 deletions
diff --git a/image/SourceBuffer.h b/image/SourceBuffer.h new file mode 100644 index 0000000000..79188fb882 --- /dev/null +++ b/image/SourceBuffer.h @@ -0,0 +1,499 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +/** + * SourceBuffer is a single producer, multiple consumer data structure used for + * storing image source (compressed) data. + */ + +#ifndef mozilla_image_sourcebuffer_h +#define mozilla_image_sourcebuffer_h + +#include <algorithm> +#include <utility> + +#include "mozilla/Maybe.h" +#include "mozilla/MemoryReporting.h" +#include "mozilla/Mutex.h" +#include "mozilla/RefCounted.h" +#include "mozilla/RefPtr.h" +#include "mozilla/UniquePtr.h" +#include "nsTArray.h" + +class nsIInputStream; + +namespace mozilla { +namespace image { + +class SourceBuffer; + +/** + * IResumable is an interface for classes that can schedule themselves to resume + * their work later. An implementation of IResumable generally should post a + * runnable to some event target which continues the work of the task. + */ +struct IResumable { + MOZ_DECLARE_REFCOUNTED_TYPENAME(IResumable) + + // Subclasses may or may not be XPCOM classes, so we just require that they + // implement AddRef and Release. + NS_INLINE_DECL_PURE_VIRTUAL_REFCOUNTING + + virtual void Resume() = 0; + + protected: + virtual ~IResumable() {} +}; + +/** + * SourceBufferIterator is a class that allows consumers of image source data to + * read the contents of a SourceBuffer sequentially. + * + * Consumers can advance through the SourceBuffer by calling + * AdvanceOrScheduleResume() repeatedly. After every advance, they should call + * check the return value, which will tell them the iterator's new state. + * + * If WAITING is returned, AdvanceOrScheduleResume() has arranged + * to call the consumer's Resume() method later, so the consumer should save its + * state if needed and stop running. + * + * If the iterator's new state is READY, then the consumer can call Data() and + * Length() to read new data from the SourceBuffer. + * + * Finally, in the COMPLETE state the consumer can call CompletionStatus() to + * get the status passed to SourceBuffer::Complete(). + */ +class SourceBufferIterator final { + public: + enum State { + START, // The iterator is at the beginning of the buffer. + READY, // The iterator is pointing to new data. + WAITING, // The iterator is blocked and the caller must yield. + COMPLETE // The iterator is pointing to the end of the buffer. + }; + + explicit SourceBufferIterator(SourceBuffer* aOwner, size_t aReadLimit) + : mOwner(aOwner), + mState(START), + mChunkCount(0), + mByteCount(0), + mRemainderToRead(aReadLimit) { + MOZ_ASSERT(aOwner); + mData.mIterating.mChunk = 0; + mData.mIterating.mData = nullptr; + mData.mIterating.mOffset = 0; + mData.mIterating.mAvailableLength = 0; + mData.mIterating.mNextReadLength = 0; + } + + SourceBufferIterator(SourceBufferIterator&& aOther) + : mOwner(std::move(aOther.mOwner)), + mState(aOther.mState), + mData(aOther.mData), + mChunkCount(aOther.mChunkCount), + mByteCount(aOther.mByteCount), + mRemainderToRead(aOther.mRemainderToRead) {} + + ~SourceBufferIterator(); + + SourceBufferIterator& operator=(SourceBufferIterator&& aOther); + + /** + * Returns true if there are no more than @aBytes remaining in the + * SourceBuffer. If the SourceBuffer is not yet complete, returns false. + */ + bool RemainingBytesIsNoMoreThan(size_t aBytes) const; + + /** + * Advances the iterator through the SourceBuffer if possible. Advances no + * more than @aRequestedBytes bytes. (Use SIZE_MAX to advance as much as + * possible.) + * + * This is a wrapper around AdvanceOrScheduleResume() that makes it clearer at + * the callsite when the no resuming is intended. + * + * @return State::READY if the iterator was successfully advanced. + * State::WAITING if the iterator could not be advanced because it's + * at the end of the underlying SourceBuffer, but the SourceBuffer + * may still receive additional data. + * State::COMPLETE if the iterator could not be advanced because it's + * at the end of the underlying SourceBuffer and the SourceBuffer is + * marked complete (i.e., it will never receive any additional + * data). + */ + State Advance(size_t aRequestedBytes) { + return AdvanceOrScheduleResume(aRequestedBytes, nullptr); + } + + /** + * Advances the iterator through the SourceBuffer if possible. Advances no + * more than @aRequestedBytes bytes. (Use SIZE_MAX to advance as much as + * possible.) If advancing is not possible and @aConsumer is not null, + * arranges to call the @aConsumer's Resume() method when more data is + * available. + * + * @return State::READY if the iterator was successfully advanced. + * State::WAITING if the iterator could not be advanced because it's + * at the end of the underlying SourceBuffer, but the SourceBuffer + * may still receive additional data. @aConsumer's Resume() method + * will be called when additional data is available. + * State::COMPLETE if the iterator could not be advanced because it's + * at the end of the underlying SourceBuffer and the SourceBuffer is + * marked complete (i.e., it will never receive any additional + * data). + */ + State AdvanceOrScheduleResume(size_t aRequestedBytes, IResumable* aConsumer); + + /// If at the end, returns the status passed to SourceBuffer::Complete(). + nsresult CompletionStatus() const { + MOZ_ASSERT(mState == COMPLETE, + "Calling CompletionStatus() in the wrong state"); + return mState == COMPLETE ? mData.mAtEnd.mStatus : NS_OK; + } + + /// If we're ready to read, returns a pointer to the new data. + const char* Data() const { + MOZ_ASSERT(mState == READY, "Calling Data() in the wrong state"); + return mState == READY ? mData.mIterating.mData + mData.mIterating.mOffset + : nullptr; + } + + /// If we're ready to read, returns the length of the new data. + size_t Length() const { + MOZ_ASSERT(mState == READY, "Calling Length() in the wrong state"); + return mState == READY ? mData.mIterating.mNextReadLength : 0; + } + + /// If we're ready to read, returns whether or not everything available thus + /// far has been in the same contiguous buffer. + bool IsContiguous() const { + MOZ_ASSERT(mState == READY, "Calling IsContiguous() in the wrong state"); + return mState == READY ? mData.mIterating.mChunk == 0 : false; + } + + /// @return a count of the chunks we've advanced through. + uint32_t ChunkCount() const { return mChunkCount; } + + /// @return a count of the bytes in all chunks we've advanced through. + size_t ByteCount() const { return mByteCount; } + + /// @return the source buffer which owns the iterator. + SourceBuffer* Owner() const { + MOZ_ASSERT(mOwner); + return mOwner; + } + + /// @return the current offset from the beginning of the buffer. + size_t Position() const { + return mByteCount - mData.mIterating.mAvailableLength; + } + + private: + friend class SourceBuffer; + + SourceBufferIterator(const SourceBufferIterator&) = delete; + SourceBufferIterator& operator=(const SourceBufferIterator&) = delete; + + bool HasMore() const { return mState != COMPLETE; } + + State AdvanceFromLocalBuffer(size_t aRequestedBytes) { + MOZ_ASSERT(mState == READY, "Advancing in the wrong state"); + MOZ_ASSERT(mData.mIterating.mAvailableLength > 0, + "The local buffer shouldn't be empty"); + MOZ_ASSERT(mData.mIterating.mNextReadLength == 0, + "Advancing without consuming previous data"); + + mData.mIterating.mNextReadLength = + std::min(mData.mIterating.mAvailableLength, aRequestedBytes); + + return READY; + } + + State SetReady(uint32_t aChunk, const char* aData, size_t aOffset, + size_t aAvailableLength, size_t aRequestedBytes) { + MOZ_ASSERT(mState != COMPLETE); + mState = READY; + + // Prevent the iterator from reporting more data than it is allowed to read. + if (aAvailableLength > mRemainderToRead) { + aAvailableLength = mRemainderToRead; + } + + // Update state. + mData.mIterating.mChunk = aChunk; + mData.mIterating.mData = aData; + mData.mIterating.mOffset = aOffset; + mData.mIterating.mAvailableLength = aAvailableLength; + + // Update metrics. + mChunkCount++; + mByteCount += aAvailableLength; + + // Attempt to advance by the requested number of bytes. + return AdvanceFromLocalBuffer(aRequestedBytes); + } + + State SetWaiting(bool aHasConsumer) { + MOZ_ASSERT(mState != COMPLETE); + // Without a consumer, we won't know when to wake up precisely. Caller + // convention should mean that we don't try to advance unless we have + // written new data, but that doesn't mean we got enough. + MOZ_ASSERT(mState != WAITING || !aHasConsumer, + "Did we get a spurious wakeup somehow?"); + return mState = WAITING; + } + + State SetComplete(nsresult aStatus) { + mData.mAtEnd.mStatus = aStatus; + return mState = COMPLETE; + } + + RefPtr<SourceBuffer> mOwner; + + State mState; + + /** + * This union contains our iteration state if we're still iterating (for + * states START, READY, and WAITING) and the status the SourceBuffer was + * completed with if we're in state COMPLETE. + */ + union { + struct { + uint32_t mChunk; // Index of the chunk in SourceBuffer. + const char* mData; // Pointer to the start of the chunk. + size_t mOffset; // Current read position of the iterator relative to + // mData. + size_t mAvailableLength; // How many bytes remain unread in the chunk, + // relative to mOffset. + size_t + mNextReadLength; // How many bytes the last iterator advance + // requested to be read, so that we know much + // to increase mOffset and reduce mAvailableLength + // by when the next advance is requested. + } mIterating; // Cached info of the chunk currently iterating over. + struct { + nsresult mStatus; // Status code indicating if we read all the data. + } mAtEnd; // State info after iterator is complete. + } mData; + + uint32_t mChunkCount; // Count of chunks observed, including current chunk. + size_t mByteCount; // Count of readable bytes observed, including unread + // bytes from the current chunk. + size_t mRemainderToRead; // Count of bytes left to read if there is a maximum + // imposed by the caller. SIZE_MAX if unlimited. +}; + +/** + * SourceBuffer is a parallel data structure used for storing image source + * (compressed) data. + * + * SourceBuffer is a single producer, multiple consumer data structure. The + * single producer calls Append() to append data to the buffer. In parallel, + * multiple consumers can call Iterator(), which returns a SourceBufferIterator + * that they can use to iterate through the buffer. The SourceBufferIterator + * returns a series of pointers which remain stable for lifetime of the + * SourceBuffer, and the data they point to is immutable, ensuring that the + * producer never interferes with the consumers. + * + * In order to avoid blocking, SourceBuffer works with SourceBufferIterator to + * keep a list of consumers which are waiting for new data, and to resume them + * when the producer appends more. All consumers must implement the IResumable + * interface to make this possible. + */ +class SourceBuffer final { + public: + MOZ_DECLARE_REFCOUNTED_TYPENAME(image::SourceBuffer) + NS_INLINE_DECL_THREADSAFE_REFCOUNTING(image::SourceBuffer) + + SourceBuffer(); + + ////////////////////////////////////////////////////////////////////////////// + // Producer methods. + ////////////////////////////////////////////////////////////////////////////// + + /** + * If the producer knows how long the source data will be, it should call + * ExpectLength, which enables SourceBuffer to preallocate its buffer. + */ + nsresult ExpectLength(size_t aExpectedLength); + + /// Append the provided data to the buffer. + nsresult Append(const char* aData, size_t aLength); + + /// Append the data available on the provided nsIInputStream to the buffer. + nsresult AppendFromInputStream(nsIInputStream* aInputStream, uint32_t aCount); + + /** + * Mark the buffer complete, with a status that will be available to + * consumers. Further calls to Append() are forbidden after Complete(). + */ + void Complete(nsresult aStatus); + + /// Returns true if the buffer is complete. + bool IsComplete(); + + /// Memory reporting. + size_t SizeOfIncludingThisWithComputedFallback(MallocSizeOf) const; + + ////////////////////////////////////////////////////////////////////////////// + // Consumer methods. + ////////////////////////////////////////////////////////////////////////////// + + /** + * Returns an iterator to this SourceBuffer, which cannot read more than the + * given length. + */ + SourceBufferIterator Iterator(size_t aReadLength = SIZE_MAX); + + ////////////////////////////////////////////////////////////////////////////// + // Consumer methods. + ////////////////////////////////////////////////////////////////////////////// + + /** + * The minimum chunk capacity we'll allocate, if we don't know the correct + * capacity (which would happen because ExpectLength() wasn't called or gave + * us the wrong value). This is only exposed for use by tests; if normal code + * is using this, it's doing something wrong. + */ + static const size_t MIN_CHUNK_CAPACITY = 4096; + + /** + * The maximum chunk capacity we'll allocate. This was historically the + * maximum we would preallocate based on the network size. We may adjust it + * in the future based on the IMAGE_DECODE_CHUNKS telemetry to ensure most + * images remain in a single chunk. + */ + static const size_t MAX_CHUNK_CAPACITY = 20 * 1024 * 1024; + + private: + friend class SourceBufferIterator; + + ~SourceBuffer(); + + ////////////////////////////////////////////////////////////////////////////// + // Chunk type and chunk-related methods. + ////////////////////////////////////////////////////////////////////////////// + + class Chunk final { + public: + explicit Chunk(size_t aCapacity) : mCapacity(aCapacity), mLength(0) { + MOZ_ASSERT(aCapacity > 0, "Creating zero-capacity chunk"); + mData = static_cast<char*>(malloc(mCapacity)); + } + + ~Chunk() { free(mData); } + + Chunk(Chunk&& aOther) + : mCapacity(aOther.mCapacity), + mLength(aOther.mLength), + mData(aOther.mData) { + aOther.mCapacity = aOther.mLength = 0; + aOther.mData = nullptr; + } + + Chunk& operator=(Chunk&& aOther) { + free(mData); + mCapacity = aOther.mCapacity; + mLength = aOther.mLength; + mData = aOther.mData; + aOther.mCapacity = aOther.mLength = 0; + aOther.mData = nullptr; + return *this; + } + + bool AllocationFailed() const { return !mData; } + size_t Capacity() const { return mCapacity; } + size_t Length() const { return mLength; } + + char* Data() const { + MOZ_ASSERT(mData, "Allocation failed but nobody checked for it"); + return mData; + } + + void AddLength(size_t aAdditionalLength) { + MOZ_ASSERT(mLength + aAdditionalLength <= mCapacity); + mLength += aAdditionalLength; + } + + bool SetCapacity(size_t aCapacity) { + MOZ_ASSERT(mData, "Allocation failed but nobody checked for it"); + char* data = static_cast<char*>(realloc(mData, aCapacity)); + if (!data) { + return false; + } + + mData = data; + mCapacity = aCapacity; + return true; + } + + private: + Chunk(const Chunk&) = delete; + Chunk& operator=(const Chunk&) = delete; + + size_t mCapacity; + size_t mLength; + char* mData; + }; + + nsresult AppendChunk(Maybe<Chunk>&& aChunk) MOZ_REQUIRES(mMutex); + Maybe<Chunk> CreateChunk(size_t aCapacity, size_t aExistingCapacity = 0, + bool aRoundUp = true); + nsresult Compact() MOZ_REQUIRES(mMutex); + static size_t RoundedUpCapacity(size_t aCapacity); + size_t FibonacciCapacityWithMinimum(size_t aMinCapacity) MOZ_REQUIRES(mMutex); + + ////////////////////////////////////////////////////////////////////////////// + // Iterator / consumer methods. + ////////////////////////////////////////////////////////////////////////////// + + void AddWaitingConsumer(IResumable* aConsumer) MOZ_REQUIRES(mMutex); + void ResumeWaitingConsumers() MOZ_REQUIRES(mMutex); + + typedef SourceBufferIterator::State State; + + State AdvanceIteratorOrScheduleResume(SourceBufferIterator& aIterator, + size_t aRequestedBytes, + IResumable* aConsumer); + bool RemainingBytesIsNoMoreThan(const SourceBufferIterator& aIterator, + size_t aBytes) const; + + void OnIteratorRelease(); + + ////////////////////////////////////////////////////////////////////////////// + // Helper methods. + ////////////////////////////////////////////////////////////////////////////// + + nsresult HandleError(nsresult aError) MOZ_REQUIRES(mMutex); + bool IsEmpty() MOZ_REQUIRES(mMutex); + bool IsLastChunk(uint32_t aChunk) MOZ_REQUIRES(mMutex); + + ////////////////////////////////////////////////////////////////////////////// + // Member variables. + ////////////////////////////////////////////////////////////////////////////// + + /// All private members are protected by mMutex. + mutable Mutex mMutex; + + /// The data in this SourceBuffer, stored as a series of Chunks. + AutoTArray<Chunk, 1> mChunks MOZ_GUARDED_BY(mMutex); + + /// Consumers which are waiting to be notified when new data is available. + nsTArray<RefPtr<IResumable>> mWaitingConsumers MOZ_GUARDED_BY(mMutex); + + /// If present, marks this SourceBuffer complete with the given final status. + Maybe<nsresult> mStatus MOZ_GUARDED_BY(mMutex); + + /// Count of active consumers. + uint32_t mConsumerCount MOZ_GUARDED_BY(mMutex); + + /// True if compacting has been performed. + bool mCompacted MOZ_GUARDED_BY(mMutex); +}; + +} // namespace image +} // namespace mozilla + +#endif // mozilla_image_sourcebuffer_h |