MySQL 9.0.0
Source Code Documentation
mysql::binlog::event::compression::Payload_event_buffer_istream Class Reference

Stream class that yields a stream of byte buffers, each holding the raw decompressed data of one event contained in a Transaction_payload_log_event. More...

#include <payload_event_buffer_istream.h>

Public Types

using Char_t = unsigned char
 
using Size_t = mysql::binlog::event::compression::buffer::Buffer_view< Char_t >::Size_t
 
using Grow_calculator_t = mysql::binlog::event::compression::buffer::Grow_calculator
 
using Managed_buffer_t = mysql::binlog::event::compression::buffer::Managed_buffer< Char_t >
 
using Decompressor_t = Decompressor
 
using Status_t = Decompress_status
 
using Factory_t = Factory
 
using Buffer_view_t = Managed_buffer_t::Buffer_view_t
 
using Buffer_ptr_t = std::shared_ptr< Buffer_view_t >
 
using Managed_buffer_ptr_t = std::shared_ptr< Managed_buffer_t >
 
using Memory_resource_t = mysql::binlog::event::resource::Memory_resource
 
template<class T >
using Allocator_t = mysql::binlog::event::resource::Allocator< T >
 

Public Member Functions

template<class String_char_t >
 Payload_event_buffer_istream (const String_char_t *compressed_buffer, Size_t compressed_buffer_size, type compression_algorithm, Size_t default_buffer_size=0, const Memory_resource_t &memory_resource=Memory_resource_t())
 Construct the stream from the raw compressed data. More...
 
template<class String_char_t >
 Payload_event_buffer_istream (const std::basic_string< String_char_t > &compressed_data, type compression_algorithm, Size_t default_buffer_size=0, const Memory_resource_t &memory_resource=Memory_resource_t())
 Construct the stream from the raw compressed data. More...
 
 Payload_event_buffer_istream (const Transaction_payload_event &transaction_payload_log_event, Size_t default_buffer_size=0, const Memory_resource_t &memory_resource=Memory_resource_t())
 Construct the stream from a (non-owned) Payload Event. More...
 
 Payload_event_buffer_istream (const std::shared_ptr< const Transaction_payload_event > &tple, Size_t default_buffer_size=0, const Memory_resource_t &memory_resource=Memory_resource_t())
 Construct the stream from a shared pointer to an event. More...
 
 Payload_event_buffer_istream (Payload_event_buffer_istream &)=delete
 
 Payload_event_buffer_istream (Payload_event_buffer_istream &&)=delete
 
Payload_event_buffer_istreamoperator= (Payload_event_buffer_istream &)=delete
 
Payload_event_buffer_istreamoperator= (Payload_event_buffer_istream &&)=delete
 
 ~Payload_event_buffer_istream ()
 
Payload_event_buffer_istreamoperator>> (Buffer_ptr_t &out)
 Read the next event from the stream and update the stream state. More...
 
Payload_event_buffer_istreamoperator>> (Managed_buffer_ptr_t &out)
 Read the next event into a Managed_buffer. More...
 
 operator bool () const
 Indicate if EOF or error has not happened. More...
 
bool operator! () const
 Indicate if EOF or error has happened. More...
 
Status_t get_status () const
 Return the stream status. More...
 
bool has_error () const
 Return true if there was an error. More...
 
std::string get_error_str () const
 Return a string that describes the last error, or empty string. More...
 
const Grow_calculator_tget_grow_calculator () const
 Return Grow_calculator used for output buffers. More...
 
void set_grow_calculator (const Grow_calculator_t &grow_calculator)
 Set a new Grow_calculator to use for output buffers. More...
 

Private Member Functions

void initialize ()
 Construct and initialize the decompressor. More...
 
void next ()
 Decompress the next event into the internal buffer. More...
 
void update_buffer ()
 Allocate the output buffer if needed. More...
 
void read_event ()
 
void set_error_str (const std::string &s)
 Specify the string that subsequent calls to error_str will return. More...
 
void set_status (Status_t status)
 Update the status. More...
 

Private Attributes

Memory_resource_t m_memory_resource
 Memory_resource to handle all allocations. More...
 
const Char_tm_compressed_buffer {nullptr}
 The buffer we are reading from. More...
 
Size_t m_compressed_buffer_size {0}
 Size of the buffer we are reading from. More...
 
type m_compression_algorithm {NONE}
 Compression algorithm we are using. More...
 
std::shared_ptr< const Transaction_payload_eventm_tple {nullptr}
 The event we are reading from. More...
 
