1 | /* |
2 | * Copyright 2017-present 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/compression/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 |
130 | |