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