MySQL 8.3.0
Source Code Documentation
decompressing_event_object_istream.h
Go to the documentation of this file.
1/* Copyright (c) 2019, 2023, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef BINLOG_DECOMPRESSING_EVENT_OBJECT_ISTREAM_H_
24#define BINLOG_DECOMPRESSING_EVENT_OBJECT_ISTREAM_H_
25
26#include <queue>
27
30#include "mysql/binlog/event/resource/memory_resource.h" // Memory_resource
31#include "sql/binlog_reader.h"
33
34/// @addtogroup Replication
35/// @{
36///
37/// @file decompressing_event_object_istream.h
38///
39/// Stream class that yields Log_event objects, including events
40/// contained in Transaction_payload_log_events.
41
42namespace binlog {
43
44/// Stream class that yields Log_event objects from a source. The
45/// source can be a Transaction_payload_log_event, in which case it will
46/// produce the contained events. Or it can be a file, in which case it
47/// will yield all events in the file, and if there is a
48/// Transaction_payload_log_event, it will yield first that and then all
49/// the contained events.
50///
51/// The recommended use pattern is:
52///
53/// @code
54/// while (stream >> event) {
55/// // handle event
56/// }
57/// if (stream.has_error()) {
58/// // handle error
59/// }
60/// @endcode
61///
62/// This class actually enforces that you call `has_error` after the
63/// loop; failure to do so will result in an assertion in debug mode.
64/// In the unlikely case that your code doesn't need to check for
65/// errors, you can get rid of the assert by calling has_error() and
66/// discarding the return value.
68 public:
73 using Event_ptr_t = std::shared_ptr<Log_event>;
74 using Tple_ptr_t = std::shared_ptr<const Transaction_payload_log_event>;
79
80 /// Construct stream over a file, decompressing payload events.
81 ///
82 /// This will produce all events in the file, and in addition, each
83 /// Transaction_payload_log_event is followed by the contained
84 /// events.
85 ///
86 /// @param reader The source file to read from.
87 /// @param memory_resource Instrumented memory allocator object
90 const Memory_resource_t &memory_resource = Memory_resource_t());
91
92 /// Construct stream over a Transaction_payload_log_event.
93 ///
94 /// This will produce all events contained in the event, but not the
95 /// event itself.
96 ///
97 /// This Decompressing_event_object_istream will, during its entire
98 /// life time, hold shared ownership of the Transaction_payload_log_event.
99 ///
100 /// @param transaction_payload_log_event The source file to read from.
101 ///
102 /// @param format_description_event The FD event used to parse events.
103 ///
104 /// @param memory_resource Instrumented memory allocator object
106 const Tple_ptr_t &transaction_payload_log_event,
107 Fde_ref_t format_description_event,
108 const Memory_resource_t &memory_resource = Memory_resource_t());
109
110 /// Construct stream over a Transaction_payload_log_event.
111 ///
112 /// This will produce all events contained in the event, but not the
113 /// event itself.
114 ///
115 /// This Decompressing_event_object_istream will, during its entire
116 /// life time, hold a pointer to the Transaction_payload_log_event,
117 /// and the caller must ensure that the event outlives the stream.
118 ///
119 /// @param transaction_payload_log_event The source file to read from.
120 ///
121 /// @param format_description_event The FD event used to parse events.
122 ///
123 /// @param memory_resource Instrumented memory allocator object
125 const Transaction_payload_log_event &transaction_payload_log_event,
126 Fde_ref_t format_description_event,
127 const Memory_resource_t &memory_resource = Memory_resource_t());
128
129#ifdef NDEBUG
131#else
133#endif
134
136 delete;
138 delete;
143
144 /// Specify whether checksums shall be verified or not.
145 ///
146 /// @param verify_checksum If true, verify checksums; otherwise
147 /// don't.
148 void set_verify_checksum(bool verify_checksum = true);
149
150 /// Read an event from the stream.
151 ///
152 /// @param out Shared pointer to the produced event. If this is a
153 /// Transaction_payload_log_event, the stream will keep a shared
154 /// pointer to it, until it has produced all the contained events.
155 ///
156 /// @return This object.
158
159 /// Indicate if EOF or error has not happened.
160 ///
161 /// @retval true last read was successful (or there was no last
162 /// read).
163 ///
164 /// @retval false last read resulted in end-of-stream or error.
165 explicit operator bool() const;
166
167 /// Indicate if EOF or error has happened. This is the negation of
168 /// `operator bool`.
169 ///
170 /// @retval false last read was successful, or there was no last
171 /// read.
172 ///
173 /// @retval true last read resulted in end-of-stream or error.
174 bool operator!() const;
175
176 /// Return true if an error has happened.
177 bool has_error() const;
178
179 /// Return a message describing the last error.
180 ///
181 /// @retval "" No error
182 ///
183 /// @retval string Error
184 std::string get_error_str() const;
185
186 /// Return the status
187 Status_t get_status() const;
188
189 /// Return const reference to Grow_calculator to the internal event buffer.
191
192 /// Set the Grow_calculator for the internal event buffer.
193 void set_grow_calculator(const Grow_calculator_t &grow_calculator);
194
195 private:
196 /// Stream of events to read from
198 /// Whether we should verify checksum. Unused!
199 bool m_verify_checksum{false};
200 /// Error from last operation
201 std::string m_error_str;
202 /// True if we have reached EOF, false otherwise.
203 bool m_end{false};
204 /// Status
206 /// Position of last event
208#ifndef NDEBUG
209 /// True if a read has failed but neither `get_error_str` nor
210 /// `has_error` has been called.
211 mutable bool m_outstanding_error{false};
212#endif
213
214 /// Policy for growing buffers in the decompressing stream
216 /// The decompression stream; non-null while we are positioned in a TPLE.
217 std::unique_ptr<Buffer_stream_t> m_buffer_istream{nullptr};
218 /// end_log_pos for the currently processed TPLE, if any
220 /// 0 when not processing a TPLE; N>0 when positioned before the Nth
221 /// embedded event of a TPLE.
223
225
226 /// Return the current FDE.
228
229 /// Report an error
230 ///
231 /// This sets the status as specified, and returns a stringstream to
232 /// which the caller shall write a message.
233 ///
234 /// @param status The status
235 ///
236 /// @returns Targeted_stringstream object; the error for this stream
237 /// will be set to the given status.
239
240 /// Prepare to unfold a given Transaction_payload_log_event by
241 /// setting state variables and creating the
242 /// Payload_event_buffer_istream object.
243 ///
244 /// This object will not hold ownership of the event. The caller
245 /// must ensure that the event outlives the stream.
246 ///
247 /// @param tple Event to unfold
249 do_begin_payload_event(tple, tple);
250 }
251
252 /// Prepare to unfold a given Transaction_payload_log_event by
253 /// setting state variables and creating the
254 /// Payload_event_buffer_istream object.
255 ///
256 /// This object will hold shared ownership of the event.
257 ///
258 /// @param tple Event to unfold
259 void begin_payload_event(const Tple_ptr_t &tple) {
260 do_begin_payload_event(*tple, tple);
261 }
262
263 /// Worker function implementing both forms of begin_payload_event.
264 ///
265 /// @tparam Event_ref_or_ptr Either reference-to-event or
266 /// shared-pointer-to-event.
267 ///
268 /// @param tple Event to unfold.
269 ///
270 /// @param ownership_tple Ownership handle for the event. This can
271 /// be a shared_ptr if this object should hold shared ownership, or
272 /// a reference otherwise.
273 template <class Event_ref_or_ptr>
275 const Event_ref_or_ptr &ownership_tple) {
279 assert(!m_buffer_istream);
280 try {
281 m_buffer_istream = std::make_unique<Buffer_stream_t>(ownership_tple, 0,
283 } catch (...) {
284 // Leave m_buffer_istream empty.
285 // Report error on next invocation of `operator>>`.
286 }
287 }
288
289 /// Worker that deserializes an event from the buffer.
290 ///
291 /// @param[in] buffer Input byte buffer.
292 ///
293 /// @param[out] out Pointer to output event.
294 ///
295 /// @retval false success
296 /// @retval true error
298 Event_ptr_t &out);
299
300 /// Status from read_from_payload_stream
301 enum class Read_status { success, eof, error };
302
303 /// Read and decode next event from the Payload_log_event stream
304 ///
305 /// @param[out] out Pointer to output event.
306 ///
307 /// @retval success The event was successfully read and decoded
308 ///
309 /// @retval error An error occurred. `get_error_str` will contain
310 /// the reason.
311 ///
312 /// @retval eof Nothing was read because the read position was at
313 /// the end of the event.
315
316 /// Read and decode the next event from the binlog stream.
317 ///
318 /// @param[out] out Pointer to the output event.
319 ///
320 /// @retval false The event was successfully read and decoded.
321 ///
322 /// @retval true Error or EOF occurred. In case of error,
323 /// `get_error_str` will contain the reason.
325};
326
327} // namespace binlog
328
329/// @} (end of group Replication)
330
331#endif // ifdef BINLOG_DECOMPRESSING_EVENT_OBJECT_ISTREAM_H_
Interface class that all specializations of template <...> Basic_binlog_file_reader inherit from.
Definition: binlog_reader.h:235
Definition: log_event.h:3858
Stream class that yields Log_event objects from a source.
Definition: decompressing_event_object_istream.h:67
~Decompressing_event_object_istream()
Definition: decompressing_event_object_istream.cc:63
Buffer_stream_t::Buffer_view_t Buffer_view_t
Definition: decompressing_event_object_istream.h:71
Decompressing_event_object_istream(IBasic_binlog_file_reader &reader, const Memory_resource_t &memory_resource=Memory_resource_t())
Construct stream over a file, decompressing payload events.
Definition: decompressing_event_object_istream.cc:32
bool decode_from_buffer(Buffer_view_t &buffer, Event_ptr_t &out)
Worker that deserializes an event from the buffer.
Definition: decompressing_event_object_istream.cc:161
Status_t get_status() const
Return the status.
Definition: decompressing_event_object_istream.cc:96
const mysql::binlog::event::Format_description_event & Fde_ref_t
Definition: decompressing_event_object_istream.h:75
Status_t m_status
Status.
Definition: decompressing_event_object_istream.h:205
void begin_payload_event(const Transaction_payload_log_event &tple)
Prepare to unfold a given Transaction_payload_log_event by setting state variables and creating the P...
Definition: decompressing_event_object_istream.h:248
Read_status read_from_payload_stream(Event_ptr_t &out)
Read and decode next event from the Payload_log_event stream.
Definition: decompressing_event_object_istream.cc:191
void do_begin_payload_event(const Transaction_payload_log_event &tple, const Event_ref_or_ptr &ownership_tple)
Worker function implementing both forms of begin_payload_event.
Definition: decompressing_event_object_istream.h:274
my_off_t m_transaction_payload_event_offset
end_log_pos for the currently processed TPLE, if any
Definition: decompressing_event_object_istream.h:219
std::shared_ptr< const Transaction_payload_log_event > Tple_ptr_t
Definition: decompressing_event_object_istream.h:74
raii::Targeted_stringstream error_stream(Status_t status)
Report an error.
Definition: decompressing_event_object_istream.cc:134
my_off_t m_event_position
Position of last event.
Definition: decompressing_event_object_istream.h:207
bool m_verify_checksum
Whether we should verify checksum. Unused!
Definition: decompressing_event_object_istream.h:199
std::shared_ptr< Log_event > Event_ptr_t
Definition: decompressing_event_object_istream.h:73
Decompressing_event_object_istream & operator=(Decompressing_event_object_istream &)=delete
Grow_calculator_t m_grow_calculator
Policy for growing buffers in the decompressing stream.
Definition: decompressing_event_object_istream.h:215
int m_embedded_event_number
0 when not processing a TPLE; N>0 when positioned before the Nth embedded event of a TPLE.
Definition: decompressing_event_object_istream.h:222
void set_verify_checksum(bool verify_checksum=true)
Specify whether checksums shall be verified or not.
Definition: decompressing_event_object_istream.cc:72
std::unique_ptr< Buffer_stream_t > m_buffer_istream
The decompression stream; non-null while we are positioned in a TPLE.
Definition: decompressing_event_object_istream.h:217
IBasic_binlog_file_reader * m_binlog_reader
Stream of events to read from.
Definition: decompressing_event_object_istream.h:197
bool operator!() const
Indicate if EOF or error has happened.
Definition: decompressing_event_object_istream.cc:79
void begin_payload_event(const Tple_ptr_t &tple)
Prepare to unfold a given Transaction_payload_log_event by setting state variables and creating the P...
Definition: decompressing_event_object_istream.h:259
Read_status
Status from read_from_payload_stream.
Definition: decompressing_event_object_istream.h:301
bool m_end
True if we have reached EOF, false otherwise.
Definition: decompressing_event_object_istream.h:203
void set_grow_calculator(const Grow_calculator_t &grow_calculator)
Set the Grow_calculator for the internal event buffer.
Definition: decompressing_event_object_istream.cc:156
std::function< Fde_ref_t()> m_get_format_description_event
Return the current FDE.
Definition: decompressing_event_object_istream.h:227
Decompressing_event_object_istream & operator>>(Event_ptr_t &out)
Read an event from the stream.
Definition: decompressing_event_object_istream.cc:263
Buffer_stream_t::Buffer_ptr_t Buffer_ptr_t
Definition: decompressing_event_object_istream.h:72
Decompressing_event_object_istream(Decompressing_event_object_istream &&)=delete
mysql::binlog::event::resource::Memory_resource Memory_resource_t
Definition: decompressing_event_object_istream.h:78
bool has_error() const
Return true if an error has happened.
Definition: decompressing_event_object_istream.cc:88
const Grow_calculator_t & get_grow_calculator() const
Return const reference to Grow_calculator to the internal event buffer.
Definition: decompressing_event_object_istream.cc:152
std::string m_error_str
Error from last operation.
Definition: decompressing_event_object_istream.h:201
Decompressing_event_object_istream(Decompressing_event_object_istream &)=delete
bool m_outstanding_error
True if a read has failed but neither get_error_str nor has_error has been called.
Definition: decompressing_event_object_istream.h:211
Memory_resource_t m_memory_resource
Definition: decompressing_event_object_istream.h:224
bool read_from_binlog_stream(Event_ptr_t &out)
Read and decode the next event from the binlog stream.
Definition: decompressing_event_object_istream.cc:227
std::string get_error_str() const
Return a message describing the last error.
Definition: decompressing_event_object_istream.cc:81
Decompressing_event_object_istream & operator=(Decompressing_event_object_istream &&)=delete
const Log_event_header * header() const
Return a const pointer to the header of the log event.
Definition: binlog_event.h:957
For binlog version 4.
Definition: control_events.h:238
unsigned long long log_pos
Definition: binlog_event.h:714
Stream class that yields a stream of byte buffers, each holding the raw decompressed data of one even...
Definition: payload_event_buffer_istream.h:58
Managed_buffer_t::Buffer_view_t Buffer_view_t
Definition: payload_event_buffer_istream.h:70
std::shared_ptr< Buffer_view_t > Buffer_ptr_t
Definition: payload_event_buffer_istream.h:71
mysql::binlog::event::compression::buffer::Grow_calculator Grow_calculator_t
Definition: payload_event_buffer_istream.h:64
Description of a heuristic to determine how much memory to allocate.
Definition: grow_calculator.h:67
Polymorphism-free memory resource class with custom allocator and deallocator functions.
Definition: memory_resource.h:87
Like std::stringstream, copying to a given target string at destruction.
Definition: targeted_stringstream.h:47
Class that wraps resources in a polymorphic manner.
#define DBUG_TRACE
Definition: my_dbug.h:145
ulonglong my_off_t
Definition: my_inttypes.h:71
Definition: pfs.cc:37
Decompress_status
Definition: decompress_status.h:31
mutable_buffer buffer(void *p, size_t n) noexcept
Definition: buffer.h:417
#define NODISCARD
The function attribute [[NODISCARD]] is a replacement for [[nodiscard]] to workaround a gcc bug.
Definition: nodiscard.h:46
Stream class that yields decompressed event byte buffers from a Transaction_payload_log_event.
required uint32 status
Definition: replication_asynchronous_connection_failover.proto:60