DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Implementation

Mercurial (02464de32c92)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289
/* 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.
  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(){};

 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)
  //           <------------------------------>
  const uint32_t mCacheBlockSize;
  int64_t mCachedOffset;
  uint32_t mCachedBytes;
  UniquePtr<char[]> mCachedBlock;
};

}  // namespace mozilla

#endif