Abstract base class for compressors. More...

#include <compressor.h>

Inheritance diagram for binary_log::transaction::compression::Compressor:

Public Types
using	Managed_buffer_sequence_t = mysqlns::buffer::Managed_buffer_sequence<>

using	Char_t = Managed_buffer_sequence_t::Char_t

using	Size_t = Managed_buffer_sequence_t::Size_t

using	Grow_constraint_t = mysqlns::buffer::Grow_constraint

Public Member Functions
	Compressor ()=default

	Compressor (const Compressor &other)=delete

	Compressor (Compressor &&other)=delete

Compressor &	operator= (const Compressor &other)=delete

Compressor &	operator= (Compressor &&other)=delete

virtual	~Compressor ()=default

type	get_type_code () const

void	reset ()
	Reset the frame. More...

template<class Input_char_t >
void	feed (const Input_char_t *input_data, Size_t input_size)
	Submit data to be compressed. More...

Compress_status	compress (Managed_buffer_sequence_t &out)
	Consume all input previously given in the feed function. More...

Compress_status	finish (Managed_buffer_sequence_t &out)
	Consume all input, produce all output, and end the frame. More...

Grow_constraint_t	get_grow_constraint_hint () const
	Return a `Grow_constraint` that may be used with the Managed_buffer_sequence storing the output, in order to optimize memory usage for a particular compression algorithm. More...

void	set_pledged_input_size (Size_t size)
	Declare that the input size will be exactly as given. More...

Size_t	get_pledged_input_size () const
	Return the size previously provided to `set_pledged_input_size`, or `pledged_input_size_unset` if no pledged size has been set. More...

Static Public Attributes
static constexpr Size_t	pledged_input_size_unset

Private Member Functions
void	feed_char_t (const Char_t *input_data, Size_t input_size)
	Worker function for `feed`, requiring the correct Char_t type. More...

virtual type	do_get_type_code () const =0
	implement `get_type_code`. More...

virtual void	do_reset ()=0
	Implement `reset`. More...

virtual void	do_feed (const Char_t *input_data, Size_t input_size)=0
	Implement `feed`. More...

virtual Compress_status	do_compress (Managed_buffer_sequence_t &out)=0
	Implement `compress`. More...

virtual Compress_status	do_finish (Managed_buffer_sequence_t &out)=0
	Implement `finish`. More...

virtual Grow_constraint_t	do_get_grow_constraint_hint () const
	Implement `get_grow_constraint_hint`. More...

virtual void	do_set_pledged_input_size (Size_t size)
	Implement `set_pledged_input_size`. More...

Private Attributes
bool	m_pending_input = false
	True when user has provided input that has not yet been consumed. More...

bool	m_empty = true
	True when user has not provided any input since the last reset. More...

Size_t	m_pledged_input_size = pledged_input_size_unset
	The number of bytes. More...

Detailed Description

Abstract base class for compressors.

Each subclass normally corresponds to a compression algorithm, and maintains the algorithm-specific state for it.

An instance of this class can be reused to compress several frames. A frame is a self-contained segment of data, in the sense that it can be decompressed without knowing about other frames, and compression does not take advantage of patterns that repeat between frames.

Input for a frame can be provided in pieces. All pieces for a frame will be compressed together; the decompressor will take advantage of patterns across in different pieces within the frame. Providing a frame in pieces is useful when not all input is known at once.

To compress one frame, use the API as follows:

Repeat as many times as needed: 1.1. Call feed to provide a piece of input. 1.2. Call compress to consume the piece of input and possibly produce a prefix of the output.
Choose one of the following: 2.1. Call finish to produce the remainder of the output for this frame. 2.2. Call reset to abort this frame.

Note: After 1.2, although the compression library has read all input given so far, it may not have produced all corresponding output. It usually holds some data in internal buffers, since it may be more compressible when more data has been given. Therefore, step 2.1 is always necessary in order to complete the frame.; To reuse the compressor object for another input, repeat the above procedure as many times as needed.

This class requires that the user provides a mysqlns::buffer::Managed_buffer_sequence to store output.

Member Typedef Documentation

◆ Char_t

using binary_log::transaction::compression::Compressor::Char_t = Managed_buffer_sequence_t::Char_t

◆ Grow_constraint_t

using binary_log::transaction::compression::Compressor::Grow_constraint_t = mysqlns::buffer::Grow_constraint

◆ Managed_buffer_sequence_t

using binary_log::transaction::compression::Compressor::Managed_buffer_sequence_t = mysqlns::buffer::Managed_buffer_sequence<>

