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_cparams

The parameters for creating a context for compression 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

uint8_t compcode

The compressor codec.

uint8_t compcode_meta

The metadata for the compressor codec.

uint8_t clevel

The compression level (5).

int use_dict

Use dicts or not when compressing (only for ZSTD).

int32_t typesize

The type size (8).

int16_t nthreads

The number of threads to use internally (1).

int32_t blocksize

The requested size of the compressed blocks (0; meaning automatic).

int32_t splitmode

Whether the blocks should be split or not.

void *schunk

The associated schunk, if any (NULL).

uint8_t filters[BLOSC2_MAX_FILTERS]

The (sequence of) filters.

uint8_t filters_meta[BLOSC2_MAX_FILTERS]

The metadata for filters.

blosc2_prefilter_fn prefilter

The prefilter function.

blosc2_prefilter_params *preparams

The prefilter parameters.

blosc2_btune *udbtune

The user-defined BTune parameters.

static const blosc2_cparams BLOSC2_CPARAMS_DEFAULTS   = {         BLOSC_BLOSCLZ, 0, 5, 0, 8, 1, 0, BLOSC_FORWARD_COMPAT_SPLIT,NULL, {0, 0, 0, 0, 0,BLOSC_SHUFFLE}, {0, 0, 0, 0, 0, 0},NULL, NULL, NULL}

Default struct for compression params meant for user initialization.

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.

Parameters
  • cparams – The blosc2_cparams struct with the compression parameters.

Returns

A pointer to the new context. NULL is returned if this fails.

blosc2_context *blosc2_create_dctx(blosc2_dparams dparams)

Create a context for *_ctx() decompression functions.

Parameters
  • dparams – The blosc2_dparams struct with the decompression parameters.

Returns

A pointer to the new context. NULL is returned if this fails.

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 blosc_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 blosc_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 blosc_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 values 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 blosc_getitem.

It uses many of the same parameters as blosc_getitem() function with a few additions.

Parameters
  • context – Context pointer.

  • srcsize – Compressed buffer length.

  • 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
  • schunk – 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
  • schunk – 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.