LLVM API Documentation

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 <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