LLVM API Documentation

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

Compressor.h

Go to the documentation of this file.
00001 //===- llvm/Support/Compressor.h --------------------------------*- C++ -*-===//
00002 // 
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file was developed by Reid Spencer and is distributed under the 
00006 // University of Illinois Open Source License. See LICENSE.TXT for details.
00007 // 
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file declares the llvm::Compressor class.
00011 //
00012 //===----------------------------------------------------------------------===//
00013 
00014 #ifndef LLVM_SUPPORT_COMPRESSOR_H
00015 #define LLVM_SUPPORT_COMPRESSOR_H
00016 
00017 #include "llvm/Support/DataTypes.h"
00018 #include <ostream>
00019 
00020 namespace llvm {
00021 
00022   /// This class provides an abstraction for compression and decompression of
00023   /// a block of memory.  The algorithm used here is currently bzip2 but that
00024   /// may change without notice. Should newer algorithms prove to compress
00025   /// bytecode better than bzip2, that newer algorithm will be added, but won't
00026   /// replace bzip2. This interface allows us to abstract the notion of 
00027   /// compression and deal with alternate compression schemes over time. 
00028   /// The type of compression used can be determined by inspecting the 
00029   /// first byte of the compressed output. Currently value '0' means no 
00030   /// compression was used (for very small files) and value '2' means bzip2
00031   /// compression was used.  The Compressor is intended for use with memory 
00032   /// mapped files where the entire data block to be compressed or decompressed
00033   /// is available in memory. However, output can be gathered in repeated calls
00034   /// to a callback.  Utilities for sending compressed or decompressed output 
00035   /// to a stream or directly to a memory block are also provided.
00036   /// @since 1.4
00037   /// @brief An abstraction for memory to memory data (de)compression
00038   class Compressor {
00039     /// @name High Level Interface
00040     /// @{
00041     public:
00042       /// This method compresses a block of memory pointed to by \p in with 
00043       /// size \p size to a block of memory, \p out, that is allocated with 
00044       /// malloc. It is the caller's responsibility to free \p out. The \p hint
00045       /// indicates which type of compression the caller would *prefer*.
00046       /// @throws std::string explaining error if a compression error occurs
00047       /// @returns The size of the output buffer \p out.
00048       /// @brief Compress memory to a new memory buffer.
00049       static uint64_t compressToNewBuffer(
00050         const char* in,           ///< The buffer to be compressed
00051         unsigned size,            ///< The size of the buffer to be compressed
00052         char*&out                 ///< The returned output buffer
00053       );
00054 
00055       /// This method compresses a block of memory pointed to by \p in with 
00056       /// size \p size to a stream. The stream \p out must be open and ready for
00057       /// writing when this method is called. The stream will not be closed by
00058       /// this method.  The \p hint argument indicates which type of 
00059       /// compression the caller would *prefer*.
00060       /// @returns The amount of data written to \p out.
00061       /// @brief Compress memory to a file.
00062       static uint64_t compressToStream(
00063         const char*in,            ///< The buffer to be compressed
00064         unsigned size,            ///< The size of the buffer to be compressed
00065         std::ostream& out         ///< The output stream to write data on
00066       );
00067 
00068       /// This method decompresses a block of memory pointed to by \p in with 
00069       /// size \p size to a new block of memory, \p out, \p that was allocated
00070       /// by malloc. It is the caller's responsibility to free \p out. 
00071       /// @returns The size of the output buffer \p out.
00072       /// @brief Decompress memory to a new memory buffer.
00073       static uint64_t decompressToNewBuffer(
00074         const char *in,           ///< The buffer to be decompressed
00075         unsigned size,            ///< Size of the buffer to be decompressed
00076         char*&out                 ///< The returned output buffer
00077       );
00078 
00079       /// This method decompresses a block of memory pointed to by \p in with 
00080       /// size \p size to a stream. The stream \p out must be open and ready for
00081       /// writing when this method is called. The stream will not be closed by
00082       /// this method. 
00083       /// @returns The amount of data written to \p out.
00084       /// @brief Decompress memory to a stream.
00085       static uint64_t decompressToStream(
00086         const char *in,           ///< The buffer to be decompressed
00087         unsigned size,            ///< Size of the buffer to be decompressed
00088         std::ostream& out         ///< The stream to write write data on
00089       );
00090 
00091     /// @}
00092     /// @name Low Level Interface
00093     /// @{
00094     public:
00095       /// A callback function type used by the Compressor's low level interface
00096       /// to get the next chunk of data to which (de)compressed output will be 
00097       /// written. This callback completely abstracts the notion of how to 
00098       /// handle the output data of compression or decompression. The callback
00099       /// is responsible for determining both the storage location and the size 
00100       /// of the output. The callback may also do other things with the data
00101       /// such as write it, transmit it, etc. Note that providing very small
00102       /// values for \p size will make the compression run very inefficiently.
00103       /// It is recommended that \p size be chosen based on the some multiple or
00104       /// fraction of the object being decompressed or compressed, respetively.
00105       /// @returns 0 for success, 1 for failure
00106       /// @throws nothing
00107       /// @brief Output callback function type
00108       typedef unsigned (OutputDataCallback)(char*& buffer, unsigned& size,
00109                                             void* context);
00110 
00111       /// This function does the compression work. The block of memory starting
00112       /// at \p in and extending for \p size bytes is compressed. The compressed
00113       /// output is written to memory blocks returned by the \p cb callback. The
00114       /// caller must provide an implementation of the OutputDataCallback
00115       /// function type and provide its address as \p cb. Note that the callback
00116       /// function will be called as many times as necessary to complete the
00117       /// compression of the \p in block but that the total size will generally
00118       /// be less than \p size. It is a good idea to provide as large a value to
00119       /// the callback's \p size parameter as possible so that fewer calls to
00120       /// the callback are made. The \p hint parameter tells the function which
00121       /// kind of compression to start with. However, if its not available on
00122       /// the platform, the algorithm "falls back" from bzip2 -> zlib -> simple.
00123       /// @throws std::string if an error occurs
00124       /// @returns the total size of the compressed data
00125       /// @brief Compress a block of memory.
00126       static uint64_t compress(
00127         const char* in,            ///< The buffer to be compressed
00128         unsigned size,             ///< The size of the buffer to be compressed
00129         OutputDataCallback* cb,    ///< Call back for memory allocation
00130         void* context = 0          ///< Context for callback
00131       );
00132 
00133       /// This function does the decompression work. The block of memory
00134       /// starting at \p in and extending for \p size bytes is decompressed. The
00135       /// decompressed output is written to memory blocks returned by the \p cb
00136       /// callback. The caller must provide an implementation of the
00137       /// OutputDataCallback function type and provide its address as \p cb.
00138       /// Note that the callback function will be called as many times as
00139       /// necessary to complete the compression of the \p in block but that the
00140       /// total size will generally be greater than \p size. It is a good idea
00141       /// to provide as large a value to the callback's \p size parameter as 
00142       /// possible so that fewer calls to the callback are made.
00143       /// @throws std::string if an error occurs
00144       /// @returns the total size of the decompressed data
00145       /// @brief Decompress a block of memory.
00146       static uint64_t decompress(
00147         const char *in,              ///< The buffer to be decompressed
00148         unsigned size,               ///< Size of the buffer to be decompressed
00149         OutputDataCallback* cb,      ///< Call back for memory allocation
00150         void* context = 0            ///< Context for callback
00151       );
00152 
00153     /// @}
00154   };
00155 }
00156 
00157 // vim: sw=2 ai
00158 
00159 #endif