/* vim:set ts=2 sw=2 sts=2 et cindent: *//* 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/. */#if !defined(MediaResource_h_)# define MediaResource_h_# include "DecoderDoctorLogger.h"# include "Intervals.h"# include "MediaData.h"# include "mozilla/Attributes.h"# include "mozilla/GuardObjects.h"# include "mozilla/UniquePtr.h"# include "nsISeekableStream.h"# include "nsThreadUtils.h"namespace mozilla {
// Represents a section of contiguous media, with a start and end offset.// Used to denote ranges of data which are cached.typedef media::Interval<int64_t> MediaByteRange;
typedef media::IntervalSet<int64_t> MediaByteRangeSet;
DDLoggedTypeDeclName(MediaResource);
/**
* Provides a thread-safe, seek/read interface to resources
* loaded from a URI. Uses MediaCache to cache data received over
* Necko's async channel API, thus resolving the mismatch between clients
* that need efficient random access to the data and protocols that do not
* support efficient random access, such as HTTP.
*
* Instances of this class must be created on the main thread.
* Most methods must be called on the main thread only. Read, Seek and
* Tell must only be called on non-main threads. In the case of the Ogg
* Decoder they are called on the Decode thread for example. You must
* ensure that no threads are calling these methods once Close is called.
*
* Instances of this class are reference counted. Use nsRefPtr for
* managing the lifetime of instances of this class.
*
* The generic implementation of this class is ChannelMediaResource, which can
* handle any URI for which Necko supports AsyncOpen.
* The 'file:' protocol can be implemented efficiently with direct random
* access, so the FileMediaResource implementation class bypasses the cache.
* For cross-process blob URL, CloneableWithRangeMediaResource is used.
* MediaResource::Create automatically chooses the best implementation class.
*/class MediaResource : public DecoderDoctorLifeLogger<MediaResource> {
public:
// Our refcounting is threadsafe, and when our refcount drops to zero// we dispatch an event to the main thread to delete the MediaResource.// Note that this means it's safe for references to this object to be// released on a non main thread, but the destructor will always run on// the main thread. NS_METHOD_(MozExternalRefCountType) AddRef(void);
NS_METHOD_(MozExternalRefCountType) Release(void);
// Close the resource, stop any listeners, channels, etc.// Cancels any currently blocking Read request and forces that request to// return an error.virtual nsresult Close() { return NS_OK; }
// These methods are called off the main thread.// Read up to aCount bytes from the stream. The read starts at// aOffset in the stream, seeking to that location initially if// it is not the current stream offset. The remaining arguments,// results and requirements are the same as per the Read method.virtual nsresult ReadAt(int64_t aOffset, char* aBuffer, uint32_t aCount,
uint32_t* aBytes) = 0;
// Indicate whether caching data in advance of reads is worth it.// E.g. Caching lockless and memory-based MediaResource subclasses would be a// waste, but caching lock/IO-bound resources means reducing the impact of// each read.virtualbool ShouldCacheReads() = 0;
// These can be called on any thread.// Cached blocks associated with this stream will not be evicted// while the stream is pinned.virtualvoid Pin() = 0;
virtualvoid Unpin() = 0;
// Get the length of the stream in bytes. Returns -1 if not known.// This can change over time; after a seek operation, a misbehaving// server may give us a resource of a different length to what it had// reported previously --- or it may just lie in its Content-Length// header and give us more or less data than it reported. We will adjust// the result of GetLength to reflect the data that's actually arriving.virtualint64_t GetLength() = 0;
// Returns the offset of the first byte of cached data at or after aOffset,// or -1 if there is no such cached data.virtualint64_t GetNextCachedData(int64_t aOffset) = 0;
// Returns the end of the bytes starting at the given offset which are in// cache. Returns aOffset itself if there are zero bytes available there.virtualint64_t GetCachedDataEnd(int64_t aOffset) = 0;
// Returns true if all the data from aOffset to the end of the stream// is in cache. If the end of the stream is not known, we return false.virtualbool IsDataCachedToEndOfResource(int64_t aOffset) = 0;
// Reads only data which is cached in the media cache. If you try to read// any data which overlaps uncached data, or if aCount bytes otherwise can't// be read, this function will return failure. This function be called from// any thread, and it is the only read operation which is safe to call on// the main thread, since it's guaranteed to be non blocking.virtual nsresult ReadFromCache(char* aBuffer, int64_t aOffset,
uint32_t aCount) = 0;
/**
* Fills aRanges with MediaByteRanges representing the data which is cached
* in the media cache. Stream should be pinned during call and while
* aRanges is being used.
*/virtual nsresult GetCachedRanges(MediaByteRangeSet& aRanges) = 0;
protected:
virtual ~MediaResource(){};
private:
void Destroy();
mozilla::ThreadSafeAutoRefCnt mRefCnt;
NS_DECL_OWNINGTHREAD
};
/**
* RAII class that handles pinning and unpinning for MediaResource and derived.
* This should be used when making calculations that involve potentially-cached
* MediaResource data, so that the state of the world can't change out from
* under us.
*/template <class T>
class MOZ_RAII AutoPinned {
public:
explicit AutoPinned(T* aResource MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
: mResource(aResource) {
MOZ_GUARD_OBJECT_NOTIFIER_INIT;
MOZ_ASSERT(mResource);
mResource->Pin();
}
~AutoPinned() { mResource->Unpin(); }
operator T*() const { return mResource; }
T* operator->() const MOZ_NO_ADDREF_RELEASE_ON_RETURN { return mResource; }
private:
T* mResource;
MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER
};
DDLoggedTypeDeclName(MediaResourceIndex);
/*
* MediaResourceIndex provides a way to access MediaResource objects.
* Read, Seek and Tell must only be called on non-main threads.
* In the case of the Ogg Decoder they are called on the Decode thread for
* example. You must ensure that no threads are calling these methods once
* the MediaResource has been Closed.
*/class MediaResourceIndex : public DecoderDoctorLifeLogger<MediaResourceIndex> {
public:
explicit MediaResourceIndex(MediaResource* aResource);
// Read up to aCount bytes from the stream. The buffer must have// enough room for at least aCount bytes. Stores the number of// actual bytes read in aBytes (0 on end of file).// May read less than aCount bytes if the number of// available bytes is less than aCount. Always check *aBytes after// read, and call again if necessary. nsresult Read(char* aBuffer, uint32_t aCount, uint32_t* aBytes);
// Seek to the given bytes offset in the stream. aWhence can be// one of:// nsISeekableStream::NS_SEEK_SET// nsISeekableStream::NS_SEEK_CUR// nsISeekableStream::NS_SEEK_END//// In the Http strategy case the cancel will cause the http// channel's listener to close the pipe, forcing an i/o error on any// blocked read. This will allow the decode thread to complete the// event.//// In the case of a seek in progress, the byte range request creates// a new listener. This is done on the main thread via seek// synchronously dispatching an event. This avoids the issue of us// closing the listener but an outstanding byte range request// creating a new one. They run on the same thread so no explicit// synchronisation is required. The byte range request checks for// the cancel flag and does not create a new channel or listener if// we are cancelling.//// The default strategy does not do any seeking - the only issue is// a blocked read which it handles by causing the listener to close// the pipe, as per the http case.//// The file strategy doesn't block for any great length of time so// is fine for a no-op cancel. nsresult Seek(int32_t aWhence, int64_t aOffset);
// Report the current offset in bytes from the start of the stream.int64_t Tell() const { return mOffset; }
// Return the underlying MediaResource. MediaResource* GetResource() const { return mResource; }
// Read up to aCount bytes from the stream. The read starts at// aOffset in the stream, seeking to that location initially if// it is not the current stream offset.// Unlike MediaResource::ReadAt, ReadAt only returns fewer bytes than// requested if end of stream or an error is encountered. There is no need to// call it again to get more data.// If the resource has cached data past the end of the request, it will be// used to fill a local cache, which should speed up consecutive ReadAt's// (mostly by avoiding using the resource's IOs and locks.)// *aBytes will contain the number of bytes copied, even if an error occurred.// ReadAt doesn't have an impact on the offset returned by Tell(). nsresult ReadAt(int64_t aOffset, char* aBuffer, uint32_t aCount,
uint32_t* aBytes);
// Same as ReadAt, but doesn't try to cache around the read.// Useful if you know that you will not read again from the same area. nsresult UncachedReadAt(int64_t aOffset, char* aBuffer, uint32_t aCount,
uint32_t* aBytes) const;
// Similar to ReadAt, but doesn't try to cache around the read.// Useful if you know that you will not read again from the same area.// Will attempt to read aRequestedCount+aExtraCount, repeatedly calling// MediaResource/ ReadAt()'s until a read returns 0 bytes (so we may actually// get less than aRequestedCount bytes), or until we get at least// aRequestedCount bytes (so we may not get any/all of the aExtraCount bytes.) nsresult UncachedRangedReadAt(int64_t aOffset, char* aBuffer,
uint32_t aRequestedCount, uint32_t aExtraCount,
uint32_t* aBytes) const;
// This method returns nullptr if anything fails.// Otherwise, it returns an owned buffer.// MediaReadAt may return fewer bytes than requested if end of stream is// encountered. There is no need to call it again to get more data.// Note this method will not update mOffset. already_AddRefed<MediaByteBuffer> MediaReadAt(int64_t aOffset,
uint32_t aCount) const;
already_AddRefed<MediaByteBuffer> CachedMediaReadAt(int64_t aOffset,
uint32_t aCount) const;
// Get the length of the stream in bytes. Returns -1 if not known.// This can change over time; after a seek operation, a misbehaving// server may give us a resource of a different length to what it had// reported previously --- or it may just lie in its Content-Length// header and give us more or less data than it reported. We will adjust// the result of GetLength to reflect the data that's actually arriving.int64_t GetLength() const;
private:
// If the resource has cached data past the requested range, try to grab it// into our local cache.// If there is no cached data, or attempting to read it fails, fallback on// a (potentially-blocking) read of just what was requested, so that we don't// get unexpected side-effects by trying to read more than intended. nsresult CacheOrReadAt(int64_t aOffset, char* aBuffer, uint32_t aCount,
uint32_t* aBytes);
// Maps a file offset to a mCachedBlock index.uint32_t IndexInCache(int64_t aOffsetInFile) const;
// Starting file offset of the cache block that contains a given file offset.int64_t CacheOffsetContaining(int64_t aOffsetInFile) const;
RefPtr<MediaResource> mResource;
int64_t mOffset;
// Local cache used by ReadAt().// mCachedBlock is valid when mCachedBytes != 0, in which case it contains// data of length mCachedBytes, starting at offset `mCachedOffset` in the// resource, located at index `IndexInCache(mCachedOffset)` in mCachedBlock.//// resource: |------------------------------------------------------|// <----------> mCacheBlockSize// <---------------------------------> mCachedOffset// <--> mCachedBytes// mCachedBlock: |..----....|// CacheOffsetContaining(mCachedOffset) <--> IndexInCache(mCachedOffset)// <------------------------------>constuint32_t mCacheBlockSize;
int64_t mCachedOffset;
uint32_t mCachedBytes;
UniquePtr<char[]> mCachedBlock;
};
} // namespace mozilla#endif