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