mfbt/Compression.h

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