◆ Size_t

using binary_log::transaction::compression::Compressor::Size_t = Managed_buffer_sequence_t::Size_t

Constructor & Destructor Documentation

◆ Compressor() [1/3]

binary_log::transaction::compression::Compressor::Compressor ( )

default

◆ Compressor() [2/3]

binary_log::transaction::compression::Compressor::Compressor ( const Compressor & other )

delete

◆ Compressor() [3/3]

binary_log::transaction::compression::Compressor::Compressor ( Compressor && other )

delete

◆ ~Compressor()

virtual binary_log::transaction::compression::Compressor::~Compressor ( )

virtualdefault

Member Function Documentation

◆ compress()

Compress_status binary_log::transaction::compression::Compressor::compress ( Managed_buffer_sequence_t & out )

Consume all input previously given in the feed function.

This will consume the input, but may not produce all output; there may be output still in compression library buffers. Use the finish function to flush the output and end the frame.

Parameters

out	Storage for compressed bytes. This may grow, if needed.

Return values

success	All input was consumed.
out_of_memory	The operation failed due to an out of memory error. The frame has been reset.
exceeds_max_size	The `out` buffer was already at its max capacity, and filled, and there were more bytes left to produce. The frame has not been reset and it is not guaranteed that all input has been consumed. The caller may resume compression e.g. after increasing the capacity, or resetting the output buffer (perhaps after moving existing data elsewhere), or using a different output buffer, or similar.

◆ do_compress()

virtual Compress_status binary_log::transaction::compression::Compressor::do_compress ( Managed_buffer_sequence_t & out )

privatepure virtual

Implement compress.

This differs from compress in that it does not have to reset the frame when returning out_of_memory; the caller does that.

Implemented in binary_log::transaction::compression::None_comp, and binary_log::transaction::compression::Zstd_comp.

◆ do_feed()

virtual void binary_log::transaction::compression::Compressor::do_feed	(	const Char_t *	input_data,
		Size_t	input_size
	)

privatepure virtual

Implement feed.

This differs from feed in that it does not have to reset the frame when returning out_of_memory; the caller does that.

Implemented in binary_log::transaction::compression::None_comp, and binary_log::transaction::compression::Zstd_comp.

◆ do_finish()

virtual Compress_status binary_log::transaction::compression::Compressor::do_finish ( Managed_buffer_sequence_t & out )

privatepure virtual

Implement finish.

This differs from finish in that it does not have to reset the frame when returning out_of_memory; the caller does that.

Implementations may assume that compress has been called, since finish does that.

Implemented in binary_log::transaction::compression::None_comp, and binary_log::transaction::compression::Zstd_comp.

◆ do_get_grow_constraint_hint()

Compressor::Grow_constraint_t binary_log::transaction::compression::Compressor::do_get_grow_constraint_hint ( ) const

privatevirtual

Implement get_grow_constraint_hint.

In this base class, the function returns a default-constructed Grow_constraint, i.e., one which does not limit the Grow_calculator.

Reimplemented in binary_log::transaction::compression::Zstd_comp.

◆ do_get_type_code()

virtual type binary_log::transaction::compression::Compressor::do_get_type_code ( ) const

privatepure virtual

implement get_type_code.

Implemented in binary_log::transaction::compression::None_comp, and binary_log::transaction::compression::Zstd_comp.

◆ do_reset()

virtual void binary_log::transaction::compression::Compressor::do_reset ( )

privatepure virtual

Implement reset.

Implemented in binary_log::transaction::compression::None_comp, and binary_log::transaction::compression::Zstd_comp.

◆ do_set_pledged_input_size()

void binary_log::transaction::compression::Compressor::do_set_pledged_input_size ( Size_t size )

privatevirtual

Implement set_pledged_input_size.

By default, this does nothing.

◆ feed()

template<class Input_char_t >

void binary_log::transaction::compression::Compressor::feed	(	const Input_char_t *	input_data,
		Size_t	input_size
	)

inline

Submit data to be compressed.

This will not consume any of the input; it should be followed by a call to compress or finish.

Note: This object will not copy the input; the caller must ensure that the input lives until it has been consumed or the frame has been reset.; Must not be called when there is still non-consumed input left after a previous call to feed.

Parameters

input_data	Data to be compressed. This object will keep a shallow copy of the data and use it in subsequent calls to `compress` or `finish`.
input_size	Size of data to be compressed.

◆ feed_char_t()

void binary_log::transaction::compression::Compressor::feed_char_t	(	const Char_t *	input_data,
		Size_t	input_size
	)

