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 #include <iosfwd>
  19 #include <string>
  20
  21 namespace llvm {
  22
  23   /// This class provides an abstraction for compression and decompression of
  24   /// a block of memory.  The algorithm used here is currently bzip2 but that
  25   /// may change without notice. Should newer algorithms prove to compress
  26   /// bytecode better than bzip2, that newer algorithm will be added, but won't
  27   /// replace bzip2. This interface allows us to abstract the notion of
  28   /// compression and deal with alternate compression schemes over time.
  29   /// The type of compression used can be determined by inspecting the
  30   /// first byte of the compressed output. Currently value '0' means no
  31   /// compression was used (for very small files) and value '2' means bzip2
  32   /// compression was used.  The Compressor is intended for use with memory
  33   /// mapped files where the entire data block to be compressed or decompressed
  34   /// is available in memory. However, output can be gathered in repeated calls
  35   /// to a callback.  Utilities for sending compressed or decompressed output
  36   /// to a stream or directly to a memory block are also provided.
  37   /// @since 1.4
  38   /// @brief An abstraction for memory to memory data (de)compression
  39   class Compressor {
  40     /// @name High Level Interface
  41     /// @{
  42     public:
  43       /// This method compresses a block of memory pointed to by \p in with
  44       /// size \p size to a block of memory, \p out, that is allocated with
  45       /// malloc. It is the caller's responsibility to free \p out. The \p hint
  46       /// indicates which type of compression the caller would *prefer*.
  47       /// @throws std::string explaining error if a compression error occurs
  48       /// @returns The size of the output buffer \p out.
  49       /// @brief Compress memory to a new memory buffer.
  50       static size_t compressToNewBuffer(
  51         const char* in,           ///< The buffer to be compressed
  52         size_t size,              ///< The size of the buffer to be compressed
  53         char*&out,                ///< The returned output buffer
  54         std::string* error = 0    ///< Optional error message
  55       );
  56
  57       /// This method compresses a block of memory pointed to by \p in with
  58       /// size \p size to a stream. The stream \p out must be open and ready for
  59       /// writing when this method is called. The stream will not be closed by
  60       /// this method.  The \p hint argument indicates which type of
  61       /// compression the caller would *prefer*.
  62       /// @returns The amount of data written to \p out.
  63       /// @brief Compress memory to a file.
  64       static size_t compressToStream(
  65         const char*in,            ///< The buffer to be compressed
  66         size_t size,              ///< The size of the buffer to be compressed
  67         std::ostream& out,        ///< The output stream to write data on
  68         std::string* error = 0    ///< Optional error message buffer
  69       );
  70
  71       /// This method decompresses a block of memory pointed to by \p in with
  72       /// size \p size to a new block of memory, \p out, \p that was allocated
  73       /// by malloc. It is the caller's responsibility to free \p out.
  74       /// @returns The size of the output buffer \p out.
  75       /// @brief Decompress memory to a new memory buffer.
  76       static size_t decompressToNewBuffer(
  77         const char *in,           ///< The buffer to be decompressed
  78         size_t size,              ///< Size of the buffer to be decompressed
  79         char*&out,                ///< The returned output buffer
  80         std::string* error = 0    ///< Optional error message buffer
  81       );
  82
  83       /// This method decompresses a block of memory pointed to by \p in with
  84       /// size \p size to a stream. The stream \p out must be open and ready for
  85       /// writing when this method is called. The stream will not be closed by
  86       /// this method.
  87       /// @returns The amount of data written to \p out.
  88       /// @brief Decompress memory to a stream.
  89       static size_t decompressToStream(
  90         const char *in,           ///< The buffer to be decompressed
  91         size_t size,              ///< Size of the buffer to be decompressed
  92         std::ostream& out,        ///< The stream to write write data on
  93         std::string* error = 0    ///< Optional error message buffer
  94       );
  95
  96     /// @}
  97     /// @name Low Level Interface
  98     /// @{
  99     public:
 100       /// A callback function type used by the Compressor's low level interface
 101       /// to get the next chunk of data to which (de)compressed output will be
 102       /// written. This callback completely abstracts the notion of how to
 103       /// handle the output data of compression or decompression. The callback
 104       /// is responsible for determining both the storage location and the size
 105       /// of the output. The callback may also do other things with the data
 106       /// such as write it, transmit it, etc. Note that providing very small
 107       /// values for \p size will make the compression run very inefficiently.
 108       /// It is recommended that \p size be chosen based on the some multiple or
 109       /// fraction of the object being decompressed or compressed, respetively.
 110       /// @returns 0 for success, 1 for failure
 111       /// @brief Output callback function type
 112       typedef size_t (OutputDataCallback)(char*& buffer, size_t& size,
 113                                             void* context);
 114
 115       /// This function does the compression work. The block of memory starting
 116       /// at \p in and extending for \p size bytes is compressed. The compressed
 117       /// output is written to memory blocks returned by the \p cb callback. The
 118       /// caller must provide an implementation of the OutputDataCallback
 119       /// function type and provide its address as \p cb. Note that the callback
 120       /// function will be called as many times as necessary to complete the
 121       /// compression of the \p in block but that the total size will generally
 122       /// be less than \p size. It is a good idea to provide as large a value to
 123       /// the callback's \p size parameter as possible so that fewer calls to
 124       /// the callback are made. The \p hint parameter tells the function which
 125       /// kind of compression to start with. However, if its not available on
 126       /// the platform, the algorithm "falls back" from bzip2 -> zlib -> simple.
 127       /// @returns the total size of the compressed data
 128       /// @brief Compress a block of memory.
 129       static size_t compress(
 130         const char* in,            ///< The buffer to be compressed
 131         size_t size,               ///< The size of the buffer to be compressed
 132         OutputDataCallback* cb,    ///< Call back for memory allocation
 133         void* context = 0,         ///< Context for callback
 134         std::string* error = 0     ///< Optional error message
 135       );
 136
 137       /// This function does the decompression work. The block of memory
 138       /// starting at \p in and extending for \p size bytes is decompressed. The
 139       /// decompressed output is written to memory blocks returned by the \p cb
 140       /// callback. The caller must provide an implementation of the
 141       /// OutputDataCallback function type and provide its address as \p cb.
 142       /// Note that the callback function will be called as many times as
 143       /// necessary to complete the compression of the \p in block but that the
 144       /// total size will generally be greater than \p size. It is a good idea
 145       /// to provide as large a value to the callback's \p size parameter as
 146       /// possible so that fewer calls to the callback are made.
 147       /// @returns the total size of the decompressed data
 148       /// @brief Decompress a block of memory.
 149       static size_t decompress(
 150         const char *in,              ///< The buffer to be decompressed
 151         size_t size,                 ///< Size of the buffer to be decompressed
 152         OutputDataCallback* cb,      ///< Call back for memory allocation
 153         void* context = 0,           ///< Context for callback
 154         std::string* error = 0       ///< Optional error message
 155       );
 156
 157     /// @}
 158   };
 159 }
 160
 161 // vim: sw=2 ai
 162
 163 #endif