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/Types.h"
  13 #include "mozilla/Assertions.h"
  14
  15 namespace mozilla {
  16 namespace Compression {
  17
  18 /**
  19  * LZ4 is a very fast byte-wise compression algorithm.
  20  *
  21  * Compared to Google's Snappy it is faster to compress and decompress and
  22  * generally produces output of about the same size.
  23  *
  24  * Compared to zlib it compresses at about 10x the speed, decompresses at about
  25  * 4x the speed and produces output of about 1.5x the size.
  26  */
  27
  28 class LZ4
  29 {
  30 public:
  31   /**
  32    * Compresses |aInputSize| bytes from |aSource| into |aDest|. Destination
  33    * buffer must be already allocated, and must be sized to handle worst cases
  34    * situations (input data not compressible). Worst case size evaluation is
  35    * provided by function maxCompressedSize()
  36    *
  37    * @param aInputSize is the input size. Max supported value is ~1.9GB
  38    * @return the number of bytes written in buffer |aDest|
  39    */
  40   static MFBT_API size_t
  41   compress(const char* aSource, size_t aInputSize, char* aDest);
  42
  43   /**
  44    * Compress |aInputSize| bytes from |aSource| into an output buffer
  45    * |aDest| of maximum size |aMaxOutputSize|.  If it cannot achieve it,
  46    * compression will stop, and result of the function will be zero,
  47    * |aDest| will still be written to, but since the number of input
  48    * bytes consumed is not returned the result is not usable.
  49    *
  50    * This function never writes outside of provided output buffer.
  51    *
  52    * @param aInputSize is the input size. Max supported value is ~1.9GB
  53    * @param aMaxOutputSize is the size of the destination buffer (which must
  54    *   be already allocated)
  55    * @return the number of bytes written in buffer |aDest| or 0 if the
  56    *   compression fails
  57    */
  58   static MFBT_API size_t
  59   compressLimitedOutput(const char* aSource, size_t aInputSize, char* aDest,
  60                         size_t aMaxOutputSize);
  61
  62   /**
  63    * If the source stream is malformed, the function will stop decoding
  64    * and return a negative result, indicating the byte position of the
  65    * faulty instruction
  66    *
  67    * This function never writes outside of provided buffers, and never
  68    * modifies input buffer.
  69    *
  70    * Note: destination buffer must be already allocated, and its size must be a
  71    *       minimum of |aOutputSize| bytes.
  72    *
  73    * @param aOutputSize is the output size, therefore the original size
  74    * @return the number of bytes read in the source buffer
  75    */
  76   static MFBT_API bool
  77   decompress(const char* aSource, char* aDest, size_t aOutputSize);
  78
  79   /**
  80    * If the source stream is malformed, the function will stop decoding
  81    * and return false.
  82    *
  83    * This function never writes beyond aDest + aMaxOutputSize, and is
  84    * therefore protected against malicious data packets.
  85    *
  86    * Note: Destination buffer must be already allocated.  This version is
  87    *       slightly slower than the decompress without the aMaxOutputSize.
  88    *
  89    * @param aInputSize is the length of the input compressed data
  90    * @param aMaxOutputSize is the size of the destination buffer (which must be
  91    *   already allocated)
  92    * @param aOutputSize the actual number of bytes decoded in the destination
  93    *   buffer (necessarily <= aMaxOutputSize)
  94    */
  95   static MFBT_API bool
  96   decompress(const char* aSource, size_t aInputSize, char* aDest,
  97              size_t aMaxOutputSize, size_t* aOutputSize);
  98
  99   /*
 100    * Provides the maximum size that LZ4 may output in a "worst case"
 101    * scenario (input data not compressible) primarily useful for memory
 102    * allocation of output buffer.
 103    * note : this function is limited by "int" range (2^31-1)
 104    *
 105    * @param aInputSize is the input size. Max supported value is ~1.9GB
 106    * @return maximum output size in a "worst case" scenario
 107    */
 108   static inline size_t maxCompressedSize(size_t aInputSize)
 109   {
 110     size_t max = (aInputSize + (aInputSize / 255) + 16);
 111     MOZ_ASSERT(max > aInputSize);
 112     return max;
 113   }
 114 };
 115
 116 } /* namespace Compression */
 117 } /* namespace mozilla */
 118
 119 #endif /* mozilla_Compression_h_ */