include/llvm/Support/Compressor.h

   1 //===- llvm/Support/Compressor.h --------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Reid Spencer and is distributed under the
   6 // University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file declares the llvm::Compressor class.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_SUPPORT_COMPRESSOR_H
  15 #define LLVM_SUPPORT_COMPRESSOR_H
  16
  17 #include <llvm/Support/DataTypes.h>
  18
  19 namespace llvm {
  20
  21   /// This class provides an abstraction for compressing a block of memory using
  22   /// a standard compression utility such as bzip2 or libz. This interface
  23   /// allos us to abstraction the notion of compression and deal with alternate
  24   /// compression scheme availability depending on the configured platform. This
  25   /// facility will always favor a bzip2 implementation if its available.
  26   /// Otherwise, libz will be used if its available. If neither zlib nor bzip2
  27   /// are available, a very simple algorithm provided by the Compressor class
  28   /// will be used The type of compression used can be determined by inspecting
  29   /// the first byte of the compressed output. ASCII values '0', '1', and '2',
  30   /// denote the compression type as given in the Algorithm enumeration below.
  31   /// The Compressor is intended for use with memory mapped files where the
  32   /// entire data block to be compressed or decompressed is available in
  33   /// memory. Output, however, can be gathered in repeated calls to a callback.
  34   /// @since 1.4
  35   /// @brief An abstraction for memory to memory data compression
  36   class Compressor {
  37     /// @name Types
  38     /// @{
  39     public:
  40       enum Algorithm {
  41         COMP_TYPE_SIMPLE = '0',  ///< Use simple but ubiquitous algorithm
  42         COMP_TYPE_ZLIB = '1',    ///< Use zlib algorithm, if available
  43         COMP_TYPE_BZIP2 = '2',   ///< Use bzip2 algorithm (preferred)
  44       };
  45
  46       /// A callback function type used by the Compressor to get the next chunk
  47       /// of data to which (de)compressed output will be written. This function
  48       /// must be written by the caller to provide the buffering of the output
  49       /// data.
  50       /// @returns 0 for success, 1 for failure
  51       /// @throws nothing
  52       /// @brief Output callback function type
  53       typedef unsigned (OutputDataCallback)(char*& buffer, unsigned& size);
  54
  55     /// @}
  56     /// @name Methods
  57     /// @{
  58     public:
  59       /// This function does the compression work. The block of memory starting
  60       /// at \p in and extending for \p size bytes is compressed. The compressed
  61       /// output is written to memory blocks returned by the \p cb callback. The
  62       /// caller must provide an implementation of the OutputDataCallback
  63       /// function type and provide its address as \p cb. Note that the callback
  64       /// function will be called as many times as necessary to complete the
  65       /// compression of the \p in block but that the total size will generally
  66       /// be less than \p size. It is a good idea to provide as large a value to
  67       /// the callback's \p size parameter as possible so that fewer calls to
  68       /// the callback are made. The \p hint parameter tells the function which
  69       /// kind of compression to start with. However, if its not available on
  70       /// the platform, the algorithm "falls back" from bzip2 -> zlib -> simple.
  71       /// @throws std::string if an error occurs
  72       /// @returns the total size of the compressed data
  73       /// @brief Compress a block of memory.
  74       static uint64_t compress(char* in, unsigned size, OutputDataCallback* cb,
  75                                Algorithm hint = COMP_TYPE_BZIP2);
  76
  77       /// This function does the decompression work. The block of memory
  78       /// starting at \p in and extending for \p size bytes is decompressed. The
  79       /// decompressed output is written to memory blocks returned by the \p cb
  80       /// callback. The caller must provide an implementation of the
  81       /// OutputDataCallback function type and provide its address as \p cb.
  82       /// Note that the callback function will be called as many times as
  83       /// necessary to complete the compression of the \p in block but that the
  84       /// total size will generally be greater than \p size. It is a good idea
  85       /// to provide as large a value to the callback's \p size parameter as
  86       /// possible so that fewer calls to the callback are made.
  87       /// @throws std::string if an error occurs
  88       /// @returns the total size of the decompressed data
  89       /// @brief Decompress a block of memory.
  90       static uint64_t decompress(char *in, unsigned size,
  91                                  OutputDataCallback* cb);
  92
  93     /// @}
  94   };
  95 }
  96
  97 // vim: sw=2 ai
  98
  99 #endif