Context#
In Blosc 2 there is a special blosc2_context struct that is created from compression and decompression parameters. This allows the compression and decompression to happen in multithreaded scenarios, without the need for using the global lock.
-
struct blosc2_dparams#
The parameters for creating a context for decompression purposes.
In parenthesis it is shown the default value used internally when a 0 (zero) in the fields of the struct is passed to a function.
-
static const blosc2_dparams BLOSC2_DPARAMS_DEFAULTS = {1, NULL, NULL, NULL}#
Default struct for decompression params meant for user initialization.
-
blosc2_context *blosc2_create_cctx(blosc2_cparams cparams)#
Create a context for *_ctx() compression functions.
See also
blosc2_compress
- Parameters:
cparams – The blosc2_cparams struct with the compression parameters.
- Returns:
A pointer to the new context. NULL is returned if this fails.
Note
This supports the same environment variables than blosc2_compress for overriding the programmatic compression values.
-
blosc2_context *blosc2_create_dctx(blosc2_dparams dparams)#
Create a context for *_ctx() decompression functions.
See also
blosc2_decompress
- Parameters:
dparams – The blosc2_dparams struct with the decompression parameters.
- Returns:
A pointer to the new context. NULL is returned if this fails.
Note
This supports the same environment variables than blosc2_decompress for overriding the programmatic decompression values.
-
void blosc2_free_ctx(blosc2_context *context)#
Free the resources associated with a context.
This function should always succeed and is valid for contexts meant for both compression and decompression.
- Parameters:
context – The context to free.
-
int blosc2_compress_ctx(blosc2_context *context, const void *src, int32_t srcsize, void *dest, int32_t destsize)#
Context interface to Blosc compression.
This does not require a call to blosc2_init and can be called from multithreaded applications without the global lock being used, so allowing Blosc be executed simultaneously in those scenarios.
- Parameters:
context – A blosc2_context struct with the different compression params.
src – The buffer containing the data to be compressed.
srcsize – The number of bytes to be compressed from the
src
buffer.dest – The buffer where the compressed data will be put.
destsize – The size in bytes of the
dest
buffer.
- Returns:
The number of bytes compressed. If
src
buffer cannot be compressed intodestsize
, the return value is zero and you should discard the contents of thedest
buffer. A negative return value means that an internal error happened. It could happen that context is not meant for compression (which is stated in stderr). Otherwise, please report it back together with the buffer data causing this and compression settings.
-
int blosc2_decompress_ctx(blosc2_context *context, const void *src, int32_t srcsize, void *dest, int32_t destsize)#
Context interface to Blosc decompression.
This does not require a call to blosc2_init and can be called from multithreaded applications without the global lock being used, so allowing Blosc be executed simultaneously in those scenarios.
Remark
Decompression is memory safe and guaranteed not to write the
dest
buffer more than what is specified indestsize
.Remark
In case you want to keep under control the number of bytes read from source, you can call blosc1_cbuffer_sizes first to check the
nbytes
(i.e. the number of bytes to be read fromsrc
buffer by this function) in the compressed buffer.Remark
If blosc2_set_maskout is called prior to this function, its
block_maskout
parameter will be honored for just one single shot; i.e. the maskout in context will be automatically reset to NULL, so mask won’t be used next time (unless blosc2_set_maskout is called again).- Parameters:
context – The blosc2_context struct with the different compression params.
src – The buffer of compressed data.
srcsize – The length of buffer of compressed data.
dest – The buffer where the decompressed data will be put.
destsize – The size in bytes of the
dest
buffer.
- Returns:
The number of bytes decompressed (i.e. the maskout blocks are not counted). If an error occurs, e.g. the compressed data is corrupted,
destsize
is not large enough or context is not meant for decompression, then a negative value will be returned instead.
Warning
The
src
buffer and thedest
buffer can not overlap.
-
int blosc2_set_maskout(blosc2_context *ctx, bool *maskout, int nblocks)#
Set a maskout so as to avoid decompressing specified blocks.
Remark
The maskout is valid for contexts only meant for decompressing a chunk via blosc2_decompress_ctx. Once a call to blosc2_decompress_ctx is done, this mask is reset so that next call to blosc2_decompress_ctx will decompress the whole chunk.
- Parameters:
ctx – The decompression context to update.
maskout – The boolean mask for the blocks where decompression is to be avoided.
nblocks – The number of blocks in maskout above.
- Returns:
If success, a 0 is returned. An error is signaled with a negative int.
-
int blosc2_getitem_ctx(blosc2_context *context, const void *src, int32_t srcsize, int start, int nitems, void *dest, int32_t destsize)#
Context interface counterpart for blosc1_getitem.
- Parameters:
context – Context pointer.
src – The compressed buffer from data will be decompressed.
srcsize – Compressed buffer length.
start – The position of the first item (of
typesize
size) from where data will be retrieved.nitems – The number of items (of
typesize
size) that will be retrieved.dest – The buffer where the decompressed data retrieved will be put.
destsize – Output buffer length.
- Returns:
The number of bytes copied to
dest
or a negative value if some error happens.
-
int blosc2_ctx_get_cparams(blosc2_context *ctx, blosc2_cparams *cparams)#
Create a
cparams
associated to a context.- Parameters:
ctx – The context from where to extract the compression parameters.
cparams – The pointer where the compression params will be stored.
- Returns:
0 if succeeds. Else a negative code is returned.
-
int blosc2_ctx_get_dparams(blosc2_context *ctx, blosc2_dparams *dparams)#
Create a
dparams
associated to a context.- Parameters:
ctx – The context from where to extract the decompression parameters.
dparams – The pointer where the decompression params will be stored.
- Returns:
0 if succeeds. Else a negative code is returned.