tor-browser

MediaResource.h (13427B)

---

/* 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/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_INLINE_DECL_THREADSAFE_REFCOUNTING_WITH_DELETE_ON_MAIN_THREAD(
     MediaResource)

 // Close the resource, stop any listeners, channels, etc.
 // Cancels any currently blocking Read request and forces that request to
 // return an error. This must be called (and resolve) before the MediaResource
 // is deleted.
 virtual RefPtr<GenericPromise> Close() {
   return GenericPromise::CreateAndResolve(true, __func__);
 }

 // 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.
 // On success, *aBytes returns the number of bytes that were actually read.
 // This can be less than aCount on end of stream or when remaining bytes will
 // not be available because a network error has occurred.
 // This will block until the data is available or the stream is closed.
 // For most resources, this will block until the data is available or the
 // stream is closed.
 // The exception is SourceBufferResource, which will return
 // NS_ERROR_DOM_MEDIA_WAITING_FOR_DATA if aCount bytes are not available to
 // read.
 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.
 virtual bool ShouldCacheReads() = 0;

 // These can be called on any thread.
 // Cached blocks associated with this stream will not be evicted
 // while the stream is pinned.
 virtual void Pin() = 0;
 virtual void 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.
 virtual int64_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.
 virtual int64_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.
 virtual int64_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.
 virtual bool 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() = default;
};

/**
* 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) : mResource(aResource) {
   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;
};

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. This can be less than aCount on end
 // of stream or error.
 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.
 // 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)
 //           <------------------------------>
 const uint32_t mCacheBlockSize;
 int64_t mCachedOffset;
 uint32_t mCachedBytes;
 UniquePtr<char[]> mCachedBlock;
};

}  // namespace mozilla

#endif