HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
blosc.h
Go to the documentation of this file.
1 /*********************************************************************
2  Blosc - Blocked Suffling and Compression Library
3 
4  Author: Francesc Alted <francesc@blosc.org>
5 
6  See LICENSES/BLOSC.txt for details about copyright and rights to use.
7 **********************************************************************/
8 #ifndef BLOSC_H
9 #define BLOSC_H
10 
11 #include <limits.h>
12 #include <stdlib.h>
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 #ifdef DLL_EXPORT
18  #undef DLL_EXPORT
19  #define DLL_EXPORT __declspec(dllexport)
20 #else
21  #undef DLL_EXPORT
22  #define DLL_EXPORT
23 #endif
24 
25 /* Version numbers */
26 #define BLOSC_VERSION_MAJOR 1 /* for major interface/format changes */
27 #define BLOSC_VERSION_MINOR 5 /* for minor interface/format changes */
28 #define BLOSC_VERSION_RELEASE 0 /* for tweaks, bug-fixes, or development */
29 
30 #define BLOSC_VERSION_STRING "1.5.0" /* string version. Sync with above! */
31 #define BLOSC_VERSION_REVISION "$Rev$" /* revision version */
32 #define BLOSC_VERSION_DATE "$Date:: 2014-11-07 #$" /* date version */
33 
34 #define BLOSCLZ_VERSION_STRING "1.0.3" /* the internal compressor version */
35 
36 /* The *_FORMAT symbols should be just 1-byte long */
37 #define BLOSC_VERSION_FORMAT 2 /* Blosc format version, starting at 1 */
38 
39 /* Minimum header length */
40 #define BLOSC_MIN_HEADER_LENGTH 16
41 
42 /* The maximum overhead during compression in bytes. This equals to
43  BLOSC_MIN_HEADER_LENGTH now, but can be higher in future
44  implementations */
45 #define BLOSC_MAX_OVERHEAD BLOSC_MIN_HEADER_LENGTH
46 
47 /* Maximum buffer size to be compressed */
48 #define BLOSC_MAX_BUFFERSIZE (INT_MAX - BLOSC_MAX_OVERHEAD)
49 
50 /* Maximum typesize before considering buffer as a stream of bytes */
51 #define BLOSC_MAX_TYPESIZE 255 /* Cannot be larger than 255 */
52 
53 /* The maximum number of threads (for some static arrays) */
54 #define BLOSC_MAX_THREADS 256
55 
56 /* Codes for internal flags (see blosc_cbuffer_metainfo) */
57 #define BLOSC_DOSHUFFLE 0x1
58 #define BLOSC_MEMCPYED 0x2
59 
60 /* Codes for the different compressors shipped with Blosc */
61 #define BLOSC_BLOSCLZ 0
62 #define BLOSC_LZ4 1
63 #define BLOSC_LZ4HC 2
64 #define BLOSC_SNAPPY 3
65 #define BLOSC_ZLIB 4
66 
67 /* Names for the different compressors shipped with Blosc */
68 #define BLOSC_BLOSCLZ_COMPNAME "blosclz"
69 #define BLOSC_LZ4_COMPNAME "lz4"
70 #define BLOSC_LZ4HC_COMPNAME "lz4hc"
71 #define BLOSC_SNAPPY_COMPNAME "snappy"
72 #define BLOSC_ZLIB_COMPNAME "zlib"
73 
74 /* Codes for the different compression libraries shipped with Blosc */
75 #define BLOSC_BLOSCLZ_LIB 0
76 #define BLOSC_LZ4_LIB 1
77 #define BLOSC_SNAPPY_LIB 2
78 #define BLOSC_ZLIB_LIB 3
79 
80 /* Names for the different compression libraries shipped with Blosc */
81 #define BLOSC_BLOSCLZ_LIBNAME "BloscLZ"
82 #define BLOSC_LZ4_LIBNAME "LZ4"
83 #define BLOSC_SNAPPY_LIBNAME "Snappy"
84 #define BLOSC_ZLIB_LIBNAME "Zlib"
85 
86 /* The codes for compressor formats shipped with Blosc (code must be < 8) */
87 #define BLOSC_BLOSCLZ_FORMAT BLOSC_BLOSCLZ_LIB
88 #define BLOSC_LZ4_FORMAT BLOSC_LZ4_LIB
89  /* LZ4HC and LZ4 share the same format */
90 #define BLOSC_LZ4HC_FORMAT BLOSC_LZ4_LIB
91 #define BLOSC_SNAPPY_FORMAT BLOSC_SNAPPY_LIB
92 #define BLOSC_ZLIB_FORMAT BLOSC_ZLIB_LIB
93 
94 
95 /* The version formats for compressors shipped with Blosc */
96 /* All versions here starts at 1 */
97 #define BLOSC_BLOSCLZ_VERSION_FORMAT 1
98 #define BLOSC_LZ4_VERSION_FORMAT 1
99 #define BLOSC_LZ4HC_VERSION_FORMAT 1 /* LZ4HC and LZ4 share the same format */
100 #define BLOSC_SNAPPY_VERSION_FORMAT 1
101 #define BLOSC_ZLIB_VERSION_FORMAT 1
102 
103 
104 /**
105  Initialize the Blosc library environment.
106 
107  You must call this previous to any other Blosc call, unless you want
108  Blosc to be used simultaneously in a multi-threaded environment, in
109  which case you should *exclusively* use the
110  blosc_compress_ctx()/blosc_decompress_ctx() pair (see below).
111  */
112 DLL_EXPORT void blosc_init(void);
113 
114 
115 /**
116  Destroy the Blosc library environment.
117 
118  You must call this after to you are done with all the Blosc calls,
119  unless you have not used blosc_init() before (see blosc_init()
120  above).
121  */
122 DLL_EXPORT void blosc_destroy(void);
123 
124 
125 /**
126  Compress a block of data in the `src` buffer and returns the size of
127  compressed block. The size of `src` buffer is specified by
128  `nbytes`. There is not a minimum for `src` buffer size (`nbytes`).
129 
130  `clevel` is the desired compression level and must be a number
131  between 0 (no compression) and 9 (maximum compression).
132 
133  `doshuffle` specifies whether the shuffle compression preconditioner
134  should be applied or not. 0 means not applying it and 1 means
135  applying it.
136 
137  `typesize` is the number of bytes for the atomic type in binary
138  `src` buffer. This is mainly useful for the shuffle preconditioner.
139  For implementation reasons, only a 1 < typesize < 256 will allow the
140  shuffle filter to work. When typesize is not in this range, shuffle
141  will be silently disabled.
142 
143  The `dest` buffer must have at least the size of `destsize`. Blosc
144  guarantees that if you set `destsize` to, at least,
145  (`nbytes`+BLOSC_MAX_OVERHEAD), the compression will always succeed.
146  The `src` buffer and the `dest` buffer can not overlap.
147 
148  Compression is memory safe and guaranteed not to write the `dest`
149  buffer more than what is specified in `destsize`.
150 
151  If `src` buffer cannot be compressed into `destsize`, the return
152  value is zero and you should discard the contents of the `dest`
153  buffer.
154 
155  A negative return value means that an internal error happened. This
156  should never happen. If you see this, please report it back
157  together with the buffer data causing this and compression settings.
158  */
159 DLL_EXPORT int blosc_compress(int clevel, int doshuffle, size_t typesize,
160  size_t nbytes, const void *src, void *dest,
161  size_t destsize);
162 
163 
164 /**
165  Context interface to blosc compression. This does not require a call
166  to blosc_init() and can be called from multithreaded applications
167  without the global lock being used, so allowing Blosc be executed
168  simultaneously in those scenarios.
169 
170  It uses the same parameters than the blosc_compress() function plus:
171 
172  `compressor`: the string representing the type of compressor to use.
173 
174  `blocksize`: the requested size of the compressed blocks.
175 
176  `numinternalthreads`: the number of threads to use internally.
177 
178  Note: This call may be removed in Blosc 2.0, but a proper
179  replacement for the same functionality should be in place by then.
180 
181  A negative return value means that an internal error happened. This
182  should never happen. If you see this, please report it back
183  together with the buffer data causing this and compression settings.
184 */
185 DLL_EXPORT int blosc_compress_ctx(int clevel, int doshuffle, size_t typesize,
186  size_t nbytes, const void* src, void* dest,
187  size_t destsize, const char* compressor,
188  size_t blocksize, int numinternalthreads);
189 
190 /**
191  Decompress a block of compressed data in `src`, put the result in
192  `dest` and returns the size of the decompressed block.
193 
194  The `src` buffer and the `dest` buffer can not overlap.
195 
196  Decompression is memory safe and guaranteed not to write the `dest`
197  buffer more than what is specified in `destsize`.
198 
199  If an error occurs, e.g. the compressed data is corrupted or the
200  output buffer is not large enough, then 0 (zero) or a negative value
201  will be returned instead.
202 */
203 DLL_EXPORT int blosc_decompress(const void *src, void *dest, size_t destsize);
204 
205 
206 /**
207  Context interface to blosc decompression. This does not require a
208  call to blosc_init() and can be called from multithreaded
209  applications without the global lock being used, so allowing Blosc
210  be executed simultaneously in those scenarios.
211 
212  It uses the same parameters than the blosc_decompress() function plus:
213 
214  `numinternalthreads`: number of threads to use internally.
215 
216  Decompression is memory safe and guaranteed not to write the `dest`
217  buffer more than what is specified in `destsize`.
218 
219  Note: This call may be removed in Blosc 2.0, but a proper
220  replacement for the same functionality should be in place by then.
221 
222  If an error occurs, e.g. the compressed data is corrupted or the
223  output buffer is not large enough, then 0 (zero) or a negative value
224  will be returned instead.
225 */
226 DLL_EXPORT int blosc_decompress_ctx(const void *src, void *dest,
227  size_t destsize, int numinternalthreads);
228 
229 /**
230  Get `nitems` (of typesize size) in `src` buffer starting in `start`.
231  The items are returned in `dest` buffer, which has to have enough
232  space for storing all items.
233 
234  Returns the number of bytes copied to `dest` or a negative value if
235  some error happens.
236  */
237 DLL_EXPORT int blosc_getitem(const void *src, int start, int nitems, void *dest);
238 
239 
240 /**
241  Initialize a pool of threads for compression/decompression. If
242  `nthreads` is 1, then the serial version is chosen and a possible
243  previous existing pool is ended. If this is not called, `nthreads`
244  is set to 1 internally.
245 
246  Returns the previous number of threads.
247  */
248 DLL_EXPORT int blosc_set_nthreads(int nthreads);
249 
250 
251 /**
252  Select the compressor to be used. The supported ones are "blosclz",
253  "lz4", "lz4hc", "snappy" and "zlib". If this function is not
254  called, then "blosclz" will be used.
255 
256  In case the compressor is not recognized, or there is not support
257  for it in this build, it returns a -1. Else it returns the code for
258  the compressor (>=0).
259  */
260 DLL_EXPORT int blosc_set_compressor(const char* compname);
261 
262 
263 /**
264  Get the `compname` associated with the `compcode`.
265 
266  If the compressor code is not recognized, or there is not support
267  for it in this build, -1 is returned. Else, the compressor code is
268  returned.
269  */
270 DLL_EXPORT int blosc_compcode_to_compname(int compcode, char **compname);
271 
272 
273 /**
274  Return the compressor code associated with the compressor name.
275 
276  If the compressor name is not recognized, or there is not support
277  for it in this build, -1 is returned instead.
278  */
279 DLL_EXPORT int blosc_compname_to_compcode(const char *compname);
280 
281 
282 /**
283  Get a list of compressors supported in the current build. The
284  returned value is a string with a concatenation of "blosclz", "lz4",
285  "lz4hc", "snappy" or "zlib" separated by commas, depending on which
286  ones are present in the build.
287 
288  This function does not leak, so you should not free() the returned
289  list.
290 
291  This function should always succeed.
292  */
294 
295 
296 /**
297  Get info from compression libraries included in the current build.
298  In `compname` you pass the compressor name that you want info from.
299  In `complib` and `version` you get the compression library name and
300  version (if available) as output.
301 
302  In `complib` and `version` you get a pointer to the compressor
303  library name and the version in string format respectively. After
304  using the name and version, you should free() them so as to avoid
305  leaks.
306 
307  If the compressor is supported, it returns the code for the library
308  (>=0). If it is not supported, this function returns -1.
309  */
310 DLL_EXPORT int blosc_get_complib_info(char *compname, char **complib, char **version);
311 
312 
313 /**
314  Free possible memory temporaries and thread resources. Use this
315  when you are not going to use Blosc for a long while. In case of
316  problems releasing the resources, it returns a negative number, else
317  it returns 0.
318  */
320 
321 
322 /**
323  Return information about a compressed buffer, namely the number of
324  uncompressed bytes (`nbytes`) and compressed (`cbytes`). It also
325  returns the `blocksize` (which is used internally for doing the
326  compression by blocks).
327 
328  You only need to pass the first BLOSC_MIN_HEADER_LENGTH bytes of a
329  compressed buffer for this call to work.
330 
331  This function should always succeed.
332  */
333 DLL_EXPORT void blosc_cbuffer_sizes(const void *cbuffer, size_t *nbytes,
334  size_t *cbytes, size_t *blocksize);
335 
336 
337 /**
338  Return information about a compressed buffer, namely the type size
339  (`typesize`), as well as some internal `flags`.
340 
341  The `flags` is a set of bits, where the currently used ones are:
342  * bit 0: whether the shuffle filter has been applied or not
343  * bit 1: whether the internal buffer is a pure memcpy or not
344 
345  You can use the `BLOSC_DOSHUFFLE` and `BLOSC_MEMCPYED` symbols for
346  extracting the interesting bits (e.g. ``flags & BLOSC_DOSHUFFLE``
347  says whether the buffer is shuffled or not).
348 
349  This function should always succeed.
350  */
351 DLL_EXPORT void blosc_cbuffer_metainfo(const void *cbuffer, size_t *typesize,
352  int *flags);
353 
354 
355 /**
356  Return information about a compressed buffer, namely the internal
357  Blosc format version (`version`) and the format for the internal
358  Lempel-Ziv compressor used (`versionlz`).
359 
360  This function should always succeed.
361  */
362 DLL_EXPORT void blosc_cbuffer_versions(const void *cbuffer, int *version,
363  int *versionlz);
364 
365 
366 /**
367  Return the compressor library/format used in a compressed buffer.
368 
369  This function should always succeed.
370  */
371 DLL_EXPORT char *blosc_cbuffer_complib(const void *cbuffer);
372 
373 
374 
375 /*********************************************************************
376 
377  Low-level functions follows. Use them only if you are an expert!
378 
379 *********************************************************************/
380 
381 
382 /**
383  Force the use of a specific blocksize. If 0, an automatic
384  blocksize will be used (the default).
385  */
386 DLL_EXPORT void blosc_set_blocksize(size_t blocksize);
387 
388 #ifdef __cplusplus
389 }
390 #endif
391 
392 
393 #endif
DLL_EXPORT int blosc_set_nthreads(int nthreads)
DLL_EXPORT int blosc_compcode_to_compname(int compcode, char **compname)
#define DLL_EXPORT
Definition: blosc.h:22
GLuint start
Definition: glcorearb.h:474
DLL_EXPORT void blosc_cbuffer_sizes(const void *cbuffer, size_t *nbytes, size_t *cbytes, size_t *blocksize)
DLL_EXPORT int blosc_compress(int clevel, int doshuffle, size_t typesize, size_t nbytes, const void *src, void *dest, size_t destsize)
GLbitfield flags
Definition: glcorearb.h:1595
DLL_EXPORT void blosc_init(void)
DLL_EXPORT void blosc_cbuffer_metainfo(const void *cbuffer, size_t *typesize, int *flags)
DLL_EXPORT int blosc_compname_to_compcode(const char *compname)
DLL_EXPORT void blosc_cbuffer_versions(const void *cbuffer, int *version, int *versionlz)
DLL_EXPORT int blosc_getitem(const void *src, int start, int nitems, void *dest)
DLL_EXPORT void blosc_destroy(void)
DLL_EXPORT int blosc_decompress(const void *src, void *dest, size_t destsize)
DLL_EXPORT int blosc_decompress_ctx(const void *src, void *dest, size_t destsize, int numinternalthreads)
DLL_EXPORT char * blosc_list_compressors(void)
DLL_EXPORT int blosc_compress_ctx(int clevel, int doshuffle, size_t typesize, size_t nbytes, const void *src, void *dest, size_t destsize, const char *compressor, size_t blocksize, int numinternalthreads)
DLL_EXPORT char * blosc_cbuffer_complib(const void *cbuffer)
DLL_EXPORT void blosc_set_blocksize(size_t blocksize)
DLL_EXPORT int blosc_get_complib_info(char *compname, char **complib, char **version)
DLL_EXPORT int blosc_free_resources(void)
DLL_EXPORT int blosc_set_compressor(const char *compname)
GLenum src
Definition: glcorearb.h:1792