folly/io/Compression.h

   1 /*
   2  * Copyright 2017 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #pragma once
  18
  19 #include <cstdint>
  20 #include <limits>
  21 #include <memory>
  22
  23 #include <folly/io/IOBuf.h>
  24
  25 /**
  26  * Compression / decompression over IOBufs
  27  */
  28
  29 namespace folly { namespace io {
  30
  31 enum class CodecType {
  32   /**
  33    * This codec type is not defined; getCodec() will throw an exception
  34    * if used. Useful if deriving your own classes from Codec without
  35    * going through the getCodec() interface.
  36    */
  37   USER_DEFINED = 0,
  38
  39   /**
  40    * Use no compression.
  41    * Levels supported: 0
  42    */
  43   NO_COMPRESSION = 1,
  44
  45   /**
  46    * Use LZ4 compression.
  47    * Levels supported: 1 = fast, 2 = best; default = 1
  48    */
  49   LZ4 = 2,
  50
  51   /**
  52    * Use Snappy compression.
  53    * Levels supported: 1
  54    */
  55   SNAPPY = 3,
  56
  57   /**
  58    * Use zlib compression.
  59    * Levels supported: 0 = no compression, 1 = fast, ..., 9 = best; default = 6
  60    */
  61   ZLIB = 4,
  62
  63   /**
  64    * Use LZ4 compression, prefixed with size (as Varint).
  65    */
  66   LZ4_VARINT_SIZE = 5,
  67
  68   /**
  69    * Use LZMA2 compression.
  70    * Levels supported: 0 = no compression, 1 = fast, ..., 9 = best; default = 6
  71    */
  72   LZMA2 = 6,
  73   LZMA2_VARINT_SIZE = 7,
  74
  75   /**
  76    * Use ZSTD compression.
  77    */
  78   ZSTD = 8,
  79
  80   /**
  81    * Use gzip compression.  This is the same compression algorithm as ZLIB but
  82    * gzip-compressed files tend to be easier to work with from the command line.
  83    * Levels supported: 0 = no compression, 1 = fast, ..., 9 = best; default = 6
  84    */
  85   GZIP = 9,
  86
  87   NUM_CODEC_TYPES = 10,
  88 };
  89
  90 class Codec {
  91  public:
  92   virtual ~Codec() { }
  93
  94   /**
  95    * Return the maximum length of data that may be compressed with this codec.
  96    * NO_COMPRESSION and ZLIB support arbitrary lengths;
  97    * LZ4 supports up to 1.9GiB; SNAPPY supports up to 4GiB.
  98    * May return UNLIMITED_UNCOMPRESSED_LENGTH if unlimited.
  99    */
 100   uint64_t maxUncompressedLength() const;
 101
 102   /**
 103    * Return the codec's type.
 104    */
 105   CodecType type() const { return type_; }
 106
 107   /**
 108    * Does this codec need the exact uncompressed length on decompression?
 109    */
 110   bool needsUncompressedLength() const;
 111
 112   /**
 113    * Compress data, returning an IOBuf (which may share storage with data).
 114    * Throws std::invalid_argument if data is larger than
 115    * maxUncompressedLength().
 116    *
 117    * Regardless of the behavior of the underlying compressor, compressing
 118    * an empty IOBuf chain will return an empty IOBuf chain.
 119    */
 120   std::unique_ptr<IOBuf> compress(const folly::IOBuf* data);
 121
 122   /**
 123    * Uncompress data. Throws std::runtime_error on decompression error.
 124    *
 125    * Some codecs (LZ4) require the exact uncompressed length; this is indicated
 126    * by needsUncompressedLength().
 127    *
 128    * For other codes (zlib), knowing the exact uncompressed length ahead of
 129    * time might be faster.
 130    *
 131    * Regardless of the behavior of the underlying compressor, uncompressing
 132    * an empty IOBuf chain will return an empty IOBuf chain.
 133    */
 134   static constexpr uint64_t UNKNOWN_UNCOMPRESSED_LENGTH = uint64_t(-1);
 135   static constexpr uint64_t UNLIMITED_UNCOMPRESSED_LENGTH = uint64_t(-2);
 136
 137   std::unique_ptr<IOBuf> uncompress(
 138       const IOBuf* data,
 139       uint64_t uncompressedLength = UNKNOWN_UNCOMPRESSED_LENGTH);
 140
 141  protected:
 142   explicit Codec(CodecType type);
 143
 144  private:
 145   // default: no limits (save for special value UNKNOWN_UNCOMPRESSED_LENGTH)
 146   virtual uint64_t doMaxUncompressedLength() const;
 147   // default: doesn't need uncompressed length
 148   virtual bool doNeedsUncompressedLength() const;
 149   virtual std::unique_ptr<IOBuf> doCompress(const folly::IOBuf* data) = 0;
 150   virtual std::unique_ptr<IOBuf> doUncompress(const folly::IOBuf* data,
 151                                               uint64_t uncompressedLength) = 0;
 152
 153   CodecType type_;
 154 };
 155
 156 constexpr int COMPRESSION_LEVEL_FASTEST = -1;
 157 constexpr int COMPRESSION_LEVEL_DEFAULT = -2;
 158 constexpr int COMPRESSION_LEVEL_BEST = -3;
 159
 160 /**
 161  * Return a codec for the given type. Throws on error.  The level
 162  * is a non-negative codec-dependent integer indicating the level of
 163  * compression desired, or one of the following constants:
 164  *
 165  * COMPRESSION_LEVEL_FASTEST is fastest (uses least CPU / memory,
 166  *   worst compression)
 167  * COMPRESSION_LEVEL_DEFAULT is the default (likely a tradeoff between
 168  *   FASTEST and BEST)
 169  * COMPRESSION_LEVEL_BEST is the best compression (uses most CPU / memory,
 170  *   best compression)
 171  *
 172  * When decompressing, the compression level is ignored. All codecs will
 173  * decompress all data compressed with the a codec of the same type, regardless
 174  * of compression level.
 175  */
 176 std::unique_ptr<Codec> getCodec(CodecType type,
 177                                 int level = COMPRESSION_LEVEL_DEFAULT);
 178
 179 /**
 180  * Check if a specified codec is supported.
 181  */
 182 bool hasCodec(CodecType type);
 183
 184 }}  // namespaces