MySQL 8.3.0
Source Code Documentation
mysql::binlog::event::compression::Compressor Class Referenceabstract

Abstract base class for compressors. More...

#include <compressor.h>

Inheritance diagram for mysql::binlog::event::compression::Compressor:
[legend]

Public Types

using Managed_buffer_sequence_t = mysql::binlog::event::compression::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 = mysql::binlog::event::compression::buffer::Grow_constraint
 

Public Member Functions

 Compressor ()=default
 
 Compressor (const Compressor &other)=delete
 
 Compressor (Compressor &&other)=delete
 
Compressoroperator= (const Compressor &other)=delete
 
Compressoroperator= (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:

  1. 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.
  2. 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 mysql::binlog::event::compression::buffer::Managed_buffer_sequence to store output.

Member Typedef Documentation

◆ Char_t

using mysql::binlog::event::compression::Compressor::Char_t = Managed_buffer_sequence_t::Char_t

◆ Grow_constraint_t

◆ Managed_buffer_sequence_t

◆ Size_t

using mysql::binlog::event::compression::Compressor::Size_t = Managed_buffer_sequence_t::Size_t

Constructor & Destructor Documentation

◆ Compressor() [1/3]

mysql::binlog::event::compression::Compressor::Compressor ( )
default

◆ Compressor() [2/3]

mysql::binlog::event::compression::Compressor::Compressor ( const Compressor other)
delete

◆ Compressor() [3/3]

mysql::binlog::event::compression::Compressor::Compressor ( Compressor &&  other)
delete

◆ ~Compressor()

virtual mysql::binlog::event::compression::Compressor::~Compressor ( )
virtualdefault

Member Function Documentation

◆ compress()

Compress_status mysql::binlog::event::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
outStorage for compressed bytes. This may grow, if needed.
Return values
successAll input was consumed.
out_of_memoryThe operation failed due to an out of memory error. The frame has been reset.
exceeds_max_sizeThe 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 mysql::binlog::event::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 mysql::binlog::event::compression::None_comp, and mysql::binlog::event::compression::Zstd_comp.

◆ do_feed()

virtual void mysql::binlog::event::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 mysql::binlog::event::compression::None_comp, and mysql::binlog::event::compression::Zstd_comp.

◆ do_finish()

virtual Compress_status mysql::binlog::event::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 mysql::binlog::event::compression::None_comp, and mysql::binlog::event::compression::Zstd_comp.

◆ do_get_grow_constraint_hint()

Compressor::Grow_constraint_t mysql::binlog::event::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 mysql::binlog::event::compression::Zstd_comp.

◆ do_get_type_code()

virtual type mysql::binlog::event::compression::Compressor::do_get_type_code ( ) const
privatepure virtual

◆ do_reset()

virtual void mysql::binlog::event::compression::Compressor::do_reset ( )
privatepure virtual

◆ do_set_pledged_input_size()

void mysql::binlog::event::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 mysql::binlog::event::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_dataData to be compressed. This object will keep a shallow copy of the data and use it in subsequent calls to compress or finish.
input_sizeSize of data to be compressed.

◆ feed_char_t()

void mysql::binlog::event::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 mysql::binlog::event::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
outStorage for compressed bytes. This may grow, if needed.
Return values
successAll input was consumed, all output was produced, and the frame was reset.
out_of_memoryThe operation failed due to an out of memory error, and the frame has been reset.
exceeds_max_sizeThe 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 mysql::binlog::event::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 mysql::binlog::event::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 mysql::binlog::event::compression::Compressor::get_type_code ( ) const
Returns
the compression type.

◆ operator=() [1/2]

Compressor & mysql::binlog::event::compression::Compressor::operator= ( Compressor &&  other)
delete

◆ operator=() [2/2]

Compressor & mysql::binlog::event::compression::Compressor::operator= ( const Compressor other)
delete

◆ reset()

void mysql::binlog::event::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 mysql::binlog::event::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 mysql::binlog::event::compression::Compressor::m_empty = true
private

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

◆ m_pending_input

bool mysql::binlog::event::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 mysql::binlog::event::compression::Compressor::m_pledged_input_size = pledged_input_size_unset
private

The number of bytes.

◆ pledged_input_size_unset

constexpr Size_t mysql::binlog::event::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: