InternalZGY::NullCompressPlugin Class Reference

Example compression plug-in that always fails to compress. More...

Classes
class	Register
	Register the compress and decompress functions in the factory. More...

Static Public Member Functions
static compressor_t	getCompressor (const std::vector< std::string > &)
	Get a functor for compressing data. More...
static rawdata_t	compress (const rawdata_t &data, const index3_t &shape)
	Compress using the chosen algorithm. More...
static rawdata_t	decompress (const rawdata_t &cdata, const BrickStatus &status, const index3_t &shape)
	Decompress data if it was compressed by our algorithm. More...

Detailed Description

Example compression plug-in that always fails to compress.

This class is here just as an example and for documentation. Real compression classes may use "copydoc" instead of repeating what is explained here.

Member Function Documentation

compress()

static rawdata_t InternalZGY::NullCompressPlugin::compress ( const rawdata_t &  data, const index3_t &  shape  )

static

Compress using the chosen algorithm.

Parameters

data	Smart pointer to data, and size in bytes of data.
shape	hint for 3d layout of data in number of samples.

Returns

Data in the same format as the input.

The number and type of parameters, except for the first one, varies depending on the algorithm being used. Some algorithms might not need additional parameters at all.

Current assumptions that apply to all compression algorithms. Except for the one about thread safety these are subject to change.

• The method must be thread safe.

• The algorithm is responsible any for big / little endian conversion.

• The compressed data stream must never be larger than the uncompressed data. If it looks like this is going to happen then just return {nullptr, 0} telling the caller that compression is not possible.

• If the algorithm decides that compression is inadvisable for other reasons, such as NaN or Inf in the data, it is also acceptable to return {nullptr, 0}. Never return the input data unchanged because this will then be flagged as compressed. And the uncompress algorithm will fail miserably.

• The compressed data stream should start with a magic number that the decompressor can recognize.

decompress()

static rawdata_t InternalZGY::NullCompressPlugin::decompress ( const rawdata_t &  cdata, const BrickStatus &  status, const index3_t &  shape  )

static

Decompress data if it was compressed by our algorithm.

Parameters

cdata	Compressed data, possibly with trailing garbage.
status	Might be used to identfy which algorithm was used.
shape	rank and size in samples of the uncompressed result.

The algorithm should check both the status argument and any magic number at the start of the buffer to decide whether this is data we know how to decompress. If not then return {nullptr, 0} which should make the caller try something else.

If the algorithm is recognized but the data cannot be decompressed because it is corrupt then the method may throw an exception. In that case no further algorithms will be tried.

Older versions of this function also received the value type of the data that was compressed and the value type we want it returned in This is now redundant since we only allow compressing float data. Anything else is simply not useful.

Passing an uncompressed brick to this function is an error. I.e. status will never be Normal. We don't have enough context to handle uncompressed bricks that might require byteswapping and fix for legacy quirks. Also cannot handle constant bricks, missing bricks, etc.

Current assumptions that apply to all decompression algorithms. Except for the one about thread safety these are subject to change.

• The method must be thread safe.

• The compressed data stream is allowed to have trailing garbage; this must be silently ignored by the decompressor.

• The algorith may assume that the compressed data stream will never be longer than the uncompressed data. This is enforced by the compressor.

• The reason for the two assumptions above is an implementation detail. The reported size of a compressed brick isn't completely reliable. This might change in the next version of the file format.

• The decompressor must verify that both the status (usually set to BrickStatus.Compressed) and the magic number at the start of the compressed stream matches is correct. Relying on only status is currently not sufficient because all compressed bricks get the same status.

getCompressor()

static compressor_t InternalZGY::NullCompressPlugin::getCompressor ( const std::vector< std::string > &  )

static

Get a functor for compressing data.

Parse the stringly typed arguments that the factory sent us. Do a consistency check on the arguments. Capture the now strongly typed compressor arguments in a lambda that can be used to compress one block of data.

The returned lambda function is supposed to be thread safe.

The return is allowed to be an empty function. The caller will treat this as if no compression had been requested. This is not precisely the same as returning a factor that always returns "I give up". The latter case would limit the file to float32 type and might turn off alignments in the file.

If the compressor needs mutable state, e.g. to accumulate perfromance measurements, it can be declared as an instance method allowing the lambda to capture "this". The class would normally be noncopyable. The returned lambda can be copied at will; the copies will share the same state. Remember to use locks to protect the shared state in "this".

Another option for mutable state is to have this function allocate some kind of "state" instance and capture it in the lambda. How to access that state later, e.g. to extract any timing measurements, is left as an exercise ;-).

---

The documentation for this class was generated from the following file:

• impl/compress_null.cpp