Compress, decompress, and configure pressio and lossless compressors. More...

#include "stddef.h"

Include dependency graph for pressio_compressor.h:

This graph shows which files directly or indirectly include this file:

Enumerations
enum	pressio_thread_safety { pressio_thread_safety_single = 0 , pressio_thread_safety_serialized = 1 , pressio_thread_safety_multiple = 2 }

Functions
void	pressio_compressor_release (struct pressio_compressor *compressor)

struct pressio_options *	pressio_compressor_get_documentation (struct pressio_compressor const *compressor)

struct pressio_options *	pressio_compressor_get_configuration (struct pressio_compressor const *compressor)

struct pressio_options *	pressio_compressor_get_options (struct pressio_compressor const *compressor)

int	pressio_compressor_set_options (struct pressio_compressor compressor, struct pressio_options const options)

int	pressio_compressor_check_options (struct pressio_compressor compressor, struct pressio_options const options)

int	pressio_compressor_compress (struct pressio_compressor compressor, const struct pressio_data input, struct pressio_data *output)

int	pressio_compressor_decompress (struct pressio_compressor compressor, const struct pressio_data input, struct pressio_data *output)

struct pressio_options *	pressio_compressor_get_metrics_results (struct pressio_compressor const *compressor)

struct pressio_metrics *	pressio_compressor_get_metrics (struct pressio_compressor const *compressor)

void	pressio_compressor_set_metrics (struct pressio_compressor compressor, struct pressio_metrics plugin)

struct pressio_options *	pressio_compressor_metrics_get_options (struct pressio_compressor const *compressor)

int	pressio_compressor_metrics_set_options (struct pressio_compressor const compressor, struct pressio_options const options)

int	pressio_compressor_error_code (struct pressio_compressor const *compressor)

const char *	pressio_compressor_error_msg (struct pressio_compressor const *compressor)

const char *	pressio_compressor_version (struct pressio_compressor const *compressor)

int	pressio_compressor_major_version (struct pressio_compressor const *compressor)

int	pressio_compressor_minor_version (struct pressio_compressor const *compressor)

int	pressio_compressor_patch_version (struct pressio_compressor const *compressor)

struct pressio_compressor *	pressio_compressor_clone (struct pressio_compressor *compressor)

const char *	pressio_compressor_get_prefix (const struct pressio_compressor *compressor)

void	pressio_compressor_set_name (struct pressio_compressor compressor, const char new_name)

const char *	pressio_compressor_get_name (struct pressio_compressor const *compressor)

int	pressio_compressor_compress_many (struct pressio_compressor compressor, struct pressio_data const const in[], size_t num_inputs, struct pressio_data *out[], size_t num_outputs)

int	pressio_compressor_decompress_many (struct pressio_compressor compressor, struct pressio_data const const in[], size_t num_inputs, struct pressio_data *out[], size_t num_outputs)

Detailed Description

Compress, decompress, and configure pressio and lossless compressors.

Enumeration Type Documentation

◆ pressio_thread_safety

enum pressio_thread_safety

reports the level of thread safety supported by the compressor.

Compressors MUST report a thread safety by setting the pressio:thread_safe option on the object returned by get_configuration and the level supported by the plug-in.

Safety is defined in terms of if the both of the following sequence of calls from multiple threads can be made without a data race:

pressio_compressor_get_options(...)

pressio_compressor_set_options(...)

pressio_compressor_set_options

int pressio_compressor_set_options(struct pressio_compressor *compressor, struct pressio_options const *options)

pressio_compressor_get_options

struct pressio_options * pressio_compressor_get_options(struct pressio_compressor const *compressor)

and

pressio_compressor_get_options(...)

pressio_compressor_set_options(...)

and

pressio_compressor_set_options(...)
pressio_compressor_compress(...)
pressio_compressor_error_code(...)
pressio_compressor_error_msg(...)

and

pressio_compressor_set_options(...)
pressio_compressor_decompress(...)
pressio_compressor_error_code(...)
pressio_compressor_error_msg(...)

All metrics plugins MUST support pressio_thread_safety_multiple (i.e. safe as long as different objects are used)

