LLVM API Documentation
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 <iosfwd> 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 size_t compressToNewBuffer( 00050 const char* in, ///< The buffer to be compressed 00051 size_t size, ///< The size of the buffer to be compressed 00052 char*&out, ///< The returned output buffer 00053 std::string* error = 0 ///< Optional error message 00054 ); 00055 00056 /// This method compresses a block of memory pointed to by \p in with 00057 /// size \p size to a stream. The stream \p out must be open and ready for 00058 /// writing when this method is called. The stream will not be closed by 00059 /// this method. The \p hint argument indicates which type of 00060 /// compression the caller would *prefer*. 00061 /// @returns The amount of data written to \p out. 00062 /// @brief Compress memory to a file. 00063 static size_t compressToStream( 00064 const char*in, ///< The buffer to be compressed 00065 size_t size, ///< The size of the buffer to be compressed 00066 std::ostream& out, ///< The output stream to write data on 00067 std::string* error = 0 ///< Optional error message buffer 00068 ); 00069 00070 /// This method decompresses a block of memory pointed to by \p in with 00071 /// size \p size to a new block of memory, \p out, \p that was allocated 00072 /// by malloc. It is the caller's responsibility to free \p out. 00073 /// @returns The size of the output buffer \p out. 00074 /// @brief Decompress memory to a new memory buffer. 00075 static size_t decompressToNewBuffer( 00076 const char *in, ///< The buffer to be decompressed 00077 size_t size, ///< Size of the buffer to be decompressed 00078 char*&out, ///< The returned output buffer 00079 std::string* error = 0 ///< Optional error message buffer 00080 ); 00081 00082 /// This method decompresses a block of memory pointed to by \p in with 00083 /// size \p size to a stream. The stream \p out must be open and ready for 00084 /// writing when this method is called. The stream will not be closed by 00085 /// this method. 00086 /// @returns The amount of data written to \p out. 00087 /// @brief Decompress memory to a stream. 00088 static size_t decompressToStream( 00089 const char *in, ///< The buffer to be decompressed 00090 size_t size, ///< Size of the buffer to be decompressed 00091 std::ostream& out, ///< The stream to write write data on 00092 std::string* error = 0 ///< Optional error message buffer 00093 ); 00094 00095 /// @} 00096 /// @name Low Level Interface 00097 /// @{ 00098 public: 00099 /// A callback function type used by the Compressor's low level interface 00100 /// to get the next chunk of data to which (de)compressed output will be 00101 /// written. This callback completely abstracts the notion of how to 00102 /// handle the output data of compression or decompression. The callback 00103 /// is responsible for determining both the storage location and the size 00104 /// of the output. The callback may also do other things with the data 00105 /// such as write it, transmit it, etc. Note that providing very small 00106 /// values for \p size will make the compression run very inefficiently. 00107 /// It is recommended that \p size be chosen based on the some multiple or 00108 /// fraction of the object being decompressed or compressed, respetively. 00109 /// @returns 0 for success, 1 for failure 00110 /// @brief Output callback function type 00111 typedef size_t (OutputDataCallback)(char*& buffer, size_t& size, 00112 void* context); 00113 00114 /// This function does the compression work. The block of memory starting 00115 /// at \p in and extending for \p size bytes is compressed. The compressed 00116 /// output is written to memory blocks returned by the \p cb callback. The 00117 /// caller must provide an implementation of the OutputDataCallback 00118 /// function type and provide its address as \p cb. Note that the callback 00119 /// function will be called as many times as necessary to complete the 00120 /// compression of the \p in block but that the total size will generally 00121 /// be less than \p size. It is a good idea to provide as large a value to 00122 /// the callback's \p size parameter as possible so that fewer calls to 00123 /// the callback are made. The \p hint parameter tells the function which 00124 /// kind of compression to start with. However, if its not available on 00125 /// the platform, the algorithm "falls back" from bzip2 -> zlib -> simple. 00126 /// @returns the total size of the compressed data 00127 /// @brief Compress a block of memory. 00128 static size_t compress( 00129 const char* in, ///< The buffer to be compressed 00130 size_t size, ///< The size of the buffer to be compressed 00131 OutputDataCallback* cb, ///< Call back for memory allocation 00132 void* context = 0, ///< Context for callback 00133 std::string* error = 0 ///< Optional error message 00134 ); 00135 00136 /// This function does the decompression work. The block of memory 00137 /// starting at \p in and extending for \p size bytes is decompressed. The 00138 /// decompressed output is written to memory blocks returned by the \p cb 00139 /// callback. The caller must provide an implementation of the 00140 /// OutputDataCallback function type and provide its address as \p cb. 00141 /// Note that the callback function will be called as many times as 00142 /// necessary to complete the compression of the \p in block but that the 00143 /// total size will generally be greater than \p size. It is a good idea 00144 /// to provide as large a value to the callback's \p size parameter as 00145 /// possible so that fewer calls to the callback are made. 00146 /// @returns the total size of the decompressed data 00147 /// @brief Decompress a block of memory. 00148 static size_t decompress( 00149 const char *in, ///< The buffer to be decompressed 00150 size_t size, ///< Size of the buffer to be decompressed 00151 OutputDataCallback* cb, ///< Call back for memory allocation 00152 void* context = 0, ///< Context for callback 00153 std::string* error = 0 ///< Optional error message 00154 ); 00155 00156 /// @} 00157 }; 00158 } 00159 00160 // vim: sw=2 ai 00161 00162 #endif