git.cworth.org Git - apitrace/blob - thirdparty/snappy/README

   1 Snappy, a fast compressor/decompressor.
   2
   3
   4 Introduction
   5 ============
   6
   7 Snappy is a compression/decompression library. It does not aim for maximum
   8 compression, or compatibility with any other compression library; instead,
   9 it aims for very high speeds and reasonable compression. For instance,
  10 compared to the fastest mode of zlib, Snappy is an order of magnitude faster
  11 for most inputs, but the resulting compressed files are anywhere from 20% to
  12 100% bigger. (For more information, see "Performance", below.)
  13
  14 Snappy has the following properties:
  15
  16  * Fast: Compression speeds at 250 MB/sec and beyond, with no assembler code.
  17    See "Performance" below.
  18  * Stable: Over the last few years, Snappy has compressed and decompressed
  19    petabytes of data in Google's production environment. The Snappy bitstream
  20    format is stable and will not change between versions.
  21  * Robust: The Snappy decompressor is designed not to crash in the face of
  22    corrupted or malicious input.
  23  * Free and open source software: Snappy is licensed under a BSD-type license.
  24    For more information, see the included COPYING file.
  25
  26 Snappy has previously been called "Zippy" in some Google presentations
  27 and the like.
  28
  29
  30 Performance
  31 ===========
  32
  33 Snappy is intended to be fast. On a single core of a Core i7 processor
  34 in 64-bit mode, it compresses at about 250 MB/sec or more and decompresses at
  35 about 500 MB/sec or more. (These numbers are for the slowest inputs in our
  36 benchmark suite; others are much faster.) In our tests, Snappy usually
  37 is faster than algorithms in the same class (e.g. LZO, LZF, FastLZ, QuickLZ,
  38 etc.) while achieving comparable compression ratios.
  39
  40 Typical compression ratios (based on the benchmark suite) are about 1.5-1.7x
  41 for plain text, about 2-4x for HTML, and of course 1.0x for JPEGs, PNGs and
  42 other already-compressed data. Similar numbers for zlib in its fastest mode
  43 are 2.6-2.8x, 3-7x and 1.0x, respectively. More sophisticated algorithms are
  44 capable of achieving yet higher compression rates, although usually at the
  45 expense of speed. Of course, compression ratio will vary significantly with
  46 the input.
  47
  48 Although Snappy should be fairly portable, it is primarily optimized
  49 for 64-bit x86-compatible processors, and may run slower in other environments.
  50 In particular:
  51
  52  - Snappy uses 64-bit operations in several places to process more data at
  53    once than would otherwise be possible.
  54  - Snappy assumes unaligned 32- and 64-bit loads and stores are cheap.
  55    On some platforms, these must be emulated with single-byte loads
  56    and stores, which is much slower.
  57  - Snappy assumes little-endian throughout, and needs to byte-swap data in
  58    several places if running on a big-endian platform.
  59
  60 Experience has shown that even heavily tuned code can be improved.
  61 Performance optimizations, whether for 64-bit x86 or other platforms,
  62 are of course most welcome; see "Contact", below.
  63
  64
  65 Usage
  66 =====
  67
  68 Note that Snappy, both the implementation and the main interface,
  69 is written in C++. However, several third-party bindings to other languages
  70 are available; see the Google Code page at http://code.google.com/p/snappy/
  71 for more information. Also, if you want to use Snappy from C code, you can
  72 use the included C bindings in snappy-c.h.
  73
  74 To use Snappy from your own C++ program, include the file "snappy.h" from
  75 your calling file, and link against the compiled library.
  76
  77 There are many ways to call Snappy, but the simplest possible is
  78
  79   snappy::Compress(input, &output);
  80
  81 and similarly
  82
  83   snappy::Uncompress(input, &output);
  84
  85 where "input" and "output" are both instances of std::string.
  86
  87 There are other interfaces that are more flexible in various ways, including
  88 support for custom (non-array) input sources. See the header file for more
  89 information.
  90
  91
  92 Tests and benchmarks
  93 ====================
  94
  95 When you compile Snappy, snappy_unittest is compiled in addition to the
  96 library itself. You do not need it to use the compressor from your own library,
  97 but it contains several useful components for Snappy development.
  98
  99 First of all, it contains unit tests, verifying correctness on your machine in
 100 various scenarios. If you want to change or optimize Snappy, please run the
 101 tests to verify you have not broken anything. Note that if you have the
 102 Google Test library installed, unit test behavior (especially failures) will be
 103 significantly more user-friendly. You can find Google Test at
 104
 105   http://code.google.com/p/googletest/
 106
 107 You probably also want the gflags library for handling of command-line flags;
 108 you can find it at
 109
 110   http://code.google.com/p/google-gflags/
 111
 112 In addition to the unit tests, snappy contains microbenchmarks used to
 113 tune compression and decompression performance. These are automatically run
 114 before the unit tests, but you can disable them using the flag
 115 --run_microbenchmarks=false if you have gflags installed (otherwise you will
 116 need to edit the source).
 117
 118 Finally, snappy can benchmark Snappy against a few other compression libraries
 119 (zlib, LZO, LZF, FastLZ and QuickLZ), if they were detected at configure time.
 120 To benchmark using a given file, give the compression algorithm you want to test
 121 Snappy against (e.g. --zlib) and then a list of one or more file names on the
 122 command line. The testdata/ directory contains the files used by the
 123 microbenchmark, which should provide a reasonably balanced starting point for
 124 benchmarking. (Note that baddata[1-3].snappy are not intended as benchmarks; they
 125 are used to verify correctness in the presence of corrupted data in the unit
 126 test.)
 127
 128
 129 Contact
 130 =======
 131
 132 Snappy is distributed through Google Code. For the latest version, a bug tracker,
 133 and other information, see
 134
 135   http://code.google.com/p/snappy/