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.

int32_t typesize#: The type size (8).

static const blosc2_dparams BLOSC2_DPARAMS_DEFAULTS = {1, NULL, NULL, NULL, 8}#: 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. If src is a lazy chunk returned by blosc2_schunk_get_lazychunk, pass the size returned by blosc2_schunk_get_lazychunk here rather than the cbytes value reported by blosc2_cbuffer_sizes.
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_vlcompress_ctx(blosc2_context *context, const void *const *srcs, const int32_t *srcsizes, int32_t nblocks, void *dest, int32_t destsize)#

Context interface to Blosc compression for chunks with variable-length blocks.

Parameters:

context – A blosc2_context struct with the different compression params.
srcs – A list of pointers, one per block.
srcsizes – A list of uncompressed sizes, one per block.
nblocks – The number of blocks in the chunk.
dest – The buffer where the compressed chunk will be put.
destsize – The size in bytes of the dest buffer.

Returns:

The number of bytes compressed, or a negative error code.

int blosc2_vldecompress_ctx(blosc2_context *context, const void *src, int32_t srcsize, void **dests, int32_t *destsizes, int32_t maxblocks)#

Context interface to Blosc decompression for chunks with variable-length blocks.

Parameters:

context – The blosc2_context struct with the different decompression params.
src – The buffer of compressed data.
srcsize – The length of buffer of compressed data.
dests – On output, one newly allocated buffer per block.
destsizes – On output, the uncompressed sizes of the blocks.
maxblocks – The number of entries available in dests and destsizes.

Returns:

The number of blocks decompressed, or a negative error code.

int blosc2_vldecompress_block_ctx(blosc2_context *context, const void *src, int32_t srcsize, int32_t nblock, uint8_t **dest, int32_t *destsize)#

Decompress a single variable-length block from a VL-block chunk.

Only the requested block is decompressed and allocated; all other blocks in the chunk are untouched.

Parameters:

context – A decompression context (blosc2_context created with blosc2_create_dctx). If src is a lazy chunk (obtained via blosc2_schunk_get_lazychunk), the caller must set context->schunk to the owning super-chunk (which must have an associated frame) before calling this function; the frame is used to read block data from disk.
src – The buffer of compressed data. Must carry the BLOSC2_VL_BLOCKS flag. May be a fully in-memory chunk or a lazy chunk proxy.
srcsize – The length of the compressed data buffer.
nblock – Zero-based index of the block to decompress.
dest – On success, points to a newly allocated buffer containing the decompressed block. The caller is responsible for freeing this buffer with free().
destsize – On success, the uncompressed byte size of the block.

Returns:

The uncompressed byte size of the block on success, or a negative error code. Returns BLOSC2_ERROR_INVALID_PARAM if the chunk does not use VL blocks or if nblock is out of range.

int blosc2_vlchunk_get_nblocks(const void *src, int32_t srcsize, int32_t *nblocks)#

Return the number of variable-length blocks stored in a VL-block chunk.

This is a header-only query: it reads only the chunk header and does not allocate or decompress anything.

Parameters:

src – The buffer of compressed data. Must carry the BLOSC2_VL_BLOCKS flag.
srcsize – The length of the compressed data buffer.
nblocks – On success, the number of VL blocks in the chunk.

Returns:

0 on success, or a negative error code. Returns BLOSC2_ERROR_INVALID_PARAM if the chunk does not use VL blocks.

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. If src is a lazy chunk returned by blosc2_schunk_get_lazychunk, pass the size returned by blosc2_schunk_get_lazychunk here rather than the cbytes value reported by blosc2_cbuffer_sizes.
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.

blosc2_cparams blosc2_get_blosc2_cparams_defaults(void)#: Get default struct for compression params meant for user initialization.

blosc2_dparams blosc2_get_blosc2_dparams_defaults(void)#: Get default struct for decompression params meant for user initialization.

const char *blosc2_error_string(int error_code)#

Get the string representation of an error code.

The returned string is a static string, so it should not be modified or freed. For unknown error codes, it returns “Unknown error”.

Parameters:

error_code – The error code to get the string representation for.

Returns:

A pointer to a static string representing the error code.