Packmatic.Compressor behaviour (Packmatic v2.1.0)

Copy Markdown View Source

The Compressor is responsible for compressing source data for placement into the Zip archive. The Zip format supports different types of compression methods, so many different Compressors can be created, as long as they conform to the behaviour.

Summary

Types

data()
init_arg()
state()
t()

Represents a Compressor being used in the Encoder.

Callbacks

close(state)

Closes down the Compressor at end of input stream. This is called when the input has been fully read (hit EOF) or further data is otherwise no longer expected for the input. When called, the Compressor may take the opportunity to emit a final part of the data stream, flushing its internal buffers. The Compressor is expected to then have emitted the entire data stream that can be used to reconstruct the input.

finalise(state)

Closes the compressor for good. All external resources should be released here; no further calls will be made by the Encoder past this point. Prior to this call, close/1 should have been invoked to mark the end of a previous stream, so the Compressor is not expected to emit any further data.

next(state, data)

Iterates the Compressor with the incoming data, compresses it and emits both the compressed data, and if necessary, an updated state.

open(init_arg)

Initialises a Compressor with the initialisation argument specified in Entries. If such an argument was not specified then it should have been normalised to []. The Compressor has the opportunity to emit the initial part of the data stream here.

reset(state, init_arg)

Closes the internal compression stream for the previous item and re-opens the Compressor for the next item. Functionally this would be identical to calling close/1 and open/1, but in practice this callback is used to facilitate preservation of external resources that may be costly to open and close when compressing many items.

Functions

build(compressor, compression_method)

Opens or resets the Compressor with the optional Initialisation Argument as specified in the Entry for a new file to be compressed.

close(arg)
finalise(arg)
next(arg, data)
reset(arg)

Types

data()

@type data() :: iodata()

init_arg()

@type init_arg() :: term()

state()

@type state() :: term()

t()

@opaque t()

Represents a Compressor being used in the Encoder.

Callbacks

close(state)

@callback close(state()) :: {:ok, data(), state()} | {:error, reason :: term()}

Closes down the Compressor at end of input stream. This is called when the input has been fully read (hit EOF) or further data is otherwise no longer expected for the input. When called, the Compressor may take the opportunity to emit a final part of the data stream, flushing its internal buffers. The Compressor is expected to then have emitted the entire data stream that can be used to reconstruct the input.

After close/1, the Encoder may call reset/2 again to compress a new input stream, or call finalise/1 to close the Compressor down for good.

finalise(state)

@callback finalise(state()) :: :ok | {:error, reason :: term()}

Closes the compressor for good. All external resources should be released here; no further calls will be made by the Encoder past this point. Prior to this call, close/1 should have been invoked to mark the end of a previous stream, so the Compressor is not expected to emit any further data.

next(state, data)

@callback next(state(), data()) :: {:ok, data(), state()} | {:error, reason :: term()}

Iterates the Compressor with the incoming data, compresses it and emits both the compressed data, and if necessary, an updated state.

open(init_arg)

@callback open(init_arg()) :: {:ok, data(), state()} | {:error, reason :: term()}

Initialises a Compressor with the initialisation argument specified in Entries. If such an argument was not specified then it should have been normalised to []. The Compressor has the opportunity to emit the initial part of the data stream here.

reset(state, init_arg)

@callback reset(state(), init_arg()) ::
  {:ok, data(), state()} | {:error, reason :: term()}

Closes the internal compression stream for the previous item and re-opens the Compressor for the next item. Functionally this would be identical to calling close/1 and open/1, but in practice this callback is used to facilitate preservation of external resources that may be costly to open and close when compressing many items.

Functions

build(compressor, compression_method)

@spec build(
  compressor :: t() | nil,
  compression_method :: Packmatic.Manifest.Entry.method()
) ::
  {:ok, data(), compressor :: t()} | {:error, reason :: term()}

Opens or resets the Compressor with the optional Initialisation Argument as specified in the Entry for a new file to be compressed.

If the new Compression Method will result in the same Compressor being used again, then the existing Compressor will be reset (via reset/2); this may result in the existing Compressor being reused:

  1. If the new Compression Method requires a different Compressor, for example the method was :store but is then changed to :deflate for the subsequent entry, then the old Compressor will be closed and a new one will be opened in all scenarios.

  2. If the new Compression Method is resolved to the same Compressor, regardless of whether the Initialisation Argument is the same, reset/2 will be called and it would be up to the relevant callback module to handle this.

Called by Packmatic.Encoder.

close(arg)

finalise(arg)

next(arg, data)

reset(arg)