commit | 5a210a09735ab4af7b0af4a0ec6d6dd09675526a | [log] [tgz] |
---|---|---|
author | Klaus Post <klauspost@gmail.com> | Sun Feb 26 13:36:42 2023 |
committer | GitHub <noreply@github.com> | Sun Feb 26 13:36:42 2023 |
tree | f2928af0cb8bdbf7fb2180fd07d88dbf6f234a0c | |
parent | 0faa2d1017e7eaee601365e4d84f15e14a98623f [diff] |
s2: Add Dictionary support. (#685) # Compression Improvement ## [github_users_sample_set](https://github.com/facebook/zstd/releases/download/v1.1.3/github_users_sample_set.tar.zst) From https://github.com/facebook/zstd/releases/tag/v1.1.3 With 64K dictionary trained with zstd: 9114 files, 7484607 bytes input: Default Compression: 3362023 (44.92%) -> 921524 (12.31%) Better: 3083163 (41.19%) -> 873154 (11.67%) Best: 3057944 (40.86%) -> 785503 bytes (10.49%) ## Go Sources 8912 files, 51253563 bytes input: Default: 22955767 (44.79%) -> 19654568 (38.35%) Better: 20189613 (39.39%) -> 16289357 (31.78%) Best: 19482828 (38.01%) -> 15184589 (29.63%) # Status: * [x] Format Specification * [x] Reference Decoder * [x] Encoders (default, better, best) * [x] Roundtrip tests * [x] Fuzz tests ## Non-goals There will be no assembly for initial release. Also some compression may still be left on the table. There will be no Snappy implementation, since it will be incompatible anyway. # DOCUMENTATION *Note: S2 dictionary compression is currently at an early implementation stage, with no assembly for neither encoding nor decoding. Performance improvements can be expected in the future.* Adding dictionaries allow providing a custom dictionary that will serve as lookup in the beginning of blocks. The same dictionary *must* be used for both encoding and decoding. S2 does not keep track of whether the same dictionary is used, and using the wrong dictionary will most often not result in an error when decompressing. Blocks encoded *without* dictionaries can be decompressed seamlessly *with* a dictionary. This means it is possible to switch from an encoding without dictionaries to an encoding with dictionaries and treat the blocks similarly. Similar to [zStandard dictionaries](https://github.com/facebook/zstd#the-case-for-small-data-compression), the same usage scenario applies to S2 dictionaries. > Training works if there is some correlation in a family of small data samples. The more data-specific a dictionary is, the more efficient it is (there is no universal dictionary). Hence, deploying one dictionary per type of data will provide the greatest benefits. Dictionary gains are mostly effective in the first few KB. Then, the compression algorithm will gradually use previously decoded content to better compress the rest of the file. S2 further limits the dictionary to only be enabled on the first 64KB of a block. This will remove any negative (speed) impacts of the dictionaries on bigger blocks. ### Compression Using the [github_users_sample_set](https://github.com/facebook/zstd/releases/download/v1.1.3/github_users_sample_set.tar.zst) and a 64KB dictionary trained with zStandard the following sizes can be achieved. | | Default | Better | Best | |--------------------|------------------|------------------|-----------------------| | Without Dictionary | 3362023 (44.92%) | 3083163 (41.19%) | 3057944 (40.86%) | | With Dictionary | 921524 (12.31%) | 873154 (11.67%) | 785503 bytes (10.49%) | So for highly repetitive content, this case provides an almost 3x reduction in size. For less uniform data we will use the Go source code tree. Compressing First 64KB of all `.go` files in `go/src`, Go 1.19.5, 8912 files, 51253563 bytes input: | | Default | Better | Best | |--------------------|-------------------|-------------------|-------------------| | Without Dictionary | 22955767 (44.79%) | 20189613 (39.39% | 19482828 (38.01%) | | With Dictionary | 19654568 (38.35%) | 16289357 (31.78%) | 15184589 (29.63%) | | Saving/file | 362 bytes | 428 bytes | 472 bytes | ### Creating Dictionaries There are no tools to create dictionaries in S2. However, there are multiple ways to create a useful dictionary: #### Using a Sample File If your input is very uniform, you can just use a sample file as the dictionary. For example in the `github_users_sample_set` above, the average compression only goes up from 10.49% to 11.48% by using the first file as dictionary compared to using a dedicated dictionary. ```Go // Read a sample sample, err := os.ReadFile("sample.json") // Create a dictionary. dict := s2.MakeDict(sample, nil) // b := dict.Bytes() will provide a dictionary that can be saved // and reloaded with s2.NewDict(b). // To encode: encoded := dict.Encode(nil, file) // To decode: decoded, err := dict.Decode(nil, file) ``` #### Using Zstandard Zstandard dictionaries can easily be converted to S2 dictionaries. This can be helpful to generate dictionaries for files that don't have a fixed structure. Example, with training set files placed in `./training-set`: `λ zstd -r --train-fastcover training-set/* --maxdict=65536 -o name.dict` This will create a dictionary of 64KB, that can be converted to a dictionary like this: ```Go // Decode the Zstandard dictionary. insp, err := zstd.InspectDictionary(zdict) if err != nil { panic(err) } // We are only interested in the contents. // Assume that files start with "// Copyright (c) 2023". // Search for the longest match for that. // This may save a few bytes. dict := s2.MakeDict(insp.Content(), []byte("// Copyright (c) 2023")) // b := dict.Bytes() will provide a dictionary that can be saved // and reloaded with s2.NewDict(b). // We can now encode using this dictionary encodedWithDict := dict.Encode(nil, payload) // To decode content: decoded, err := dict.Decode(nil, encodedWithDict) ``` It is recommended to save the dictionary returned by ` b:= dict.Bytes()`, since that will contain only the S2 dictionary. This dictionary can later be loaded using `s2.NewDict(b)`. The dictionary then no longer requires `zstd` to be initialized. Also note how `s2.MakeDict` allows you to search for a common starting sequence of your files. This can be omitted, at the expense of a few bytes. # Dictionary Encoding Adding dictionaries allow providing a custom dictionary that will serve as lookup in the beginning of blocks. A dictionary provides an initial repeat value that can be used to point to a common header. Other than that the dictionary contains values that can be used as back-references. Often used data should be placed at the *end* of the dictionary since offsets < 2048 bytes will be smaller. ## Format Dictionary *content* must at least 16 bytes and less or equal to 64KiB (65536 bytes). Encoding: `[repeat value (uvarint)][dictionary content...]` Before the dictionary content, an unsigned base-128 (uvarint) encoded value specifying the initial repeat offset. This value is an offset into the dictionary content and not a back-reference offset, so setting this to 0 will make the repeat value point to the first value of the dictionary. The value must be less than the dictionary length-8. ## Encoding From the decoder point of view the dictionary content is seen as preceding the encoded content. `[dictionary content][decoded output]` Backreferences to the dictionary are encoded as ordinary backreferences that have an offset before the start of the decoded block. Matches copying from the dictionary are **not** allowed to cross from the dictionary into the decoded data. However, if a copy ends at the end of the dictionary the next repeat will point to the start of the decoded buffer, which is allowed. The first match can be a repeat value, which will use the repeat offset stored in the dictionary. When 64KB (65536 bytes) has been en/decoded it is no longer allowed to reference the dictionary, neither by a copy nor repeat operations. If the boundary is crossed while copying from the dictionary, the operation should complete, but the next instruction is not allowed to reference the dictionary. Valid blocks encoded *without* a dictionary can be decoded with any dictionary. There are no checks whether the supplied dictionary is the correct for a block. Because of this there is no overhead by using a dictionary. ## Streams For streams each block can use the dictionary. The dictionary is not provided on the stream.
This package provides various compression algorithms.
github.com/golang/snappy
offering better compression and concurrent streams.Jan 21st, 2023 (v1.15.15)
Jan 3rd, 2023 (v1.15.14)
Dec 11, 2022 (v1.15.13)
Oct 26, 2022 (v1.15.12)
HeaderNoCompression
https://github.com/klauspost/compress/pull/683Sept 26, 2022 (v1.15.11)
Sept 16, 2022 (v1.15.10)
July 21, 2022 (v1.15.9)
July 13, 2022 (v1.15.8)
June 29, 2022 (v1.15.7)
June 3, 2022 (v1.15.6)
May 25, 2022 (v1.15.5)
May 11, 2022 (v1.15.4)
May 5, 2022 (v1.15.3)
Apr 26, 2022 (v1.15.2)
Mar 11, 2022 (v1.15.1)
Mar 3, 2022 (v1.15.0)
Both compression and decompression now supports “synchronous” stream operations. This means that whenever “concurrency” is set to 1, they will operate without spawning goroutines.
Stream decompression is now faster on asynchronous, since the goroutine allocation much more effectively splits the workload. On typical streams this will typically use 2 cores fully for decompression. When a stream has finished decoding no goroutines will be left over, so decoders can now safely be pooled and still be garbage collected.
While the release has been extensively tested, it is recommended to testing when upgrading.
Feb 22, 2022 (v1.14.4)
Feb 17, 2022 (v1.14.3)
Jan 25, 2022 (v1.14.2)
Jan 11, 2022 (v1.14.1)
Aug 30, 2021 (v1.13.5)
Aug 12, 2021 (v1.13.4)
Aug 3, 2021 (v1.13.3)
Jun 14, 2021 (v1.13.1)
Jun 3, 2021 (v1.13.0)
May 25, 2021 (v1.12.3)
Apr 27, 2021 (v1.12.2)
Apr 14, 2021 (v1.12.1)
Mar 26, 2021 (v1.11.13)
Mar 5, 2021 (v1.11.12)
s2sx
binary that creates self extracting archives.Mar 1, 2021 (v1.11.9)
Feb 25, 2021 (v1.11.8)
Jan 14, 2021 (v1.11.7)
Jan 7, 2021 (v1.11.6)
Dec 20, 2020 (v1.11.4)
Nov 15, 2020 (v1.11.3)
Oct 11, 2020 (v1.11.2)
Oct 1, 2020 (v1.11.1)
Sept 8, 2020 (v1.11.0)
July 8, 2020 (v1.10.11)
June 23, 2020 (v1.10.10)
June 16, 2020 (v1.10.9):
June 5, 2020 (v1.10.8):
June 1, 2020 (v1.10.7):
May 21, 2020: (v1.10.6)
April 12, 2020: (v1.10.5)
Apr 8, 2020: (v1.10.4)
Mar 11, 2020: (v1.10.3)
Feb 27, 2020: (v1.10.2)
Feb 18, 2020: (v1.10.1)
Feb 4, 2020: (v1.10.0)
nil
for previous behaviour. #216-rm
(remove source files) and -q
(no output except errors) to s2c
and s2d
commandss2c
and s2d
commandline tools.The packages are drop-in replacements for standard libraries. Simply replace the import path to use them:
old import | new import | Documentation |
---|---|---|
compress/gzip | github.com/klauspost/compress/gzip | gzip |
compress/zlib | github.com/klauspost/compress/zlib | zlib |
archive/zip | github.com/klauspost/compress/zip | zip |
compress/flate | github.com/klauspost/compress/flate | flate |
You may also be interested in pgzip, which is a drop in replacement for gzip, which support multithreaded compression on big files and the optimized crc32 package used by these packages.
The packages contains the same as the standard library, so you can use the godoc for that: gzip, zip, zlib, flate.
Currently there is only minor speedup on decompression (mostly CRC32 calculation).
Memory usage is typically 1MB for a Writer. stdlib is in the same range. If you expect to have a lot of concurrently allocated Writers consider using the stateless compress described below.
For compression performance, see: this spreadsheet.
This package offers stateless compression as a special option for gzip/deflate. It will do compression but without maintaining any state between Write calls.
This means there will be no memory kept between Write calls, but compression and speed will be suboptimal.
This is only relevant in cases where you expect to run many thousands of compressors concurrently, but with very little activity. This is not intended for regular web servers serving individual requests.
Because of this, the size of actual Write calls will affect output size.
In gzip, specify level -3
/ gzip.StatelessCompression
to enable.
For direct deflate use, NewStatelessWriter and StatelessDeflate are available. See documentation
A bufio.Writer
can of course be used to control write sizes. For example, to use a 4KB buffer:
// replace 'ioutil.Discard' with your output. gzw, err := gzip.NewWriterLevel(ioutil.Discard, gzip.StatelessCompression) if err != nil { return err } defer gzw.Close() w := bufio.NewWriterSize(gzw, 4096) defer w.Flush() // Write to 'w'
This will only use up to 4KB in memory when the writer is idle.
Compression is almost always worse than the fastest compression level and each write will allocate (a little) memory.
It has been a while since we have been looking at the speed of this package compared to the standard library, so I thought I would re-do my tests and give some overall recommendations based on the current state. All benchmarks have been performed with Go 1.10 on my Desktop Intel(R) Core(TM) i7-2600 CPU @3.40GHz. Since I last ran the tests, I have gotten more RAM, which means tests with big files are no longer limited by my SSD.
The raw results are in my updated spreadsheet. Due to cgo changes and upstream updates i could not get the cgo version of gzip to compile. Instead I included the zstd cgo implementation. If I get cgo gzip to work again, I might replace the results in the sheet.
The columns to take note of are: MB/s - the throughput. Reduction - the data size reduction in percent of the original. Rel Speed relative speed compared to the standard library at the same level. Smaller - how many percent smaller is the compressed output compared to stdlib. Negative means the output was bigger. Loss means the loss (or gain) in compression as a percentage difference of the input.
The gzstd
(standard library gzip) and gzkp
(this package gzip) only uses one CPU core. pgzip
, bgzf
uses all 4 cores. zstd
uses one core, and is a beast (but not Go, yet).
There appears to be a roughly 5-10% speed advantage over the standard library when comparing at similar compression levels.
The biggest difference you will see is the result of re-balancing the compression levels. I wanted by library to give a smoother transition between the compression levels than the standard library.
This package attempts to provide a more smooth transition, where “1” is taking a lot of shortcuts, “5” is the reasonable trade-off and “9” is the “give me the best compression”, and the values in between gives something reasonable in between. The standard library has big differences in levels 1-4, but levels 5-9 having no significant gains - often spending a lot more time than can be justified by the achieved compression.
There are links to all the test data in the spreadsheet in the top left field on each tab.
This test set aims to emulate typical use in a web server. The test-set is 4GB data in 53k files, and is a mixture of (mostly) HTML, JS, CSS.
Since level 1 and 9 are close to being the same code, they are quite close. But looking at the levels in-between the differences are quite big.
Looking at level 6, this package is 88% faster, but will output about 6% more data. For a web server, this means you can serve 88% more data, but have to pay for 6% more bandwidth. You can draw your own conclusions on what would be the most expensive for your case.
This test is for typical data files stored on a server. In this case it is a collection of Go precompiled objects. They are very compressible.
The picture is similar to the web content, but with small differences since this is very compressible. Levels 2-3 offer good speed, but is sacrificing quite a bit of compression.
The standard library seems suboptimal on level 3 and 4 - offering both worse compression and speed than level 6 & 7 of this package respectively.
This is a JSON file with very high redundancy. The reduction starts at 95% on level 1, so in real life terms we are dealing with something like a highly redundant stream of data, etc.
It is definitely visible that we are dealing with specialized content here, so the results are very scattered. This package does not do very well at levels 1-4, but picks up significantly at level 5 and levels 7 and 8 offering great speed for the achieved compression.
So if you know you content is extremely compressible you might want to go slightly higher than the defaults. The standard library has a huge gap between levels 3 and 4 in terms of speed (2.75x slowdown), so it offers little “middle ground”.
This is a pretty common test corpus: enwik9. It contains the first 10^9 bytes of the English Wikipedia dump on Mar. 3, 2006. This is a very good test of typical text based compression and more data heavy streams.
We see a similar picture here as in “Web Content”. On equal levels some compression is sacrificed for more speed. Level 5 seems to be the best trade-off between speed and size, beating stdlib level 3 in both.
I will combine two test sets, one 10GB file set and a VM disk image (~8GB). Both contain different data types and represent a typical backup scenario.
The most notable thing is how quickly the standard library drops to very low compression speeds around level 5-6 without any big gains in compression. Since this type of data is fairly common, this does not seem like good behavior.
This is mainly a test of how good the algorithms are at detecting un-compressible input. The standard library only offers this feature with very conservative settings at level 1. Obviously there is no reason for the algorithms to try to compress input that cannot be compressed. The only downside is that it might skip some compressible data on false detections.
This compression library adds a special compression level, named HuffmanOnly
, which allows near linear time compression. This is done by completely disabling matching of previous data, and only reduce the number of bits to represent each character.
This means that often used characters, like ‘e’ and ' ' (space) in text use the fewest bits to represent, and rare characters like ‘¤’ takes more bits to represent. For more information see wikipedia or this nice video.
Since this type of compression has much less variance, the compression speed is mostly unaffected by the input data, and is usually more than 180MB/s for a single core.
The downside is that the compression ratio is usually considerably worse than even the fastest conventional compression. The compression ratio can never be better than 8:1 (12.5%).
The linear time compression can be used as a “better than nothing” mode, where you cannot risk the encoder to slow down on some content. For comparison, the size of the “Twain” text is 233460 bytes (+29% vs. level 1) and encode speed is 144MB/s (4.5x level 1). So in this case you trade a 30% size increase for a 4 times speedup.
For more information see my blog post on Fast Linear Time Compression.
This is implemented on Go 1.7 as “Huffman Only” mode, though not exposed for gzip.
Here are other packages of good quality and pure Go (no cgo wrappers or autoconverted code):
This code is licensed under the same conditions as the original Go code. See LICENSE file.