Grow_calculator_t m_grow_calculator
 Grow calculator for the Managed_buffer. More...
 
Size_t m_default_buffer_size
 Default buffer size for the Managed_buffer. More...
 
Managed_buffer_ptr_t m_managed_buffer_ptr
 Shared pointer to Managed_buffer that holds the output. More...
 
std::unique_ptr< Decompressor_tm_decompressor {nullptr}
 Decompressor. More...
 
Status_t m_status {Status_t::success}
 Error status. More...
 
std::string m_error_str
 Error string. More...
 
bool m_outstanding_error {false}
 True if a read has failed but neither get_error_str, has_error, nor get_status has been called. More...
 

Detailed Description

Stream class that yields a stream of byte buffers, each holding the raw decompressed data of one event contained in a Transaction_payload_log_event.

The suggested use pattern is:

while (stream >> event_buffer) { // handle event } if (stream.error()) { // handle error }

Member Typedef Documentation

◆ Allocator_t

◆ Buffer_ptr_t

◆ Buffer_view_t

◆ Char_t

◆ Decompressor_t

◆ Factory_t

◆ Grow_calculator_t

◆ Managed_buffer_ptr_t

◆ Managed_buffer_t

◆ Memory_resource_t

◆ Size_t

◆ Status_t

Constructor & Destructor Documentation

◆ Payload_event_buffer_istream() [1/6]

template<class String_char_t >
mysql::binlog::event::compression::Payload_event_buffer_istream::Payload_event_buffer_istream ( const String_char_t *  compressed_buffer,
Size_t  compressed_buffer_size,
type  compression_algorithm,
Size_t  default_buffer_size = 0,
const Memory_resource_t memory_resource = Memory_resource_t() 
)
inline

Construct the stream from the raw compressed data.

This stream will keep a pointer to the buffer, so the caller must ensure that the buffer outlives the stream.

Parameters
compressed_bufferInput buffer (compressed bytes).
compressed_buffer_sizeSize of input buffer.
compression_algorithmThe algorithm the input was compressed with.
default_buffer_sizeThe default size of the internal event buffer. To tune this, consider that bigger buffers reduce allocations since one buffer will be reused for all smaller events, whereas smaller buffers reduce memory footprint in case all events fit within the buffer size.
memory_resourceMemory_resource object used to allocate memory.

◆ Payload_event_buffer_istream() [2/6]

template<class String_char_t >
mysql::binlog::event::compression::Payload_event_buffer_istream::Payload_event_buffer_istream ( const std::basic_string< String_char_t > &  compressed_data,
type  compression_algorithm,
Size_t  default_buffer_size = 0,
const Memory_resource_t memory_resource = Memory_resource_t() 
)
inline

Construct the stream from the raw compressed data.

This stream will keep a pointer to the buffer, so the caller must ensure that the buffer outlives the stream.

Parameters
compressed_dataInput buffer (compressed bytes).
compression_algorithmThe algorithm the input was compressed with.
default_buffer_sizeThe default size of the internal event buffer. To tune this, consider that bigger buffers reduce allocations since one buffer will be reused for all smaller events, whereas smaller buffers reduce memory footprint in case all events fit within the buffer size.
memory_resourceMemory_resource object used to allocate memory.

◆ Payload_event_buffer_istream() [3/6]

mysql::binlog::event::compression::Payload_event_buffer_istream::Payload_event_buffer_istream ( const Transaction_payload_event transaction_payload_log_event,
Size_t  default_buffer_size = 0,
const Memory_resource_t memory_resource = Memory_resource_t() 
)
explicit

Construct the stream from a (non-owned) Payload Event.

This stream will keep a pointer to the buffer owned by the event, so the caller must ensure that the event outlives the stream.

Parameters
transaction_payload_log_eventEvent containing the compressed data.
default_buffer_sizeThe default size of the internal event buffer. To tune this, consider that bigger buffers reduce allocations since one buffer will be reused for all smaller events, whereas smaller buffers reduce memory footprint in case all events fit within the buffer size.
memory_resourceMemory_resource object used to allocate memory.

◆ Payload_event_buffer_istream() [4/6]

mysql::binlog::event::compression::Payload_event_buffer_istream::Payload_event_buffer_istream ( const std::shared_ptr< const Transaction_payload_event > &  tple,
Size_t  default_buffer_size = 0,
const Memory_resource_t memory_resource = Memory_resource_t() 
)
explicit

Construct the stream from a shared pointer to an event.

This stream will, as long as it lives, hold shared ownership of the event. If, when this stream is deleted, it is the last owner of the event, it will delete the event.

Parameters
tpleEvent containing the compressed data.
default_buffer_sizeThe default size of the internal event buffer. To tune this, consider that bigger buffers reduce allocations since one buffer will be reused for all smaller events, whereas smaller buffers reduce memory footprint in case all events fit within the buffer size.
memory_resourceMemory_resource object used to allocate memory.

◆ Payload_event_buffer_istream() [5/6]

mysql::binlog::event::compression::Payload_event_buffer_istream::Payload_event_buffer_istream ( Payload_event_buffer_istream )
delete

◆ Payload_event_buffer_istream() [6/6]

mysql::binlog::event::compression::Payload_event_buffer_istream::Payload_event_buffer_istream ( Payload_event_buffer_istream &&  )
delete

◆ ~Payload_event_buffer_istream()

mysql::binlog::event::compression::Payload_event_buffer_istream::~Payload_event_buffer_istream ( )

Member Function Documentation

◆ get_error_str()

std::string mysql::binlog::event::compression::Payload_event_buffer_istream::get_error_str ( ) const

Return a string that describes the last error, or empty string.

This corresponds to the return value from has_error. When has_error returns success or eof, get_error_str returns an empty string.

◆ get_grow_calculator()

const Payload_event_buffer_istream::Grow_calculator_t & mysql::binlog::event::compression::Payload_event_buffer_istream::get_grow_calculator ( ) const

Return Grow_calculator used for output buffers.

◆ get_status()

Payload_event_buffer_istream::Status_t mysql::binlog::event::compression::Payload_event_buffer_istream::get_status ( ) const

Return the stream status.

Return values
successLast read was successful
endLast read could not complete because the position was at the end.
out_of_memoryError: memory allocation failed.
exceeds_max_sizeError: the event was larger than the configured maximum.
corruptedA corruption error was reported from ZSTD, or the stream was truncated.

◆ has_error()

bool mysql::binlog::event::compression::Payload_event_buffer_istream::has_error ( ) const

Return true if there was an error.

◆ initialize()

void mysql::binlog::event::compression::Payload_event_buffer_istream::initialize ( )
private

Construct and initialize the decompressor.

This will attempt to initialize the decompressor and feed it the input buffer. If an error occurs, the stream error state is set accordingly.

◆ next()

void mysql::binlog::event::compression::Payload_event_buffer_istream::next ( )
private

Decompress the next event into the internal buffer.

If any error occurs, the stream error state is set accordingly.

◆ operator bool()

mysql::binlog::event::compression::Payload_event_buffer_istream::operator bool ( ) const
explicit

Indicate if EOF or error has not happened.

Return values
truelast read was successful, or no read has yet been attempted).
falselast read resulted in end-of-stream or error.

