MySQL 8.4.3
Source Code Documentation
file_storage.h
Go to the documentation of this file.
1/* Copyright (c) 2023, 2024, 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 designed to work 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 either included with
13the program or referenced in the documentation.
14
15This program is distributed in the hope that it will be useful,
16but WITHOUT ANY WARRANTY; without even the implied warranty of
17MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18GNU General Public License, version 2.0, for more details.
19
20You should have received a copy of the GNU General Public License
21along with this program; if not, write to the Free Software
22Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef BINLOG_SERVICE_ITERATOR_FILE_STORAGE_H_
25#define BINLOG_SERVICE_ITERATOR_FILE_STORAGE_H_
26
29
32 public:
33 /// @brief The fully qualified service name: "binlog_storage_iterator.file".
34 static const std::string SERVICE_NAME;
35
36 /// @brief This registers runtime binary log related file services in
37 /// the service registry.
38 ///
39 /// This function is called at server startup.
40 ///
41 /// @return true on failure
42 /// @return false on success
43 static bool register_service();
44
45 /// @brief This unregisters runtime binary log related file storage services
46 /// from the server registry.
47 ///
48 /// This function is called, when the binary log is closed or when the server
49 /// is shutting down.
50 ///
51 /// @return true on failure.
52 /// @return false on success.
53 static bool unregister_service();
54
55 /// @brief Initializes the iterator.
56 ///
57 /// This function must be called prior to using the iterator.
58 ///
59 /// @param[out] iterator a pointer to the iterator to initialize.
60 ///
61 /// @param[in] excluded_gtids_as_string the set of transaction identifiers to
62 /// skip while reading from the log.
63 ///
64 /// @retval kBinlogIteratorInitOk if the operation concluded successfully.
65 /// @retval kBinlogIteratorIniErrorPurgedGtids if the iterator was not
66 /// successfully initialized due to transactions having been purged.
67 /// @retval kBinlogIteratorInitErrorLogClosed if the iterator was not
68 /// successfully initialized because the log is closed.
69 /// @retval BINLOG_INIT_ITERATOR_ERROR_UNDEF if the iterator was not
70 /// initialized due to an undefined error.
73 const char *excluded_gtids_as_string));
74
75 /// @brief Returns the next entry in the log files, end-of-file, or an error.
76 ///
77 /// @param[in] iterator the iterator context
78 ///
79 /// @param[in,out] buffer the buffer where to put the next value.
80 ///
81 /// @param[in] buffer_capacity the buffer size.
82 ///
83 /// @param[out] bytes_read the size of the value added to the buffer. If the
84 /// value is larger than the buffer length, then an error is returned and this
85 /// value is undefined.
86 ///
87 /// @note If there are new transactions being written to the log file after
88 /// the iterator has been opened, get will return them if the iterator is not
89 /// disposed before reaching that point in the log.
90 ///
91 /// @note If the log file rotates after the iterator has been opened, the
92 /// iterator itself shall rotate to the new file as well.
93 ///
94 /// @note The iterator will stop once it reached the end of the most recent
95 /// log file.
96 ///
97 /// @retval kBinlogIteratorGetOk if the operation succeeded.
98 /// @retval kBinlogIteratorGetEndOfChanges if there are no more events to
99 /// read. The iterator is still valid and if you call get again you either get
100 /// the same error back or new entries that may have been added in the
101 /// meantime.
102 /// @retval kBinlogIteratorGetInsufficientBuffer if the buffer is insufficient
103 /// to store the next entry. The iterator is still valid and you can call try
104 /// to get another entry with a larger buffer.
105 /// @retval kBinlogIteratorGetErrorClosed if the log is closed. The iterator
106 /// is still valid, but retrying will get the same error back as long as the
107 /// change log is closed.
108 /// @retval kBinlogIteratorGetErrorInvalid if the iterator itself has become
109 /// invalid. This can happen if the memory structures of the iterator are
110 /// tampered with. The iterator state is invalid and therefore the behavior is
111 /// undefined if one retries getting the next entry. May result on the same
112 /// error again. This iterator should be de-initialized and a new one created.
113 /// @retval kBinlogIteratorGetErrorUnspecified if there was an undefined error
114 /// while reading the next entry. The iterator state is invalid and therefore
115 /// the behavior is undefined if one retries getting the next entry. May
116 /// result on the same error again. This iterator should be de-initialized and
117 /// a new one created.
120 unsigned char *buffer, uint64_t buffer_capacity,
121 uint64_t *bytes_read));
122
123 /// @brief Destroys the iterator.
124 /// @param[in] iterator the iterator to destroy.
125 static DEFINE_METHOD(void, deinit, (my_h_binlog_storage_iterator iterator));
126
127 /// @brief Gets details about the entry's storage in a JSON format.
128 ///
129 /// @param[in] iterator a valid iterator, i.e., one that has been initialized
130 /// and not destroyed yet.
131 ///
132 /// @param[in,out] buffer The buffer to store the information in.
133 ///
134 /// @param[in,out] size As input, the size of the buffer provided. As output,
135 /// the size of the data copied into the buffer.
136 ///
137 /// @return false on success, true otherwise.
140 char *buffer, uint64_t *size));
141
142 /// Gets the size of the next block to be read.
143 ///
144 /// This member function can be used to check how larger the size of the
145 /// buffer to read the next block/event shall be. Note though that if the next
146 /// block ends up being skipped the obtained via this function is obsolete and
147 /// a new get_next_entry_size may have to be executed to fetch the buffer
148 /// needed for the next entry. Therefore it is a good practice for the caller
149 /// to loop over a get function while it returns insufficient buffer and thus
150 /// allocate a bigger buffer in that case.
151 ///
152 /// @param[in] iterator the iterator context.
153 ///
154 /// @param[out] size a pointer that stores the size if the function returns
155 /// successfully.
156 ///
157 /// @return false on success, true otherwise.
160 uint64_t *size));
161};
162
163/* clang-format off */
165 binlog_storage_iterator)
166
172
174/* clang-format on */
175
176} // namespace binlog::services::iterator
177#endif /* BINLOG_ITERATOR_SERVICE_FILE_IMPLEMENTATION_H */
Binlog_iterator_service_init_status
Definition: binlog_storage_iterator.h:35
Binlog_iterator_service_get_status
This enumeration lists the possible return values for the get function.
Definition: binlog_storage_iterator.h:56
Definition: file_storage.h:31
static Binlog_iterator_service_init_status init(my_h_binlog_storage_iterator *iterator, const char *excluded_gtids_as_string) noexcept
Initializes the iterator.
Definition: file_storage.cc:541
static bool unregister_service()
This unregisters runtime binary log related file storage services from the server registry.
Definition: file_storage.cc:748
static Binlog_iterator_service_get_status get(my_h_binlog_storage_iterator iterator, unsigned char *buffer, uint64_t buffer_capacity, uint64_t *bytes_read) noexcept
Returns the next entry in the log files, end-of-file, or an error.
Definition: file_storage.cc:633
static mysql_service_status_t get_next_entry_size(my_h_binlog_storage_iterator iterator, uint64_t *size) noexcept
Gets the size of the next block to be read.
Definition: file_storage.cc:703
static void deinit(my_h_binlog_storage_iterator iterator) noexcept
Destroys the iterator.
Definition: file_storage.cc:624
static mysql_service_status_t get_storage_details(my_h_binlog_storage_iterator iterator, char *buffer, uint64_t *size) noexcept
Gets details about the entry's storage in a JSON format.
Definition: file_storage.cc:598
static const std::string SERVICE_NAME
The fully qualified service name: "binlog_storage_iterator.file".
Definition: file_storage.h:34
static bool register_service()
This registers runtime binary log related file services in the service registry.
Definition: file_storage.cc:725
Definition: file_storage.cc:445
size_t size(const char *const c)
Definition: base64.h:46
mutable_buffer buffer(void *p, size_t n) noexcept
Definition: buffer.h:418
Specifies macros to define Service Implementations.
#define BEGIN_SERVICE_IMPLEMENTATION(component, service)
Declares a Service Implementation.
Definition: service_implementation.h:62
#define END_SERVICE_IMPLEMENTATION()
A macro to end the last declaration of a Service Implementation.
Definition: service_implementation.h:67
#define DEFINE_BOOL_METHOD(name, args)
A short macro to define method that returns bool, which is the most common case.
Definition: service_implementation.h:88
#define DEFINE_METHOD(retval, name, args)
A macro to ensure method implementation has required properties, that is it does not throw exceptions...
Definition: service_implementation.h:79
Definition: file_storage.cc:430
Definition: server_struct.h:39