Enumerator
pressio_thread_safety_single	use of this compressor in a multi-threaded environment is unsafe.
pressio_thread_safety_serialized	calls are safe if and only if only one thread will execute the above sequences of calls to any instance of the compressor at a time
pressio_thread_safety_multiple	calls are safe if and only if only one thread will execute the above sequences of calls to an instance of the compressor at a time

Function Documentation

◆ pressio_compressor_check_options()

int pressio_compressor_check_options	(	struct pressio_compressor *	compressor,
		struct pressio_options const *	options
	)

Validates that only defined options have been set. This can be useful for programmer errors. This function should NOT be used with any option structure which contains options for multiple compressors. Other checks MAY be preformed implementing compressors.

Parameters

[in]	compressor	which compressor to validate the options struct against
[in]	options	which options set to check against. It should ONLY contain options returned by pressio_compressor_get_options

Returns: 0 if successful, 1 if there is an error. On error, an error message is set in pressio_compressor_error_msg.

See also: pressio_compressor_error_msg to get the error message

◆ pressio_compressor_clone()

struct pressio_compressor * pressio_compressor_clone ( struct pressio_compressor * compressor )

Clones a compressor and its configuration including metrics information

Parameters

[in] compressor the compressor to clone. It will not be modified except to modify a reference count as needed.

Returns: a pointer to a new compressor plugin reference which is equivalent to the compressor cloned. It the compressor is not thread safe, it may return a new reference to the same object.

◆ pressio_compressor_compress()

int pressio_compressor_compress	(	struct pressio_compressor *	compressor,
		const struct pressio_data *	input,
		struct pressio_data *	output
	)

compresses the data in data using the specified compressor

Parameters

[in]	compressor	compressor to be used
[in]	input	data to be compressed and associated metadata
[in,out]	output	when passed in, `output` MAY contain metadata (type, dimentions) and additionally MAY contain a buffer. pressio_data_free will be called on the pointer passed into this function if a new owning pressio_data structure is returned. when passed out, `output` will contain either: The same pointer passed in to `output` if the compressor supports using a provided buffer for the results of the compression and contains has a buffer. It is recommended the user provide an owning pressio_data structure if passing a pressio_data structure with a buffer. A new owning pressio_data structure with the results of the compression

Returns: 0 if successful, positive values on errors, negative values on warnings

◆ pressio_compressor_compress_many()

int pressio_compressor_compress_many	(	struct pressio_compressor *	compressor,
		struct pressio_data const *const	in[],
		size_t	num_inputs,
		struct pressio_data *	out[],
		size_t	num_outputs
	)

compress multiple data buffers in one api call. Underlying implementations may do this in serial or parallel

Parameters

[in]	compressor	the compressor object that will perform compression
[in]	in	array of input buffers
[in]	num_inputs	the number of elements of the "in" array
[in,out]	out	array of compressed data buffers When passed in, each element of out MAY contain metadata (type, dimentions), and may additionally contain a buffer. pressio_data_free will need to be called on the object returned from this buffer. When passed out, each elements of out will contain either The same pointer passed in to `output` if the compressor supports using a provided buffer for the results of the compression and contains has a buffer. It is recommended the user provide an owning pressio_data structure if passing a pressio_data structure with a buffer. A new owning pressio_data structure with the results of the compression
[in]	num_outputs	the number of elements of the "out" array

Returns: 0 if successful, 1 if there is an error. On error, an error message is set in pressio_compressor_error_msg.

◆ pressio_compressor_decompress()

int pressio_compressor_decompress	(	struct pressio_compressor *	compressor,
		const struct pressio_data *	input,
		struct pressio_data *	output
	)

decompresses the compressed data using the specified compressor calling this without calling libpressio_compressor_set_options() has undefined behavior decompressing with a compressor with different settings than used for compression has undefined behavior

Parameters

[in]	compressor	compressor to be used
[in]	input	data to be decompressed and associated metadata
[in,out]	output	when passed in, `output` SHOULD contain the metadata (type, dimentions) for the output of the compression if available. pressio_data_free will be called the pointer passed in during this function. when passed out, it will contain either The same pointer passed in to `output` if the compressor supports using a provided buffer for the results of the compression and contains has a buffer. It is recommended the user provide an owning pressio_data structure if passing a pressio_data structure with a buffer. A new owning pressio_data structure with the results of the compression

