dom/media/MediaBlockCacheBase.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   5  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef MEDIA_BLOCK_CACHE_BASE_H_
   8 #define MEDIA_BLOCK_CACHE_BASE_H_
   9
  10 #include "MediaCache.h"
  11 #include "mozilla/Span.h"
  12
  13 namespace mozilla {
  14
  15 // Manages block management for the media cache. Data comes in over the network
  16 // via callbacks on the main thread, however we don't want to write the
  17 // incoming data to the media cache on the main thread, as this could block
  18 // causing UI jank.
  19 //
  20 // So MediaBlockCacheBase provides an abstraction for a temporary memory buffer
  21 // or file accessible as an array of blocks, which supports a block move
  22 // operation, and allows synchronous reading and writing from any thread, with
  23 // writes being buffered as needed so as not to block.
  24 //
  25 // Writes and cache block moves (which require reading) may be deferred to
  26 // their own non-main thread. This object also ensures that data which has
  27 // been scheduled to be written, but hasn't actually *been* written, is read
  28 // as if it had, i.e. pending writes are cached in readable memory until
  29 // they're flushed to file.
  30 //
  31 // To improve efficiency, writes can only be done at block granularity,
  32 // whereas reads can be done with byte granularity.
  33 //
  34 // Note it's also recommended not to read from the media cache from the main
  35 // thread to prevent jank.
  36 class MediaBlockCacheBase {
  37  public:
  38   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(MediaBlockCacheBase)
  39
  40   static_assert(
  41       MediaCacheStream::BLOCK_SIZE <
  42           static_cast<
  43               std::remove_const<decltype(MediaCacheStream::BLOCK_SIZE)>::type>(
  44               INT32_MAX),
  45       "MediaCacheStream::BLOCK_SIZE should fit in 31 bits");
  46   static const int32_t BLOCK_SIZE = MediaCacheStream::BLOCK_SIZE;
  47
  48  protected:
  49   virtual ~MediaBlockCacheBase() = default;
  50
  51  public:
  52   // Initialize this cache.
  53   virtual nsresult Init() = 0;
  54
  55   // Erase data and discard pending changes to reset the cache to its pristine
  56   // state as it was after Init().
  57   virtual void Flush() = 0;
  58
  59   // Maximum number of blocks expected in this block cache. (But allow overflow
  60   // to accomodate incoming traffic before MediaCache can handle it.)
  61   virtual size_t GetMaxBlocks(size_t aCacheSizeInKiB) const = 0;
  62
  63   // Can be called on any thread. This defers to a non-main thread.
  64   virtual nsresult WriteBlock(uint32_t aBlockIndex, Span<const uint8_t> aData1,
  65                               Span<const uint8_t> aData2) = 0;
  66
  67   // Synchronously reads data from file. May read from file or memory
  68   // depending on whether written blocks have been flushed to file yet.
  69   // Not recommended to be called from the main thread, as can cause jank.
  70   virtual nsresult Read(int64_t aOffset, uint8_t* aData, int32_t aLength,
  71                         int32_t* aBytes) = 0;
  72
  73   // Moves a block asynchronously. Can be called on any thread.
  74   // This defers file I/O to a non-main thread.
  75   virtual nsresult MoveBlock(int32_t aSourceBlockIndex,
  76                              int32_t aDestBlockIndex) = 0;
  77 };
  78
  79 }  // End namespace mozilla.
  80
  81 #endif /* MEDIA_BLOCK_CACHE_BASE_H_ */