private

Worker function for feed, requiring the correct Char_t type.

See also: feed.

◆ finish()

Compress_status binary_log::transaction::compression::Compressor::finish ( Managed_buffer_sequence_t & out )

Consume all input, produce all output, and end the frame.

This will consume all input previously given by feed (it internally calls compress). Then it ends the frame and flushes the output, ensuring that all data that may reside in the compression library's internal buffers gets compressed and written to the output.

The next call to feed will start a new frame.

Parameters

out	Storage for compressed bytes. This may grow, if needed.

Return values

success	All input was consumed, all output was produced, and the frame was reset.
out_of_memory	The operation failed due to an out of memory error, and the frame has been reset.
exceeds_max_size	The `out` buffer was already at its max capacity, and filled, and there were more bytes left to produce. The frame has not been reset and it is not guaranteed that all input has been consumed. The caller may resume compression e.g. after increasing the capacity, or resetting the output buffer (perhaps after moving existing data elsewhere), or using a different output buffer, or similar.

◆ get_grow_constraint_hint()

Compressor::Grow_constraint_t binary_log::transaction::compression::Compressor::get_grow_constraint_hint ( ) const

Return a Grow_constraint that may be used with the Managed_buffer_sequence storing the output, in order to optimize memory usage for a particular compression algorithm.

This may be implemented by subclasses such that it depends on the pledged input size. Therefore, for the most optimal grow constraint, call this after set_pledged_input_size.

◆ get_pledged_input_size()

Compressor::Size_t binary_log::transaction::compression::Compressor::get_pledged_input_size ( ) const

Return the size previously provided to set_pledged_input_size, or pledged_input_size_unset if no pledged size has been set.

◆ get_type_code()

type binary_log::transaction::compression::Compressor::get_type_code ( ) const

Returns: the compression type.

◆ operator=() [1/2]

Compressor & binary_log::transaction::compression::Compressor::operator= ( Compressor && other )

delete

◆ operator=() [2/2]

Compressor & binary_log::transaction::compression::Compressor::operator= ( const Compressor & other )

delete

◆ reset()

void binary_log::transaction::compression::Compressor::reset ( )

Reset the frame.

This cancels the current frame and starts a new one.

This is allowed but unnecessary if the current frame has been reset by finish or by an out_of_memory error from compress.

◆ set_pledged_input_size()

void binary_log::transaction::compression::Compressor::set_pledged_input_size ( Size_t size )

Declare that the input size will be exactly as given.

This may allow compressors and decompressors to use memory more efficiently.

This function may only be called if feed has never been called, or if the compressor has been reset since the last call to feed. The pledged size will be set back to pledged_input_size_unset next time this compressor is reset.

It is required that the total number of bytes passed to feed before the call to finish matches the pledged number. Otherwise, the behavior of finish is undefined.

Member Data Documentation

◆ m_empty

bool binary_log::transaction::compression::Compressor::m_empty = true

private

True when user has not provided any input since the last reset.

◆ m_pending_input

bool binary_log::transaction::compression::Compressor::m_pending_input = false

private

True when user has provided input that has not yet been consumed.

◆ m_pledged_input_size

Size_t binary_log::transaction::compression::Compressor::m_pledged_input_size = pledged_input_size_unset

private

The number of bytes.

◆ pledged_input_size_unset

constexpr Size_t binary_log::transaction::compression::Compressor::pledged_input_size_unset

staticconstexpr

Initial value:

=

std::numeric_limits<Size_t>::max()

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

libbinlogevents/include/compression/compressor.h
libbinlogevents/src/compression/compressor.cpp

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Char_t

◆ Grow_constraint_t

◆ Managed_buffer_sequence_t

◆ Size_t

Constructor & Destructor Documentation

◆ Compressor() [1/3]

◆ Compressor() [2/3]

◆ Compressor() [3/3]

◆ ~Compressor()

Member Function Documentation

◆ compress()

◆ do_compress()

◆ do_feed()

◆ do_finish()

◆ do_get_grow_constraint_hint()

◆ do_get_type_code()

◆ do_reset()

◆ do_set_pledged_input_size()

◆ feed()

◆ feed_char_t()

◆ finish()

◆ get_grow_constraint_hint()

◆ get_pledged_input_size()

◆ get_type_code()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ reset()

◆ set_pledged_input_size()

Member Data Documentation

◆ m_empty

◆ m_pending_input

◆ m_pledged_input_size

◆ pledged_input_size_unset