Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 283 insertions, 0 deletions

diff --git a/dom/media/MediaResource.h b/dom/media/MediaResource.h
new file mode 100644
index 0000000000..223340b876
--- /dev/null
+++ b/dom/media/MediaResource.h
@@ -0,0 +1,283 @@
+/* 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. 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.
+  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 (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)
+  //           <------------------------------>
+  const uint32_t mCacheBlockSize;
+  int64_t mCachedOffset;
+  uint32_t mCachedBytes;
+  UniquePtr<char[]> mCachedBlock;
+};
+
+}  // namespace mozilla
+
+#endif