MySQL 8.3.0
Source Code Documentation
binlog_storage_iterator.h
Go to the documentation of this file.
1/* Copyright (c) 2023, Oracle and/or its affiliates.
2
3This program is free software; you can redistribute it and/or modify
4it under the terms of the GNU General Public License, version 2.0,
5as published by the Free Software Foundation.
6
7This program is also distributed with certain software (including
8but not limited to OpenSSL) that is licensed under separate terms,
9as designated in a particular file or component or in included license
10documentation. The authors of MySQL hereby grant you an additional
11permission to link the program and your derivative works with the
12separately licensed software that they have included with MySQL.
13
14This program is distributed in the hope that it will be useful,
15but WITHOUT ANY WARRANTY; without even the implied warranty of
16MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17GNU General Public License, version 2.0, for more details.
18
19You should have received a copy of the GNU General Public License
20along with this program; if not, write to the Free Software
21Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef BINLOG_STORAGE_ITERATOR_SERVICE_HEADERS_H
24#define BINLOG_STORAGE_ITERATOR_SERVICE_HEADERS_H
25#include <cstdint>
26#include <string>
27
31
33
35 /// @brief Iterator was successfully initialized.
37
38 /// @brief Returned when the required GTIDs have already been purged and
39 /// therefore the iterator cannot fetch the needed entries. Caller should
40 /// still call the deinit function on the iterator.
42
43 /// @brief Returned when the log is closed and therefore the iterator cannot
44 /// get the change entries. Caller should still call the deinit function on
45 /// the iterator.
47
48 /// @brief Failure to initialize iterator due to undefined error. Caller
49 /// should still call the deinit function on the iterator.
51};
52
53/// @brief This enumeration lists the possible return values for the get
54/// function
56 /// @brief returned when the get operation succeeded.
57 ///
58 /// If the get operation succeeds, this also means that the iterator advances.
60
61 /// @brief returned when there are no more entries to get.
62 ///
63 /// The iterator remains open and you can call get on it again. If
64 /// more content has been created in the meantime, get will get it
65 /// for you.
67
68 /// @brief returned whenever the get was called with an insufficient buffer.
69 ///
70 /// The iterator does not advance and the caller can call get again with a
71 /// larger buffer.
73
74 /// @brief Returned when there is an unrecoverable error and this iterator has
75 /// been closed. The caller still needs to deinitialize the iterator.
77
78 /// @brief returned whenever the iterator context is invalid.
79 ///
80 /// The iterator became invalid and therefore it cannot be used successfully
81 /// from now onwards. I must still be de-initialized to release resources.
83
84 /// @brief returned whenever there was an unspecified error attempting to get
85 /// the next entry.
86 ///
87 /// In case of an unspecified error, the caller can retry but there is no
88 /// guarantee whether the retry is successful or not.
90};
91
92BEGIN_SERVICE_DEFINITION(binlog_storage_iterator)
93
94/// @brief Initializes the iterator.
95///
96/// my_h_binlog_storage_iterator is the service handle defined and is an opaque
97/// pointer to the stream state.
98///
99/// @param[out] iterator where the iterator created will be stored.
100///
101/// @param[in] excluded_gtids_as_string The set of GTIDs to filter out from the
102/// iterator.
103///
104/// @retval kBinlogIteratorInitOk @see
105/// Binlog_iterator_service_init_status#kBinlogIteratorInitOk
106/// @retval kBinlogIteratorIniErrorPurgedGtids @see
107/// Binlog_iterator_service_init_status#kBinlogIteratorIniErrorPurgedGtids
108/// @retval kBinlogIteratorInitErrorLogClosed @see
109/// Binlog_iterator_service_init_status#kBinlogIteratorInitErrorLogClosed
110/// @retval kBinlogIteratorInitErrorUnspecified @see
111/// Binlog_iterator_service_init_status#kBinlogIteratorGetErrorUnspecified
114 const char *excluded_gtids_as_string));
115
116/// @brief Shall get the next event in the iterator.
117///
118/// Gets the next event in the iterator. If there are no more events in the
119/// iterator, it just returns immediately. Note that this function will also
120/// advance the iterator if the operation is successful or the next entries are
121/// to be skipped.
122///
123/// In case the error is kBinlogIteratorGetErrorInvalid or
124/// kBinlogIteratorGetErrorUnspecified the iterator must be de initialized by
125/// calling deinit. If the caller attempts to call get again, then the
126/// same error is returned.
127///
128/// @param iterator the iterator reference to use use during the get operation.
129///
130/// @param[in,out] buffer the buffer to store the raw change stream bytes for
131/// the next entry fetched from the given iterator.
132///
133/// @param[in] buffer_capacity the capacity of the buffer where the bytes are to
134/// be stored.
135///
136/// @param[out] bytes_read the amount of bytes read and put into the buffer.
137///
138/// @retval kBinlogIteratorGetOk
139/// Binlog_iterator_service_get_status#kBinlogIteratorGetOk
140/// @retval kBinlogIteratorGetEndOfChanges
141/// Binlog_iterator_service_get_status#kBinlogIteratorGetEndOfChanges
142/// @retval kBinlogIteratorGetInsufficientBuffer
143/// Binlog_iterator_service_get_status#kBinlogIteratorGetInsufficientBuffer
144/// @retval kBinlogIteratorGetErrorClosed @see
145/// Binlog_iterator_service_get_status#kBinlogIteratorGetErrorClosed
146/// @retval kBinlogIteratorGetErrorInvalid @see
147/// Binlog_iterator_service_get_status#kBinlogIteratorGetErrorInvalid
148/// @retval kBinlogIteratorGetErrorUnspecified @see
149/// Binlog_iterator_service_get_status#kBinlogIteratorGetErrorUnspecified
151 (my_h_binlog_storage_iterator iterator, unsigned char *buffer,
152 uint64_t buffer_capacity, uint64_t *bytes_read));
153
154/// @brief Destroys the iterator and releases resources associated with it.
155///
156/// @param[in] iterator the iterator to destroy.
158
159/// @brief Gets details about the entry's storage in a JSON format.
160///
161/// Allows the caller to get information about the underlying storage. Some
162/// implementations may return a name and a position, for instance.
163///
164/// @param[in] iterator the iterator handle.
165///
166/// @param[in,out] buffer The buffer to store the information in.
167///
168/// @param[in,out] size As input, the size of the buffer provided. As output,
169/// the size of the data copied into the buffer.
170///
171/// @return true if there was an error, false otherwise.
172DECLARE_BOOL_METHOD(get_storage_details, (my_h_binlog_storage_iterator iterator,
173 char *buffer, uint64_t *size));
174
175/// @brief Gets the size of the next entry to fetch from the iterator.
176///
177/// Useful to drive reallocations.
178///
179/// @param[in] iterator the iterator being operated.
180/// @param[out] size a pointer to store the size of the next entry to get.
181///
182/// @return false on success, true otherwise. Note that if the iterator has
183/// reached the end of changes, then it means that an error shall be returned.
184DECLARE_BOOL_METHOD(get_next_entry_size,
185 (my_h_binlog_storage_iterator iterator, uint64_t *size));
186
187END_SERVICE_DEFINITION(binlog_storage_iterator)
188
189#endif /* BINLOG_STORAGE_ITERATOR_SERVICE_HEADERS_H */
static mysql_service_status_t deinit()
Component deinitialization.
Definition: audit_api_message_emit.cc:579
static mysql_service_status_t init()
Component initialization.
Definition: audit_api_message_emit.cc:570
Binlog_iterator_service_init_status
Definition: binlog_storage_iterator.h:34
@ kBinlogIteratorInitErrorUnspecified
Failure to initialize iterator due to undefined error.
Definition: binlog_storage_iterator.h:50
@ kBinlogIteratorInitErrorLogClosed
Returned when the log is closed and therefore the iterator cannot get the change entries.
Definition: binlog_storage_iterator.h:46
@ kBinlogIteratorInitOk
Iterator was successfully initialized.
Definition: binlog_storage_iterator.h:36
@ kBinlogIteratorIniErrorPurgedGtids
Returned when the required GTIDs have already been purged and therefore the iterator cannot fetch the...
Definition: binlog_storage_iterator.h:41
Binlog_iterator_service_get_status
This enumeration lists the possible return values for the get function.
Definition: binlog_storage_iterator.h:55
@ kBinlogIteratorGetErrorClosed
Returned when there is an unrecoverable error and this iterator has been closed.
Definition: binlog_storage_iterator.h:76
@ kBinlogIteratorGetErrorInvalid
returned whenever the iterator context is invalid.
Definition: binlog_storage_iterator.h:82
@ kBinlogIteratorGetErrorUnspecified
returned whenever there was an unspecified error attempting to get the next entry.
Definition: binlog_storage_iterator.h:89
@ kBinlogIteratorGetEndOfChanges
returned when there are no more entries to get.
Definition: binlog_storage_iterator.h:66
@ kBinlogIteratorGetInsufficientBuffer
returned whenever the get was called with an insufficient buffer.
Definition: binlog_storage_iterator.h:72
@ kBinlogIteratorGetOk
returned when the get operation succeeded.
Definition: binlog_storage_iterator.h:59
mutable_buffer buffer(void *p, size_t n) noexcept
Definition: buffer.h:417
void get(PSI_field *, PSI_longlong *) noexcept
Definition: pfs_plugin_column_bigint_v1_all_empty.cc:31
#define DECLARE_METHOD(retval, name, args)
Declares a method as a part of the Service definition.
Definition: service.h:102
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
#define DEFINE_SERVICE_HANDLE(name)
Defines an object type that is meant for carrying handles to the implementation-specific objects used...
Definition: service.h:128
#define DECLARE_BOOL_METHOD(name, args)
Declares a method that returns bool as a part of the Service definition.
Definition: service.h:111
Definition: file_storage.cc:429