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::containers::buffers::Buffer_view< Char_t >::Size_t

using	Grow_calculator_t = mysql::containers::buffers::Grow_calculator

using	Managed_buffer_t = mysql::containers::buffers::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::allocators::Memory_resource

template<class T >
using	Allocator_t = mysql::allocators::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_istream &	operator= (Payload_event_buffer_istream &)=delete

Payload_event_buffer_istream &	operator= (Payload_event_buffer_istream &&)=delete

	~Payload_event_buffer_istream ()

Payload_event_buffer_istream &	operator>> (Buffer_ptr_t &out)
	Read the next event from the stream and update the stream state. More...

Payload_event_buffer_istream &	operator>> (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_t &	get_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_t *	m_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_event >	m_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_t >	m_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

template<class T >

using mysql::binlog::event::compression::Payload_event_buffer_istream::Allocator_t = mysql::allocators::Allocator<T>

◆ Buffer_ptr_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Buffer_ptr_t = std::shared_ptr<Buffer_view_t>

◆ Buffer_view_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Buffer_view_t = Managed_buffer_t::Buffer_view_t

◆ Char_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Char_t = unsigned char

◆ Decompressor_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Decompressor_t = Decompressor

◆ Factory_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Factory_t = Factory

◆ Grow_calculator_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Grow_calculator_t = mysql::containers::buffers::Grow_calculator

◆ Managed_buffer_ptr_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Managed_buffer_ptr_t = std::shared_ptr<Managed_buffer_t>

◆ Managed_buffer_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Managed_buffer_t = mysql::containers::buffers::Managed_buffer<Char_t>

◆ Memory_resource_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Memory_resource_t = mysql::allocators::Memory_resource

◆ Size_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Size_t = mysql::containers::buffers::Buffer_view<Char_t>::Size_t

◆ Status_t

using mysql::binlog::event::compression::Payload_event_buffer_istream::Status_t = Decompress_status

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_buffer	Input buffer (compressed bytes).
compressed_buffer_size	Size of input buffer.
compression_algorithm	The algorithm the input was compressed with.
default_buffer_size	The 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_resource	`Memory_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_data	Input buffer (compressed bytes).
compression_algorithm	The algorithm the input was compressed with.
default_buffer_size	The 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_resource	`Memory_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_event	Event containing the compressed data.
default_buffer_size	The 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_resource	`Memory_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

tple	Event containing the compressed data.
default_buffer_size	The 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_resource	`Memory_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

success	Last read was successful
end	Last read could not complete because the position was at the end.
out_of_memory	Error: memory allocation failed.
exceeds_max_size	Error: the event was larger than the configured maximum.
corrupted	A 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

true	last read was successful, or no read has yet been attempted).
false	last 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

false	last read was successful, or no read has yet been attempted.
true	last 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] out The 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:

libs/mysql/binlog/event/compression/payload_event_buffer_istream.h
libs/mysql/binlog/event/compression/payload_event_buffer_istream.cpp

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

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]

◆ Payload_event_buffer_istream() [2/6]

◆ Payload_event_buffer_istream() [3/6]

◆ Payload_event_buffer_istream() [4/6]

◆ Payload_event_buffer_istream() [5/6]

◆ Payload_event_buffer_istream() [6/6]

◆ ~Payload_event_buffer_istream()

Member Function Documentation

◆ get_error_str()

◆ get_grow_calculator()

◆ get_status()

◆ has_error()

◆ initialize()

◆ next()

◆ operator bool()

◆ operator!()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator>>() [1/2]

◆ operator>>() [2/2]

◆ read_event()

◆ set_error_str()

◆ set_grow_calculator()

◆ set_status()

◆ update_buffer()

Member Data Documentation

◆ m_compressed_buffer

◆ m_compressed_buffer_size

◆ m_compression_algorithm

◆ m_decompressor

◆ m_default_buffer_size

◆ m_error_str

◆ m_grow_calculator

◆ m_managed_buffer_ptr

◆ m_memory_resource

◆ m_outstanding_error

◆ m_status

◆ m_tple