Returns: 0 if successful, positive values on errors, negative values on warnings

See also: pressio_data_new_empty often used as the pointer passed into output; pressio_data_new_move often used as the pointer passed out of output

◆ pressio_compressor_decompress_many()

int pressio_compressor_decompress_many	(	struct pressio_compressor *	compressor,
		struct pressio_data const *const	in[],
		size_t	num_inputs,
		struct pressio_data *	out[],
		size_t	num_outputs
	)

decompress multiple data buffers in one api call. Underlying implementations may do this in serial or parallel

Parameters

[in]	compressor	the compressor object that will perform compression
[in]	in	array of input buffers
[in]	num_inputs	the number of elements of the "in" array
[in,out]	out	array of compressed data buffers When passed in, each element of out MAY contain metadata (type, dimentions), and may additionally contain a buffer. pressio_data_free will need to be called on the object returned from this buffer. When passed out, each elements of out will contain either The same pointer passed in to `output` if the compressor supports using a provided buffer for the results of the compression and contains has a buffer. It is recommended the user provide an owning pressio_data structure if passing a pressio_data structure with a buffer. A new owning pressio_data structure with the results of the compression
[in]	num_outputs	the number of elements of the "out" array

Returns: 0 if successful, 1 if there is an error. On error, an error message is set in pressio_compressor_error_msg.

◆ pressio_compressor_error_code()

int pressio_compressor_error_code ( struct pressio_compressor const * compressor )

Parameters

[in] compressor the compressor to query

Returns: last error code for the compressor

◆ pressio_compressor_error_msg()

const char * pressio_compressor_error_msg ( struct pressio_compressor const * compressor )

Parameters

[in] compressor the compressor to query

Returns: last error message for the compressor

◆ pressio_compressor_get_configuration()

struct pressio_options * pressio_compressor_get_configuration ( struct pressio_compressor const * compressor )

Returns: a pressio options struct that represents the compile time configuration of the compressor

Parameters

[in] compressor which compressor to get compile-time configuration for

◆ pressio_compressor_get_documentation()

struct pressio_options * pressio_compressor_get_documentation ( struct pressio_compressor const * compressor )

Returns: a pressio options struct that represents the documentation for the compressor

Parameters

[in] compressor which compressor to get documentation for

◆ pressio_compressor_get_metrics()

struct pressio_metrics * pressio_compressor_get_metrics ( struct pressio_compressor const * compressor )

Parameters

[in] compressor the compressor to get the metrics plugin for

Returns: the current pressio_metrics* structure

◆ pressio_compressor_get_metrics_results()

struct pressio_options * pressio_compressor_get_metrics_results ( struct pressio_compressor const * compressor )

Parameters

[in] compressor the compressor to get results from

Returns: a pressio_options structure containing the metrics returned by the provided metrics plugin

See also: libpressio_metricsplugin for how to compute results

◆ pressio_compressor_get_name()

const char * pressio_compressor_get_name ( struct pressio_compressor const * compressor )

Get the name of a compressor

Parameters

[in] compressor the compressor to get the name of

Returns: a string with the compressor name. The string becomes invalid if the name is set_name is called.

◆ pressio_compressor_get_options()

struct pressio_options * pressio_compressor_get_options ( struct pressio_compressor const * compressor )

Returns: a pressio options struct that represents the current options of the compressor

Parameters

[in] compressor which compressor to get options for

◆ pressio_compressor_get_prefix()

const char * pressio_compressor_get_prefix ( const struct pressio_compressor * compressor )

Returns the name this compressor uses its keys

Parameters

[in] compressor the compressor to get the prefix for

Returns: the prefix for this compressor

◆ pressio_compressor_major_version()

int pressio_compressor_major_version ( struct pressio_compressor const * compressor )

Parameters

[in] compressor the compressor to query

Returns: the major version number or 0 if there is none

◆ pressio_compressor_metrics_get_options()

struct pressio_options * pressio_compressor_metrics_get_options ( struct pressio_compressor const * compressor )

Gets the options for a metrics structure

Parameters

[in] compressor the metrics structure to get options for

Returns: a new pressio_options structure with the options for the metrics