◆ operator!()

bool mysql::binlog::event::compression::Payload_event_buffer_istream::operator! ( ) const

Indicate if EOF or error has happened.

This is the negation of operator bool.

Return values
falselast read was successful, or no read has yet been attempted.
truelast read resulted in end-of-stream or error.

◆ operator=() [1/2]

Payload_event_buffer_istream & mysql::binlog::event::compression::Payload_event_buffer_istream::operator= ( Payload_event_buffer_istream &&  )
delete

◆ operator=() [2/2]

Payload_event_buffer_istream & mysql::binlog::event::compression::Payload_event_buffer_istream::operator= ( Payload_event_buffer_istream )
delete

◆ operator>>() [1/2]

Payload_event_buffer_istream & mysql::binlog::event::compression::Payload_event_buffer_istream::operator>> ( Buffer_ptr_t out)

Read the next event from the stream and update the stream state.

If the stream status is already something else than Decompress_status::success, the function does not change the status.

If the function was able to read an event, it modifies out to point to a buffer holding event data. This leaves the stream state as Decompress_status::success, and subsequent invocations of operator bool will return true.

If an error occurred, or the end of the stream was reached, the function resets out to nullptr. It also alters the stream state to the relevant Decompress_status, and subsequent invocations of operator bool will return false. If the resulting status is not Decompress_status::end, an error message can subsequently be obtained by calling get_error_str.

