#ifndef LLVM_SUPPORT_COMPRESSOR_H
#define LLVM_SUPPORT_COMPRESSOR_H
-#include <llvm/Support/DataTypes.h>
+#include "llvm/Support/DataTypes.h"
+#include <iosfwd>
namespace llvm {
- /// This class provides an abstraction for compressing a block of memory using
- /// a standard compression utility such as bzip2 or libz. This interface
- /// allos us to abstraction the notion of compression and deal with alternate
- /// compression scheme availability depending on the configured platform. This
- /// facility will always favor a bzip2 implementation if its available.
- /// Otherwise, libz will be used if its available. If neither zlib nor bzip2
- /// are available, a very simple algorithm provided by the Compressor class
- /// will be used The type of compression used can be determined by inspecting
- /// the first byte of the compressed output. ASCII values '0', '1', and '2',
- /// denote the compression type as given in the Algorithm enumeration below.
- /// The Compressor is intended for use with memory mapped files where the
- /// entire data block to be compressed or decompressed is available in
- /// memory. Output, however, can be gathered in repeated calls to a callback.
+ /// This class provides an abstraction for compression and decompression of
+ /// a block of memory. The algorithm used here is currently bzip2 but that
+ /// may change without notice. Should newer algorithms prove to compress
+ /// bytecode better than bzip2, that newer algorithm will be added, but won't
+ /// replace bzip2. This interface allows us to abstract the notion of
+ /// compression and deal with alternate compression schemes over time.
+ /// The type of compression used can be determined by inspecting the
+ /// first byte of the compressed output. Currently value '0' means no
+ /// compression was used (for very small files) and value '2' means bzip2
+ /// compression was used. The Compressor is intended for use with memory
+ /// mapped files where the entire data block to be compressed or decompressed
+ /// is available in memory. However, output can be gathered in repeated calls
+ /// to a callback. Utilities for sending compressed or decompressed output
+ /// to a stream or directly to a memory block are also provided.
/// @since 1.4
- /// @brief An abstraction for memory to memory data compression
+ /// @brief An abstraction for memory to memory data (de)compression
class Compressor {
- /// @name Types
+ /// @name High Level Interface
/// @{
public:
- enum Algorithm {
- COMP_TYPE_SIMPLE = '0', ///< Use simple but ubiquitous algorithm
- COMP_TYPE_ZLIB = '1', ///< Use zlib algorithm, if available
- COMP_TYPE_BZIP2 = '2', ///< Use bzip2 algorithm (preferred)
- };
+ /// This method compresses a block of memory pointed to by \p in with
+ /// size \p size to a block of memory, \p out, that is allocated with
+ /// malloc. It is the caller's responsibility to free \p out. The \p hint
+ /// indicates which type of compression the caller would *prefer*.
+ /// @throws std::string explaining error if a compression error occurs
+ /// @returns The size of the output buffer \p out.
+ /// @brief Compress memory to a new memory buffer.
+ static size_t compressToNewBuffer(
+ const char* in, ///< The buffer to be compressed
+ size_t size, ///< The size of the buffer to be compressed
+ char*&out ///< The returned output buffer
+ );
- /// A callback function type used by the Compressor to get the next chunk
- /// of data to which (de)compressed output will be written. This function
- /// must be written by the caller to provide the buffering of the output
- /// data.
- /// @returns 0 for success, 1 for failure
- /// @throws nothing
- /// @brief Output callback function type
- typedef unsigned (OutputDataCallback)(char*& buffer, unsigned& size);
+ /// This method compresses a block of memory pointed to by \p in with
+ /// size \p size to a stream. The stream \p out must be open and ready for
+ /// writing when this method is called. The stream will not be closed by
+ /// this method. The \p hint argument indicates which type of
+ /// compression the caller would *prefer*.
+ /// @returns The amount of data written to \p out.
+ /// @brief Compress memory to a file.
+ static size_t compressToStream(
+ const char*in, ///< The buffer to be compressed
+ size_t size, ///< The size of the buffer to be compressed
+ std::ostream& out ///< The output stream to write data on
+ );
+
+ /// This method decompresses a block of memory pointed to by \p in with
+ /// size \p size to a new block of memory, \p out, \p that was allocated
+ /// by malloc. It is the caller's responsibility to free \p out.
+ /// @returns The size of the output buffer \p out.
+ /// @brief Decompress memory to a new memory buffer.
+ static size_t decompressToNewBuffer(
+ const char *in, ///< The buffer to be decompressed
+ size_t size, ///< Size of the buffer to be decompressed
+ char*&out ///< The returned output buffer
+ );
+
+ /// This method decompresses a block of memory pointed to by \p in with
+ /// size \p size to a stream. The stream \p out must be open and ready for
+ /// writing when this method is called. The stream will not be closed by
+ /// this method.
+ /// @returns The amount of data written to \p out.
+ /// @brief Decompress memory to a stream.
+ static size_t decompressToStream(
+ const char *in, ///< The buffer to be decompressed
+ size_t size, ///< Size of the buffer to be decompressed
+ std::ostream& out ///< The stream to write write data on
+ );
/// @}
- /// @name Methods
+ /// @name Low Level Interface
/// @{
public:
+ /// A callback function type used by the Compressor's low level interface
+ /// to get the next chunk of data to which (de)compressed output will be
+ /// written. This callback completely abstracts the notion of how to
+ /// handle the output data of compression or decompression. The callback
+ /// is responsible for determining both the storage location and the size
+ /// of the output. The callback may also do other things with the data
+ /// such as write it, transmit it, etc. Note that providing very small
+ /// values for \p size will make the compression run very inefficiently.
+ /// It is recommended that \p size be chosen based on the some multiple or
+ /// fraction of the object being decompressed or compressed, respetively.
+ /// @returns 0 for success, 1 for failure
+ /// @throws nothing
+ /// @brief Output callback function type
+ typedef size_t (OutputDataCallback)(char*& buffer, size_t& size,
+ void* context);
+
/// This function does the compression work. The block of memory starting
/// at \p in and extending for \p size bytes is compressed. The compressed
/// output is written to memory blocks returned by the \p cb callback. The
/// @throws std::string if an error occurs
/// @returns the total size of the compressed data
/// @brief Compress a block of memory.
- static uint64_t compress(char* in, unsigned size, OutputDataCallback* cb,
- Algorithm hint = COMP_TYPE_BZIP2);
+ static size_t compress(
+ const char* in, ///< The buffer to be compressed
+ size_t size, ///< The size of the buffer to be compressed
+ OutputDataCallback* cb, ///< Call back for memory allocation
+ void* context = 0 ///< Context for callback
+ );
/// This function does the decompression work. The block of memory
/// starting at \p in and extending for \p size bytes is decompressed. The
/// @throws std::string if an error occurs
/// @returns the total size of the decompressed data
/// @brief Decompress a block of memory.
- static uint64_t decompress(char *in, unsigned size,
- OutputDataCallback* cb);
+ static size_t decompress(
+ const char *in, ///< The buffer to be decompressed
+ size_t size, ///< Size of the buffer to be decompressed
+ OutputDataCallback* cb, ///< Call back for memory allocation
+ void* context = 0 ///< Context for callback
+ );
/// @}
};
projects / oota-llvm.git / blobdiff