| 1 | #ifndef _Rstzip_H_ |
| 2 | #define _Rstzip_H_ |
| 3 | |
| 4 | // version number of Rstzip.H interface. not of the rstzip library |
| 5 | #define RSTZIP_VERSION_STR "3.19" |
| 6 | |
| 7 | #include"rstf/rstf.h" |
| 8 | // #include "Compressor.H" |
| 9 | |
| 10 | |
| 11 | #ifdef __cplusplus |
| 12 | extern "C" { |
| 13 | #endif |
| 14 | |
| 15 | typedef enum { |
| 16 | RSTZIP_OK = 1, |
| 17 | RSTZIP_ERROR = -1 |
| 18 | } RstzipReturnVals; |
| 19 | |
| 20 | // this constant is provided as the default optimal buffer size. |
| 21 | // alternative buffer sizes may be specified to the compressor using the options string |
| 22 | // FIXME: the rstzip object can be queried for the buffer size of the input trace after the open() call |
| 23 | |
| 24 | const int rstzip_opt_buffersize = 1<<15; // new since library version 3.22 |
| 25 | |
| 26 | #ifdef __cplusplus |
| 27 | } |
| 28 | #endif |
| 29 | |
| 30 | #ifdef __cplusplus |
| 31 | |
| 32 | // ==== C++ Compression example ==== |
| 33 | // |
| 34 | // rz = new Rstzip; |
| 35 | // rz->open(outfile, "w", "verbose=0"); |
| 36 | // nrecs = fread(rstbuf, sizeof(rstf_unionT), RZ_opt_bufsize, infp); |
| 37 | // while (nrecs > 0) { |
| 38 | // rstzip->compress(rstbuf, nrecs); |
| 39 | // nrecs = fread(rstbuf, sizeof(rstf_unionT), opt_bufsize, infp); |
| 40 | // } |
| 41 | // rz->close(); |
| 42 | // delete rz; |
| 43 | |
| 44 | // ==== C++ Decompression example ==== |
| 45 | // |
| 46 | // rz = new Rstzip; |
| 47 | // rz->open(infile, "r", "verbose=0"); |
| 48 | // nrecs = rstzip->decompress(rstbuf, RZ_opt_bufsize); |
| 49 | // while (nrecs > 0) { |
| 50 | // fwrite(rstbuf, sizeof(rstf_unionT), nrecs, outfp); |
| 51 | // nrecs = rz->decompress(rstbuf, RZ_opt_bufsize; |
| 52 | // } |
| 53 | // rz->close(); |
| 54 | |
| 55 | // class Rstzip : public Compressor { |
| 56 | class Rstzip { |
| 57 | public: |
| 58 | Rstzip(); |
| 59 | |
| 60 | ~Rstzip(); |
| 61 | |
| 62 | // SYNOPSIS |
| 63 | // virtual int getMajorVersion(); |
| 64 | // virtual int getMinorVersion(); |
| 65 | // virtual const char* getVersionStr(); |
| 66 | // |
| 67 | // DESCRIPTION |
| 68 | // Return compressor library version information. |
| 69 | virtual int getMajorVersion(); |
| 70 | |
| 71 | virtual int getMinorVersion(); |
| 72 | |
| 73 | virtual const char* getVersionStr(); |
| 74 | |
| 75 | // SYNOPSIS |
| 76 | // virtual int |
| 77 | // open(const char* file, const char* md, const char* options) |
| 78 | // |
| 79 | // DESCRIPTION |
| 80 | // Opens 'file' for compressing or decompressing, and associates the |
| 81 | // rstzip object with it. |
| 82 | // |
| 83 | // The argument 'md' points to a string with one of the following |
| 84 | // sequences: |
| 85 | // r Open the compressed file for reading (decompression). |
| 86 | // w Open the noncompressed file for writing (compression). |
| 87 | // One of "r" and "w" must be specified. |
| 88 | // |
| 89 | // If the file parameter is NULL, the input file is set to stdin or stdout |
| 90 | // depending on the mode: stdin if "r" and stdout if "w" |
| 91 | // |
| 92 | // options: all rstzip2 options are optional with this version. |
| 93 | // Unrecognized options will be discarded. Recognized options are: |
| 94 | // |
| 95 | // verbose=0|1 <= produce verbose output while compressing/decompressing |
| 96 | // stats=0|1 <= print compression statistics |
| 97 | // ver=0|1|2|3 <= for decompression only: specify version of incoming file |
| 98 | // |
| 99 | // when opening a disk file, rstzip detects its version automatically. |
| 100 | // however, when reading from stdin, rstzip v3 is assumed unless specified in |
| 101 | // this manner. If more than one version is specified, results are unpredictable |
| 102 | // Version 0 indicates a RAW RST trace file. |
| 103 | // |
| 104 | // FIXME: ADD information about buffersize here |
| 105 | // |
| 106 | // Note: normally, a raw RST trace can be detected by the presence of a valid RST |
| 107 | // Header record. However, if this record is absent, manually specifying ver=0 is |
| 108 | // the only way to indicate to rstzip that the input file is a raw rst file. |
| 109 | // |
| 110 | // example: const char * rz3_options = "verbose=0 stats=1" |
| 111 | // |
| 112 | // RETURN VALUES |
| 113 | // Returns RSTZIP_OK (1) if the file is successfully opened; returns |
| 114 | // RSTZIP_ERROR (-1) otherwise. |
| 115 | virtual int open(const char* file, const char* md, const char* options); |
| 116 | |
| 117 | // SYNOPSIS |
| 118 | // virtual int compress(rstf_unionT* rstbuf, int nrecs); |
| 119 | // |
| 120 | // DESCRIPTION |
| 121 | // Compresses exactly 'nrecs' RST records from 'rstbuf', and writes |
| 122 | // the compressed data to the file opened by open(). |
| 123 | // |
| 124 | // For best performance, 'nrecs' should be set to rstzip_opt_buffersize |
| 125 | // or an integral multiple thereof. This minimizes memcpy() overhead. |
| 126 | // |
| 127 | // RETURN VALUES |
| 128 | // The number of RST records compressed is returned; this value |
| 129 | // should be equal to 'nrecs'. |
| 130 | virtual int compress(rstf_unionT* rstbuf, int nrecs); |
| 131 | |
| 132 | // SYNOPSIS |
| 133 | // virtual int decompress(rstf_unionT* rstbuf, int nrecs); |
| 134 | // |
| 135 | // DESCRIPTION |
| 136 | // Decompresses up to 'nrecs' records from the file opened by |
| 137 | // open(), and writes the decompressed records into 'rstbuf'. |
| 138 | // |
| 139 | // For best performance, 'nrecs' should be set to rstzip3_opt_buffersize |
| 140 | // or an integral multiple thereof. This minimizes memcpy() overhead. |
| 141 | // |
| 142 | // |
| 143 | // RETURN VALUES |
| 144 | // The number of RST records decompressed is returned; this value |
| 145 | // should be equal to 'nrecs', unless the end of the compressed |
| 146 | // trace is reached. Subsequent calls to decompress() will return 0. |
| 147 | virtual int decompress(rstf_unionT* rstbuf, int nrecs); |
| 148 | |
| 149 | // SYNOPSIS |
| 150 | // virtual void close(); |
| 151 | // |
| 152 | // DESCRIPTION |
| 153 | // Flushes all internal buffers, and closes the file specified by open(). |
| 154 | // This function must be called before exiting the program, or the |
| 155 | // (de)compressed file will be corrupted. |
| 156 | // |
| 157 | // RETURN VALUES |
| 158 | // None. |
| 159 | virtual void close(); |
| 160 | |
| 161 | // FIXME: add function to flush internal buffer while compressing |
| 162 | // while decompressing, we don't have this option because the |
| 163 | // buffer size is fixed in the input compressed file. |
| 164 | // virtual void flush(); |
| 165 | |
| 166 | // FIXME: add function to return the dynamic optimal buffer size |
| 167 | // |
| 168 | // for compression, the optimal buffer size is one that would exactly |
| 169 | // fill up the internal buffer, if any so that subsequent compress() calls |
| 170 | // would not require memcpy() into the internal buffer. |
| 171 | // |
| 172 | // for decompression, the optimal buffer size is one that would exactly |
| 173 | // empty the internal buffer, if any, so that subsequent decompress() calls |
| 174 | // would directly decompress into the caller's buffer. |
| 175 | // |
| 176 | // virtual int opt_buffer_size(); |
| 177 | |
| 178 | // protected: |
| 179 | // Compressor* rstzip; |
| 180 | private: |
| 181 | struct Rstzip_impl * impl; |
| 182 | |
| 183 | }; // class Rstzip; |
| 184 | |
| 185 | #else // __cplusplus |
| 186 | |
| 187 | typedef struct Rstzip Rstzip; |
| 188 | |
| 189 | #endif // __cplusplus |
| 190 | |
| 191 | #ifdef __cplusplus |
| 192 | extern "C" { |
| 193 | #endif |
| 194 | |
| 195 | // SYNOPSIS |
| 196 | // Rstzip* rzMakeRstzip(); |
| 197 | // |
| 198 | // DESCRIPTION |
| 199 | // Allocate an Rstip Compressor object. The object is deallocated by the |
| 200 | // rzClose() function. |
| 201 | // |
| 202 | // RETURN VALUES |
| 203 | // Pointer to the allocated Rstzip Compressor object. |
| 204 | Rstzip* rzMakeRstzip(); |
| 205 | |
| 206 | int rzGetMajorVersion(Rstzip* rstzip); |
| 207 | |
| 208 | int rzGetMinorVersion(Rstzip* rstzip); |
| 209 | |
| 210 | const char* rzGetVersionStr(Rstzip* rstzip); |
| 211 | |
| 212 | int rzOpen(Rstzip* rstzip, const char* file, const char* md, const char* options); |
| 213 | |
| 214 | int rzCompress(Rstzip* rstzip, rstf_unionT* rstbuf, int nrecs); |
| 215 | |
| 216 | int rzDecompress(Rstzip* rstzip, rstf_unionT* rstbuf, int nrecs); |
| 217 | |
| 218 | void rzClose(Rstzip* rstzip); |
| 219 | |
| 220 | #ifdef __cplusplus |
| 221 | } |
| 222 | #endif |
| 223 | |
| 224 | |
| 225 | |
| 226 | // for backwards compatibility. this structure is not used in rstzip3 |
| 227 | #ifdef __cplusplus |
| 228 | extern "C" { |
| 229 | #endif |
| 230 | |
| 231 | typedef struct { |
| 232 | uint32_t buffersize; |
| 233 | uint8_t numcpus; |
| 234 | uint8_t gzip; |
| 235 | uint8_t stats; |
| 236 | uint8_t version; |
| 237 | uint8_t rstzip; // For Zio.H |
| 238 | } RstzipOptions; |
| 239 | |
| 240 | #ifdef __cplusplus |
| 241 | } |
| 242 | #endif // #ifdef __cplusplus |
| 243 | |
| 244 | char* makeRstzipOptionsString(RstzipOptions* opts); |
| 245 | |
| 246 | |
| 247 | #endif // _Rstzip_H_ |