mozglue/static/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 size_t compress(const char* aSource, size_t aInputSize, char* aDest);
  46
  47   /**
  48    * Compress |aInputSize| bytes from |aSource| into an output buffer
  49    * |aDest| of maximum size |aMaxOutputSize|.  If it cannot achieve it,
  50    * compression will stop, and result of the function will be zero,
  51    * |aDest| will still be written to, but since the number of input
  52    * bytes consumed is not returned the result is not usable.
  53    *
  54    * This function never writes outside of provided output buffer.
  55    *
  56    * @param aInputSize is the input size. Max supported value is ~1.9GB
  57    * @param aMaxOutputSize is the size of the destination buffer (which must
  58    *   be already allocated)
  59    * @return the number of bytes written in buffer |aDest| or 0 if the
  60    *   compression fails
  61    */
  62   static size_t compressLimitedOutput(const char* aSource, size_t aInputSize,
  63                                       char* aDest, size_t aMaxOutputSize);
  64
  65   /**
  66    * If the source stream is malformed, the function will stop decoding
  67    * and return false.
  68    *
  69    * This function never writes beyond aDest + aMaxOutputSize, and is
  70    * therefore protected against malicious data packets.
  71    *
  72    * Note: Destination buffer must be already allocated.  This version is
  73    *       slightly slower than the decompress without the aMaxOutputSize.
  74    *
  75    * @param aInputSize is the length of the input compressed data
  76    * @param aMaxOutputSize is the size of the destination buffer (which must be
  77    *   already allocated)
  78    * @param aOutputSize the actual number of bytes decoded in the destination
  79    *   buffer (necessarily <= aMaxOutputSize)
  80    * @return true on success, false on failure
  81    */
  82   [[nodiscard]] static bool decompress(const char* aSource, size_t aInputSize,
  83                                        char* aDest, size_t aMaxOutputSize,
  84                                        size_t* aOutputSize);
  85
  86   /**
  87    * If the source stream is malformed, the function will stop decoding
  88    * and return false.
  89    *
  90    * This function never writes beyond aDest + aMaxOutputSize, and is
  91    * therefore protected against malicious data packets. It also ignores
  92    * unconsumed input upon reaching aMaxOutputSize and can therefore be used
  93    * for partial decompression.
  94    *
  95    * Note: Destination buffer must be already allocated.  This version is
  96    *       slightly slower than the decompress without the aMaxOutputSize.
  97    *
  98    * @param aInputSize is the length of the input compressed data
  99    * @param aMaxOutputSize is the size of the destination buffer (which must be
 100    *   already allocated)
 101    * @param aOutputSize the actual number of bytes decoded in the destination
 102    *   buffer (necessarily <= aMaxOutputSize)
 103    * @return true on success, false on failure
 104    */
 105   [[nodiscard]] static bool decompressPartial(const char* aSource,
 106                                               size_t aInputSize, char* aDest,
 107                                               size_t aMaxOutputSize,
 108                                               size_t* aOutputSize);
 109
 110   /*
 111    * Provides the maximum size that LZ4 may output in a "worst case"
 112    * scenario (input data not compressible) primarily useful for memory
 113    * allocation of output buffer.
 114    * note : this function is limited by "int" range (2^31-1)
 115    *
 116    * @param aInputSize is the input size. Max supported value is ~1.9GB
 117    * @return maximum output size in a "worst case" scenario
 118    */
 119   static inline size_t maxCompressedSize(size_t aInputSize) {
 120     size_t max = (aInputSize + (aInputSize / 255) + 16);
 121     MOZ_ASSERT(max > aInputSize);
 122     return max;
 123   }
 124 };
 125
 126 /**
 127  * Context for LZ4 Frame-based streaming compression. Use this if you
 128  * want to incrementally compress something or if you want to compress
 129  * something such that another application can read it.
 130  */
 131 class LZ4FrameCompressionContext final {
 132  public:
 133   LZ4FrameCompressionContext(int aCompressionLevel, size_t aMaxSrcSize,
 134                              bool aChecksum, bool aStableSrc = false);
 135
 136   ~LZ4FrameCompressionContext();
 137
 138   size_t GetRequiredWriteBufferLength() { return mWriteBufLen; }
 139
 140   /**
 141    * Begin streaming frame-based compression.
 142    *
 143    * @return a Result with a Span containing the frame header, or an lz4 error
 144    * code (size_t).
 145    */
 146   Result<Span<const char>, size_t> BeginCompressing(Span<char> aWriteBuffer);
 147
 148   /**
 149    * Continue streaming frame-based compression with the provided input.
 150    *
 151    * @param aInput input buffer to be compressed.
 152    * @return a Result with a Span containing compressed output, or an lz4 error
 153    * code (size_t).
 154    */
 155   Result<Span<const char>, size_t> ContinueCompressing(Span<const char> aInput);
 156
 157   /**
 158    * Finalize streaming frame-based compression with the provided input.
 159    *
 160    * @return a Result with a Span containing compressed output and the frame
 161    * footer, or an lz4 error code (size_t).
 162    */
 163   Result<Span<const char>, size_t> EndCompressing();
 164
 165  private:
 166   LZ4F_cctx_s* mContext;
 167   int mCompressionLevel;
 168   bool mGenerateChecksum;
 169   bool mStableSrc;
 170   size_t mMaxSrcSize;
 171   size_t mWriteBufLen;
 172   Span<char> mWriteBuffer;
 173 };
 174
 175 struct LZ4FrameDecompressionResult {
 176   size_t mSizeRead;
 177   size_t mSizeWritten;
 178   bool mFinished;
 179 };
 180
 181 /**
 182  * Context for LZ4 Frame-based streaming decompression. Use this if you
 183  * want to decompress something compressed by LZ4FrameCompressionContext
 184  * or by another application.
 185  */
 186 class LZ4FrameDecompressionContext final {
 187  public:
 188   explicit LZ4FrameDecompressionContext(bool aStableDest = false);
 189   ~LZ4FrameDecompressionContext();
 190
 191   /**
 192    * Decompress a buffer/part of a buffer compressed with
 193    * LZ4FrameCompressionContext or another application.
 194    *
 195    * @param aOutput output buffer to be write results into.
 196    * @param aInput input buffer to be decompressed.
 197    * @return a Result with information on bytes read/written and whether we
 198    * completely decompressed the input into the output, or an lz4 error code
 199    * (size_t).
 200    */
 201   Result<LZ4FrameDecompressionResult, size_t> Decompress(
 202       Span<char> aOutput, Span<const char> aInput);
 203
 204  private:
 205   LZ4F_dctx_s* mContext;
 206   bool mStableDest;
 207 };
 208
 209 } /* namespace Compression */
 210 } /* namespace mozilla */
 211
 212 #endif /* mozilla_Compression_h_ */