Note
This class attempts to protect against a common coding mistake. The mistake occurs when a caller forgets to check the reason for ending the stream; whether it actually reached the end, or whether there was an error. Normally, the caller should act differently in the two cases. The protection mechanism is enabled in debug mode, and enforces that the user calls get_status after the stream ends (whether it ends by reaching the end or by an error). If the stream ends, and the user does not call get_status, and then the stream object is destroyed, the destructor raises an assertion.
The output is a reference to a shared pointer, and the stream is another owner of the same shared pointer. On the next invocation of operator>>, the buffer will be reused if there are no other owners than the stream and the output argument. If there are other owners to it, a new buffer is allocated. So a caller is allowed to keep a shared pointer to the output buffer as long as it needs. If the caller does not keep any shared pointer to the output buffer, it allows the stream to reduce allocations and memory footprint.
Compressed events never have a checksum, regardless of configuration. If the event is to be decoded, you must disable checksum checks first.
Parameters
[out]outThe target buffer where this function will store the event data.

◆ operator>>() [2/2]

Payload_event_buffer_istream & mysql::binlog::event::compression::Payload_event_buffer_istream::operator>> ( Managed_buffer_ptr_t out)

Read the next event into a Managed_buffer.

See also
operator>>(Buffer_ptr_t &out)

◆ read_event()

void mysql::binlog::event::compression::Payload_event_buffer_istream::read_event ( )
private

◆ set_error_str()

void mysql::binlog::event::compression::Payload_event_buffer_istream::set_error_str ( const std::string &  s)
private

Specify the string that subsequent calls to error_str will return.

◆ set_grow_calculator()

void mysql::binlog::event::compression::Payload_event_buffer_istream::set_grow_calculator ( const Grow_calculator_t grow_calculator)

Set a new Grow_calculator to use for output buffers.

◆ set_status()

void mysql::binlog::event::compression::Payload_event_buffer_istream::set_status ( Status_t  status)
private

Update the status.

◆ update_buffer()

void mysql::binlog::event::compression::Payload_event_buffer_istream::update_buffer ( )
private

Allocate the output buffer if needed.

It reuses the existing buffer if this object holds the only reference to it. Otherwise it allocates a new buffer. If allocation fails, the stream error state is set accordingly.

Member Data Documentation

◆ m_compressed_buffer

const Char_t* mysql::binlog::event::compression::Payload_event_buffer_istream::m_compressed_buffer {nullptr}
private

The buffer we are reading from.

◆ m_compressed_buffer_size

Size_t mysql::binlog::event::compression::Payload_event_buffer_istream::m_compressed_buffer_size {0}
private

Size of the buffer we are reading from.

◆ m_compression_algorithm

type mysql::binlog::event::compression::Payload_event_buffer_istream::m_compression_algorithm {NONE}
private

Compression algorithm we are using.

◆ m_decompressor

std::unique_ptr<Decompressor_t> mysql::binlog::event::compression::Payload_event_buffer_istream::m_decompressor {nullptr}
private

Decompressor.

◆ m_default_buffer_size

Size_t mysql::binlog::event::compression::Payload_event_buffer_istream::m_default_buffer_size
private

Default buffer size for the Managed_buffer.

◆ m_error_str

std::string mysql::binlog::event::compression::Payload_event_buffer_istream::m_error_str
private

Error string.

◆ m_grow_calculator

Grow_calculator_t mysql::binlog::event::compression::Payload_event_buffer_istream::m_grow_calculator
private

Grow calculator for the Managed_buffer.

◆ m_managed_buffer_ptr

Managed_buffer_ptr_t mysql::binlog::event::compression::Payload_event_buffer_istream::m_managed_buffer_ptr
private

Shared pointer to Managed_buffer that holds the output.

This will be shared with API clients. Therefore, API clients can use the returned buffer as long as they like. The next time this objects needs a buffer to write the output, it uses the shared object if the API clients have stopped using it; otherwise allocates a new Managed_buffer.

◆ m_memory_resource

Memory_resource_t mysql::binlog::event::compression::Payload_event_buffer_istream::m_memory_resource
private

Memory_resource to handle all allocations.

◆ m_outstanding_error

bool mysql::binlog::event::compression::Payload_event_buffer_istream::m_outstanding_error {false}
mutableprivate

True if a read has failed but neither get_error_str, has_error, nor get_status has been called.

◆ m_status

Status_t mysql::binlog::event::compression::Payload_event_buffer_istream::m_status {Status_t::success}
private

Error status.

◆ m_tple

std::shared_ptr<const Transaction_payload_event> mysql::binlog::event::compression::Payload_event_buffer_istream::m_tple {nullptr}
private

The event we are reading from.

We don't use this, we only hold the shared pointer to prevent that the caller destroys the object that owns the buffer.


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