Skip to main content
`Ctrl`+`K`

# 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_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 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.