◆ pressio_compressor_metrics_set_options()

int pressio_compressor_metrics_set_options	(	struct pressio_compressor const *	compressor,
		struct pressio_options const *	options
	)

Gets the options for a metrics structure

Parameters

[in]	compressor	the compressor structure to get metrics options for
[in]	options	the options to set

Returns: 0 if successful, positive values on errors, negative values on warnings

◆ pressio_compressor_minor_version()

int pressio_compressor_minor_version ( struct pressio_compressor const * compressor )

Parameters

[in] compressor the compressor to query

Returns: the major version number or 0 if there is none

◆ pressio_compressor_patch_version()

int pressio_compressor_patch_version ( struct pressio_compressor const * compressor )

Parameters

[in] compressor the compressor to query

Returns: the major version number or 0 if there is none

◆ pressio_compressor_release()

void pressio_compressor_release ( struct pressio_compressor * compressor )

Parameters

[in] compressor deallocates a reference to a compressor.

◆ pressio_compressor_set_metrics()

void pressio_compressor_set_metrics	(	struct pressio_compressor *	compressor,
		struct pressio_metrics *	plugin
	)

Parameters

[in]	compressor	the compressor to set metrics plugin for
[in]	plugin	the configured libpressio_metricsplugin plugin to use

◆ pressio_compressor_set_name()

void pressio_compressor_set_name	(	struct pressio_compressor *	compressor,
		const char *	new_name
	)

Assign a new name to a compressor. Names are used to prefix options in meta-compressors.

sub-compressors will be renamed either by the of the sub-compressors prefix or by the $prefix:name configuration option

i.e. for some new_name and a compressor with prefix foo and subcompressors with prefixs "abc", "def", "ghi" respectively

if foo:names = ['one', 'two', 'three'], then the names will be `$new_name/one, $new_name/two $new_name/three
otherwise the names will be $new_name/abc, $new_name/def, $new_name/ghi

Parameters

[in]	compressor	the compressor to get the name of
[in]	new_name	the name to set

◆ pressio_compressor_set_options()

int pressio_compressor_set_options	(	struct pressio_compressor *	compressor,
		struct pressio_options const *	options
	)

sets the options for the pressio_compressor. Compressors MAY choose to ignore some subset of options passed in if there valid but conflicting settings (i.e. two settings that adjust the same underlying configuration). Additionally, if one of the two settings is a generic one (i.e. pressio:abs) the compressor specific version should prevail. Compressors SHOULD return an error value if configuration failed due to a missing required setting or an invalid one. Users MAY call pressio_compressor_error_msg() to get more information about the warnings or errors Compressors MUST ignore any and all options set that they do not support.

Parameters

[in]	compressor	which compressor to get options for
[in]	options	the options to set

Returns: 0 if successful, positive values on errors, negative values on warnings

See also: pressio_compressor_error_msg

◆ pressio_compressor_version()

const char * pressio_compressor_version ( struct pressio_compressor const * compressor )

Get the version and feature information. The version string may include more information than major/minor/patch provide.

Parameters

[in] compressor the compressor to query

Returns: a implementation specific version string

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ pressio_thread_safety

Function Documentation

◆ pressio_compressor_check_options()

◆ pressio_compressor_clone()

◆ pressio_compressor_compress()

◆ pressio_compressor_compress_many()

◆ pressio_compressor_decompress()

◆ pressio_compressor_decompress_many()

◆ pressio_compressor_error_code()

◆ pressio_compressor_error_msg()

◆ pressio_compressor_get_configuration()

◆ pressio_compressor_get_documentation()

◆ pressio_compressor_get_metrics()

◆ pressio_compressor_get_metrics_results()

◆ pressio_compressor_get_name()

◆ pressio_compressor_get_options()

◆ pressio_compressor_get_prefix()

◆ pressio_compressor_major_version()

◆ pressio_compressor_metrics_get_options()

◆ pressio_compressor_metrics_set_options()

◆ pressio_compressor_minor_version()

◆ pressio_compressor_patch_version()

◆ pressio_compressor_release()

◆ pressio_compressor_set_metrics()

◆ pressio_compressor_set_name()

◆ pressio_compressor_set_options()

◆ pressio_compressor_version()