folly/io/compression/Zlib.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 <folly/Portability.h>
  20 #include <folly/io/Compression.h>
  21
  22 #if FOLLY_HAVE_LIBZ
  23
  24 #include <zlib.h>
  25
  26 /**
  27  * Interface for Zlib-specific codec initialization.
  28  */
  29 namespace folly {
  30 namespace io {
  31 namespace zlib {
  32
  33 struct Options {
  34   /**
  35    * ZLIB: default option -- write a zlib wrapper as documented in RFC 1950.
  36    *
  37    * GZIP: write a simple gzip header and trailer around the compressed data
  38    * instead of a zlib wrapper.
  39    *
  40    * RAW: deflate will generate raw deflate data with no zlib header or
  41    * trailer, and will not compute a check value.
  42    *
  43    * AUTO: enable automatic header detection for decoding gzip or zlib data.
  44    * For deflation, ZLIB will be used.
  45    */
  46   enum class Format { ZLIB, GZIP, RAW, AUTO };
  47
  48   explicit Options(
  49       Format format = Format::ZLIB,
  50       int windowSize = 15,
  51       int memLevel = 8,
  52       int strategy = Z_DEFAULT_STRATEGY)
  53       : format(format),
  54         windowSize(windowSize),
  55         memLevel(memLevel),
  56         strategy(strategy) {}
  57
  58   Format format;
  59
  60   /**
  61    * windowSize is the base two logarithm of the window size (the size of the
  62    * history buffer). It should be in the range 9..15. Larger values of this
  63    * parameter result in better compression at the expense of memory usage.
  64    *
  65    * The default value is 15.
  66    *
  67    * NB: when inflating/uncompressing data, the windowSize must be greater than
  68    * or equal to the size used when deflating/compressing.
  69    */
  70   int windowSize;
  71
  72   /**
  73    * "The memLevel parameter specifies how much memory should be allocated for
  74    * the internal compression state. memLevel=1 uses minimum memory but is slow
  75    * and reduces compression ratio; memLevel=9 uses maximum memory for optimal
  76    * speed. The default value is 8."
  77    */
  78   int memLevel;
  79
  80   /**
  81    * The strategy parameter is used to tune the compression algorithm.
  82    * Supported values:
  83    * - Z_DEFAULT_STRATEGY: normal data
  84    * - Z_FILTERED: data produced by a filter (or predictor)
  85    * - Z_HUFFMAN_ONLY: force Huffman encoding only (no string match)
  86    * - Z_RLE: limit match distances to one
  87    * - Z_FIXED: prevents the use of dynamic Huffman codes
  88    *
  89    * The strategy parameter only affects the compression ratio but not the
  90    * correctness of the compressed output.
  91    */
  92   int strategy;
  93 };
  94
  95 /**
  96  * Get the default options for gzip compression.
  97  * A codec created with these options will have type CodecType::GZIP.
  98  */
  99 Options defaultGzipOptions();
 100
 101 /**
 102  * Get the default options for zlib compression.
 103  * A codec created with these options will have type CodecType::ZLIB.
 104  */
 105 Options defaultZlibOptions();
 106
 107 /**
 108  * Get a codec with the given options and compression level.
 109  *
 110  * If the windowSize is 15 and the format is Format::ZLIB or Format::GZIP, then
 111  * the type of the codec will be CodecType::ZLIB or CodecType::GZIP
 112  * respectively. Otherwise, the type will be CodecType::USER_DEFINED.
 113  *
 114  * Automatic uncompression is not supported with USER_DEFINED codecs.
 115  *
 116  * Levels supported: 0 = no compression, 1 = fast, ..., 9 = best; default = 6
 117  */
 118 std::unique_ptr<Codec> getCodec(
 119     Options options = Options(),
 120     int level = COMPRESSION_LEVEL_DEFAULT);
 121 std::unique_ptr<StreamCodec> getStreamCodec(
 122     Options options = Options(),
 123     int level = COMPRESSION_LEVEL_DEFAULT);
 124
 125 } // namespace zlib
 126 } // namespace io
 127 } // namespace folly
 128
 129 #endif // FOLLY_HAVE_LIBZ