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.

Public Members

int16_t nthreads#: The number of threads to use internally (1).

void *schunk#: The associated schunk, if any (NULL).

blosc2_postfilter_fn postfilter#: The postfilter function.

blosc2_postfilter_params *postparams#: The postfilter parameters.

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_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 into destsize, the return value is zero and you should discard the contents of the dest 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 in destsize.

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 from src 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 the dest 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.