Line data    Source code

       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             : 
      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 false.
      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, and its size must be a
      70             :    *       minimum of |aOutputSize| bytes.
      71             :    *
      72             :    * @param aOutputSize is the output size, therefore the original size
      73             :    * @return true on success, false on failure
      74             :    */
      75             :   static MFBT_API MOZ_MUST_USE bool
      76             :   decompress(const char* aSource, char* aDest, size_t aOutputSize);
      77             : 
      78             :   /**
      79             :    * If the source stream is malformed, the function will stop decoding
      80             :    * and return false.
      81             :    *
      82             :    * This function never writes beyond aDest + aMaxOutputSize, and is
      83             :    * therefore protected against malicious data packets.
      84             :    *
      85             :    * Note: Destination buffer must be already allocated.  This version is
      86             :    *       slightly slower than the decompress without the aMaxOutputSize.
      87             :    *
      88             :    * @param aInputSize is the length of the input compressed data
      89             :    * @param aMaxOutputSize is the size of the destination buffer (which must be
      90             :    *   already allocated)
      91             :    * @param aOutputSize the actual number of bytes decoded in the destination
      92             :    *   buffer (necessarily <= aMaxOutputSize)
      93             :    * @return true on success, false on failure
      94             :    */
      95             :   static MFBT_API MOZ_MUST_USE 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           0 :   static inline size_t maxCompressedSize(size_t aInputSize)
     109             :   {
     110           0 :     size_t max = (aInputSize + (aInputSize / 255) + 16);
     111           0 :     MOZ_ASSERT(max > aInputSize);
     112           0 :     return max;
     113             :   }
     114             : };
     115             : 
     116             : } /* namespace Compression */
     117             : } /* namespace mozilla */
     118             : 
     119             : #endif /* mozilla_Compression_h_ */