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   /// allows us to abstract 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 it is 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. However, output can be gathered in repeated calls to a callback.
  34   /// @since 1.4
  35   /// @brief An abstraction for memory to memory data (de)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                                             void* context);
  55
  56     /// @}
  57     /// @name Methods
  58     /// @{
  59     public:
  60       /// This function does the compression work. The block of memory starting
  61       /// at \p in and extending for \p size bytes is compressed. The compressed
  62       /// output is written to memory blocks returned by the \p cb callback. The
  63       /// caller must provide an implementation of the OutputDataCallback
  64       /// function type and provide its address as \p cb. Note that the callback
  65       /// function will be called as many times as necessary to complete the
  66       /// compression of the \p in block but that the total size will generally
  67       /// be less than \p size. It is a good idea to provide as large a value to
  68       /// the callback's \p size parameter as possible so that fewer calls to
  69       /// the callback are made. The \p hint parameter tells the function which
  70       /// kind of compression to start with. However, if its not available on
  71       /// the platform, the algorithm "falls back" from bzip2 -> zlib -> simple.
  72       /// @throws std::string if an error occurs
  73       /// @returns the total size of the compressed data
  74       /// @brief Compress a block of memory.
  75       static uint64_t compress(char* in, unsigned size, OutputDataCallback* cb,
  76                                Algorithm hint = COMP_TYPE_BZIP2,
  77                                void* context = 0);
  78
  79       /// This function does the decompression work. The block of memory
  80       /// starting at \p in and extending for \p size bytes is decompressed. The
  81       /// decompressed output is written to memory blocks returned by the \p cb
  82       /// callback. The caller must provide an implementation of the
  83       /// OutputDataCallback function type and provide its address as \p cb.
  84       /// Note that the callback function will be called as many times as
  85       /// necessary to complete the compression of the \p in block but that the
  86       /// total size will generally be greater than \p size. It is a good idea
  87       /// to provide as large a value to the callback's \p size parameter as
  88       /// possible so that fewer calls to the callback are made.
  89       /// @throws std::string if an error occurs
  90       /// @returns the total size of the decompressed data
  91       /// @brief Decompress a block of memory.
  92       static uint64_t decompress(char *in, unsigned size,
  93                                  OutputDataCallback* cb, void* context = 0);
  94
  95     /// @}
  96   };
  97 }
  98
  99 // vim: sw=2 ai
 100
 101 #endif