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/. */
7 /* Various simple compression/decompression functions. */
9 #ifndef mozilla_Compression_h_
10 #define mozilla_Compression_h_
12 #include "mozilla/Assertions.h"
13 #include "mozilla/Types.h"
14 #include "mozilla/Result.h"
15 #include "mozilla/Span.h"
16 #include "mozilla/UniquePtr.h"
18 struct LZ4F_cctx_s
; // compression context
19 struct LZ4F_dctx_s
; // decompression context
22 namespace Compression
{
25 * LZ4 is a very fast byte-wise compression algorithm.
27 * Compared to Google's Snappy it is faster to compress and decompress and
28 * generally produces output of about the same size.
30 * Compared to zlib it compresses at about 10x the speed, decompresses at about
31 * 4x the speed and produces output of about 1.5x the size.
37 * Compresses |aInputSize| bytes from |aSource| into |aDest|. Destination
38 * buffer must be already allocated, and must be sized to handle worst cases
39 * situations (input data not compressible). Worst case size evaluation is
40 * provided by function maxCompressedSize()
42 * @param aInputSize is the input size. Max supported value is ~1.9GB
43 * @return the number of bytes written in buffer |aDest|
45 static MFBT_API
size_t compress(const char* aSource
, size_t aInputSize
,
49 * Compress |aInputSize| bytes from |aSource| into an output buffer
50 * |aDest| of maximum size |aMaxOutputSize|. If it cannot achieve it,
51 * compression will stop, and result of the function will be zero,
52 * |aDest| will still be written to, but since the number of input
53 * bytes consumed is not returned the result is not usable.
55 * This function never writes outside of provided output buffer.
57 * @param aInputSize is the input size. Max supported value is ~1.9GB
58 * @param aMaxOutputSize is the size of the destination buffer (which must
59 * be already allocated)
60 * @return the number of bytes written in buffer |aDest| or 0 if the
63 static MFBT_API
size_t compressLimitedOutput(const char* aSource
,
64 size_t aInputSize
, char* aDest
,
65 size_t aMaxOutputSize
);
68 * If the source stream is malformed, the function will stop decoding
71 * This function never writes outside of provided buffers, and never
72 * modifies input buffer.
74 * Note: destination buffer must be already allocated, and its size must be a
75 * minimum of |aOutputSize| bytes.
77 * @param aOutputSize is the output size, therefore the original size
78 * @return true on success, false on failure
80 static MFBT_API MOZ_MUST_USE
bool decompress(const char* aSource
, char* aDest
,
84 * If the source stream is malformed, the function will stop decoding
87 * This function never writes beyond aDest + aMaxOutputSize, and is
88 * therefore protected against malicious data packets.
90 * Note: Destination buffer must be already allocated. This version is
91 * slightly slower than the decompress without the aMaxOutputSize.
93 * @param aInputSize is the length of the input compressed data
94 * @param aMaxOutputSize is the size of the destination buffer (which must be
96 * @param aOutputSize the actual number of bytes decoded in the destination
97 * buffer (necessarily <= aMaxOutputSize)
98 * @return true on success, false on failure
100 static MFBT_API MOZ_MUST_USE
bool decompress(const char* aSource
,
101 size_t aInputSize
, char* aDest
,
102 size_t aMaxOutputSize
,
103 size_t* aOutputSize
);
106 * If the source stream is malformed, the function will stop decoding
109 * This function never writes beyond aDest + aMaxOutputSize, and is
110 * therefore protected against malicious data packets. It also ignores
111 * unconsumed input upon reaching aMaxOutputSize and can therefore be used
112 * for partial decompression.
114 * Note: Destination buffer must be already allocated. This version is
115 * slightly slower than the decompress without the aMaxOutputSize.
117 * @param aInputSize is the length of the input compressed data
118 * @param aMaxOutputSize is the size of the destination buffer (which must be
120 * @param aOutputSize the actual number of bytes decoded in the destination
121 * buffer (necessarily <= aMaxOutputSize)
122 * @return true on success, false on failure
124 static MFBT_API MOZ_MUST_USE
bool decompressPartial(const char* aSource
,
127 size_t aMaxOutputSize
,
128 size_t* aOutputSize
);
131 * Provides the maximum size that LZ4 may output in a "worst case"
132 * scenario (input data not compressible) primarily useful for memory
133 * allocation of output buffer.
134 * note : this function is limited by "int" range (2^31-1)
136 * @param aInputSize is the input size. Max supported value is ~1.9GB
137 * @return maximum output size in a "worst case" scenario
139 static inline size_t maxCompressedSize(size_t aInputSize
) {
140 size_t max
= (aInputSize
+ (aInputSize
/ 255) + 16);
141 MOZ_ASSERT(max
> aInputSize
);
147 * Context for LZ4 Frame-based streaming compression. Use this if you
148 * want to incrementally compress something or if you want to compress
149 * something such that another application can read it.
151 class LZ4FrameCompressionContext final
{
153 MFBT_API
LZ4FrameCompressionContext(int aCompressionLevel
, size_t aMaxSrcSize
,
154 bool aChecksum
, bool aStableSrc
= false);
156 MFBT_API
~LZ4FrameCompressionContext();
158 size_t GetRequiredWriteBufferLength() { return mWriteBufLen
; }
161 * Begin streaming frame-based compression.
163 * @return a Result with a Span containing the frame header, or an lz4 error
166 MFBT_API Result
<Span
<const char>, size_t> BeginCompressing(
167 Span
<char> aWriteBuffer
);
170 * Continue streaming frame-based compression with the provided input.
172 * @param aInput input buffer to be compressed.
173 * @return a Result with a Span containing compressed output, or an lz4 error
176 MFBT_API Result
<Span
<const char>, size_t> ContinueCompressing(
177 Span
<const char> aInput
);
180 * Finalize streaming frame-based compression with the provided input.
182 * @return a Result with a Span containing compressed output and the frame
183 * footer, or an lz4 error code (size_t).
185 MFBT_API Result
<Span
<const char>, size_t> EndCompressing();
188 LZ4F_cctx_s
* mContext
;
189 int mCompressionLevel
;
190 bool mGenerateChecksum
;
194 Span
<char> mWriteBuffer
;
197 struct LZ4FrameDecompressionResult
{
204 * Context for LZ4 Frame-based streaming decompression. Use this if you
205 * want to decompress something compressed by LZ4FrameCompressionContext
206 * or by another application.
208 class LZ4FrameDecompressionContext final
{
210 explicit MFBT_API
LZ4FrameDecompressionContext(bool aStableDest
= false);
211 MFBT_API
~LZ4FrameDecompressionContext();
214 * Decompress a buffer/part of a buffer compressed with
215 * LZ4FrameCompressionContext or another application.
217 * @param aOutput output buffer to be write results into.
218 * @param aInput input buffer to be decompressed.
219 * @return a Result with information on bytes read/written and whether we
220 * completely decompressed the input into the output, or an lz4 error code
223 MFBT_API Result
<LZ4FrameDecompressionResult
, size_t> Decompress(
224 Span
<char> aOutput
, Span
<const char> aInput
);
227 LZ4F_dctx_s
* mContext
;
231 } /* namespace Compression */
232 } /* namespace mozilla */
234 #endif /* mozilla_Compression_h_ */