mfbt/Compression.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   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
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* Various simple compression/decompression functions. */
   8
   9 #ifndef mozilla_Compression_h_
  10 #define mozilla_Compression_h_
  11
  12 #include "mozilla/Assertions.h"
  13 #include "mozilla/Types.h"
  14 #include "mozilla/ResultVariant.h"
  15 #include "mozilla/Span.h"
  16 #include "mozilla/UniquePtr.h"
  17
  18 struct LZ4F_cctx_s;  // compression context
  19 struct LZ4F_dctx_s;  // decompression context
  20
  21 namespace mozilla {
  22 namespace Compression {
  23
  24 /**
  25  * LZ4 is a very fast byte-wise compression algorithm.
  26  *
  27  * Compared to Google's Snappy it is faster to compress and decompress and
  28  * generally produces output of about the same size.
  29  *
  30  * Compared to zlib it compresses at about 10x the speed, decompresses at about
  31  * 4x the speed and produces output of about 1.5x the size.
  32  */
  33
  34 class LZ4 {
  35  public:
  36   /**
  37    * Compresses |aInputSize| bytes from |aSource| into |aDest|. Destination
  38    * buffer must be already allocated, and must be sized to handle worst cases
  39    * situations (input data not compressible). Worst case size evaluation is
  40    * provided by function maxCompressedSize()
  41    *
  42    * @param aInputSize is the input size. Max supported value is ~1.9GB
  43    * @return the number of bytes written in buffer |aDest|
  44    */
  45   static MFBT_API size_t compress(const char* aSource, size_t aInputSize,
  46                                   char* aDest);
  47
  48   /**
  49    * Compress |aInputSize| bytes from |aSource| into an output buffer
  50    * |aDest| of maximum size |aMaxOutputSize|.  If it cannot achieve it,
  51    * compression will stop, and result of the function will be zero,
  52    * |aDest| will still be written to, but since the number of input
  53    * bytes consumed is not returned the result is not usable.
  54    *
  55    * This function never writes outside of provided output buffer.
  56    *
  57    * @param aInputSize is the input size. Max supported value is ~1.9GB
  58    * @param aMaxOutputSize is the size of the destination buffer (which must
  59    *   be already allocated)
  60    * @return the number of bytes written in buffer |aDest| or 0 if the
  61    *   compression fails
  62    */
  63   static MFBT_API size_t compressLimitedOutput(const char* aSource,
  64                                                size_t aInputSize, char* aDest,
  65                                                size_t aMaxOutputSize);
  66
  67   /**
  68    * If the source stream is malformed, the function will stop decoding
  69    * and return false.
  70    *
  71    * This function never writes beyond aDest + aMaxOutputSize, and is
  72    * therefore protected against malicious data packets.
  73    *
  74    * Note: Destination buffer must be already allocated.  This version is
  75    *       slightly slower than the decompress without the aMaxOutputSize.
  76    *
  77    * @param aInputSize is the length of the input compressed data
  78    * @param aMaxOutputSize is the size of the destination buffer (which must be
  79    *   already allocated)
  80    * @param aOutputSize the actual number of bytes decoded in the destination
  81    *   buffer (necessarily <= aMaxOutputSize)
  82    * @return true on success, false on failure
  83    */
  84   [[nodiscard]] static MFBT_API bool decompress(const char* aSource,
  85                                                 size_t aInputSize, char* aDest,
  86                                                 size_t aMaxOutputSize,
  87                                                 size_t* aOutputSize);
  88
  89   /**
  90    * If the source stream is malformed, the function will stop decoding
  91    * and return false.
  92    *
  93    * This function never writes beyond aDest + aMaxOutputSize, and is
  94    * therefore protected against malicious data packets. It also ignores
  95    * unconsumed input upon reaching aMaxOutputSize and can therefore be used
  96    * for partial decompression.
  97    *
  98    * Note: Destination buffer must be already allocated.  This version is
  99    *       slightly slower than the decompress without the aMaxOutputSize.
 100    *
 101    * @param aInputSize is the length of the input compressed data
 102    * @param aMaxOutputSize is the size of the destination buffer (which must be
 103    *   already allocated)
 104    * @param aOutputSize the actual number of bytes decoded in the destination
 105    *   buffer (necessarily <= aMaxOutputSize)
 106    * @return true on success, false on failure
 107    */
 108   [[nodiscard]] static MFBT_API bool decompressPartial(const char* aSource,
 109                                                        size_t aInputSize,
 110                                                        char* aDest,
 111                                                        size_t aMaxOutputSize,
 112                                                        size_t* aOutputSize);
 113
 114   /*
 115    * Provides the maximum size that LZ4 may output in a "worst case"
 116    * scenario (input data not compressible) primarily useful for memory
 117    * allocation of output buffer.
 118    * note : this function is limited by "int" range (2^31-1)
 119    *
 120    * @param aInputSize is the input size. Max supported value is ~1.9GB
 121    * @return maximum output size in a "worst case" scenario
 122    */
 123   static inline size_t maxCompressedSize(size_t aInputSize) {
 124     size_t max = (aInputSize + (aInputSize / 255) + 16);
 125     MOZ_ASSERT(max > aInputSize);
 126     return max;
 127   }
 128 };
 129
 130 /**
 131  * Context for LZ4 Frame-based streaming compression. Use this if you
 132  * want to incrementally compress something or if you want to compress
 133  * something such that another application can read it.
 134  */
 135 class LZ4FrameCompressionContext final {
 136  public:
 137   MFBT_API LZ4FrameCompressionContext(int aCompressionLevel, size_t aMaxSrcSize,
 138                                       bool aChecksum, bool aStableSrc = false);
 139
 140   MFBT_API ~LZ4FrameCompressionContext();
 141
 142   size_t GetRequiredWriteBufferLength() { return mWriteBufLen; }
 143
 144   /**
 145    * Begin streaming frame-based compression.
 146    *
 147    * @return a Result with a Span containing the frame header, or an lz4 error
 148    * code (size_t).
 149    */
 150   MFBT_API Result<Span<const char>, size_t> BeginCompressing(
 151       Span<char> aWriteBuffer);
 152
 153   /**
 154    * Continue streaming frame-based compression with the provided input.
 155    *
 156    * @param aInput input buffer to be compressed.
 157    * @return a Result with a Span containing compressed output, or an lz4 error
 158    * code (size_t).
 159    */
 160   MFBT_API Result<Span<const char>, size_t> ContinueCompressing(
 161       Span<const char> aInput);
 162
 163   /**
 164    * Finalize streaming frame-based compression with the provided input.
 165    *
 166    * @return a Result with a Span containing compressed output and the frame
 167    * footer, or an lz4 error code (size_t).
 168    */
 169   MFBT_API Result<Span<const char>, size_t> EndCompressing();
 170
 171  private:
 172   LZ4F_cctx_s* mContext;
 173   int mCompressionLevel;
 174   bool mGenerateChecksum;
 175   bool mStableSrc;
 176   size_t mMaxSrcSize;
 177   size_t mWriteBufLen;
 178   Span<char> mWriteBuffer;
 179 };
 180
 181 struct LZ4FrameDecompressionResult {
 182   size_t mSizeRead;
 183   size_t mSizeWritten;
 184   bool mFinished;
 185 };
 186
 187 /**
 188  * Context for LZ4 Frame-based streaming decompression. Use this if you
 189  * want to decompress something compressed by LZ4FrameCompressionContext
 190  * or by another application.
 191  */
 192 class LZ4FrameDecompressionContext final {
 193  public:
 194   explicit MFBT_API LZ4FrameDecompressionContext(bool aStableDest = false);
 195   MFBT_API ~LZ4FrameDecompressionContext();
 196
 197   /**
 198    * Decompress a buffer/part of a buffer compressed with
 199    * LZ4FrameCompressionContext or another application.
 200    *
 201    * @param aOutput output buffer to be write results into.
 202    * @param aInput input buffer to be decompressed.
 203    * @return a Result with information on bytes read/written and whether we
 204    * completely decompressed the input into the output, or an lz4 error code
 205    * (size_t).
 206    */
 207   MFBT_API Result<LZ4FrameDecompressionResult, size_t> Decompress(
 208       Span<char> aOutput, Span<const char> aInput);
 209
 210  private:
 211   LZ4F_dctx_s* mContext;
 212   bool mStableDest;
 213 };
 214
 215 } /* namespace Compression */
 216 } /* namespace mozilla */
 217
 218 #endif /* mozilla_Compression_h_ */