MySQL 8.4.3
Source Code Documentation
tc_log.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 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 TC_LOG_H
25#define TC_LOG_H
26
27#include <assert.h>
28#include <stddef.h>
29#include <sys/types.h>
30
31#include "my_inttypes.h"
32#include "my_io.h"
33#include "my_sys.h" // my_msync
37
38class THD;
39
41
42#define TC_LOG_MIN_PAGES 6
43
44namespace trx_coordinator {
45/**
46 Commits detached XA transaction by XID in all storage engines.
47
48 @pre thd->transaction.flags.commit_low == true
49 @post thd->transaction.flags.commit_low == false
50
51 @param thd The THD session object holding the detached XA/XID.
52 @param run_after_commit
53 True by default, otherwise, does not execute the
54 after_commit hook in the function.
55
56 @return false if execution succeeded, true otherwise.
57 */
58bool commit_detached_by_xid(THD *thd, bool run_after_commit = true);
59/**
60 Rolls back detached XA transaction by XID in all storage engines.
61
62 @param thd The THD session object holding the detached XA/XID.
63
64 @return false if execution succeeded, true otherwise.
65 */
67/**
68 Commits the underlying transaction in storage engines.
69
70 Determines if the transaction to commit is attached to the `thd`
71 parameter or, instead, the `thd` parameter holds the XID for a detached
72 transaction to be committed.
73
74 @param thd THD session object.
75 @param all Is set in case of explicit commit (COMMIT statement), or
76 implicit commit issued by DDL. Is not set when called at the
77 end of statement, even if autocommit=1.
78 @param run_after_commit
79 True by default, otherwise, does not execute the
80 after_commit hook in the function.
81
82 @return false if the transaction was committed, true if an error
83 occurred.
84*/
85bool commit_in_engines(THD *thd, bool all = false,
86 bool run_after_commit = true);
87/**
88 Rolls back the underlying transaction in storage engines.
89
90 Determines if the transaction to rollback is attached to the `thd`
91 parameter or, instead, the `thd` parameter holds the XID for a detached
92 transaction to be rolled back.
93
94 @param thd THD session object.
95 @param all Is set in case of explicit commit (COMMIT statement), or
96 implicit commit issued by DDL. Is not set when called at the
97 end of statement, even if autocommit=1.
98
99 @return false if the transaction was rolled back, true if an error
100 occurred.
101*/
102bool rollback_in_engines(THD *thd, bool all = false);
103
104/**
105 Marks the underlying transaction as `PREPARED_IN_TC` in storage engines.
106
107 The underlying executing statement is tested in order to understand if
108 the transaction should be marked. The accepted statements are:
109 - XA PREPARE [xid]
110
111 @param thd THD session object.
112 @param all Is set in case of explicit commit (COMMIT statement), or
113 implicit commit issued by DDL. Is not set when called at the
114 end of statement, even if autocommit=1.
115
116 @return 0 id the transaction was marked as `PREPARED_IN_TC` in
117 storage engines, error code otherwise.
118 */
119int set_prepared_in_tc_in_engines(THD *thd, bool all = false);
120/**
121 Checks whether or not the underlying statement should trigger setting the
122 transaction to `PREPARED_IN_TC` state. The accepted statemets are:
123 - XA PREPARE [xid]
124
125 @param thd THD session object.
126
127 @return true if the underlying statement should trigger setting the
128 transaction as `PREPARED_IN_TC`, false if not
129 */
131} // namespace trx_coordinator
132
133/**
134 Transaction Coordinator Log.
135
136 A base abstract class for three different implementations of the
137 transaction coordinator.
138
139 The server uses the transaction coordinator to order transactions
140 correctly and there are three different implementations: one using
141 an in-memory structure, one dummy that does not do anything, and one
142 using the binary log for transaction coordination.
143*/
144class TC_LOG {
145 public:
146 /**
147 Perform heuristic recovery, if --tc-heuristic-recover was used.
148
149 @note no matter whether heuristic recovery was successful or not
150 mysqld must exit. So, return value is the same in both cases.
151
152 @retval false no heuristic recovery was requested
153 @retval true heuristic recovery was performed
154 */
156
157 TC_LOG() = default;
158 virtual ~TC_LOG() = default;
159
161
162 /**
163 Initialize and open the coordinator log.
164 Do recovery if necessary. Called during server startup.
165
166 @param opt_name Name of logfile.
167
168 @retval 0 success
169 @retval 1 failed
170 */
171 virtual int open(const char *opt_name) = 0;
172
173 /**
174 Close the transaction coordinator log and free any resources.
175 Called during server shutdown.
176 */
177 virtual void close() = 0;
178
179 /**
180 Log a commit record of the transaction to the transaction
181 coordinator log.
182
183 When the function returns, the transaction commit is properly
184 logged to the transaction coordinator log and can be committed in
185 the storage engines.
186
187 @param thd Session to log transaction for.
188 @param all @c True if this is a "real" commit, @c false if it is a
189 "statement" commit.
190
191 @return Error code on failure, zero on success.
192 */
193 virtual enum_result commit(THD *thd, bool all) = 0;
194
195 /**
196 Log a rollback record of the transaction to the transaction
197 coordinator log.
198
199 When the function returns, the transaction have been aborted in
200 the transaction coordinator log.
201
202 @param thd Session to log transaction record for.
203
204 @param all @c true if an explicit commit or an implicit commit
205 for a statement, @c false if an internal commit of the statement.
206
207 @return Error code on failure, zero on success.
208 */
209 virtual int rollback(THD *thd, bool all) = 0;
210
211 /**
212 Log a prepare record of the transaction to the storage engines.
213
214 @param thd Session to log transaction record for.
215
216 @param all @c true if an explicit commit or an implicit commit
217 for a statement, @c false if an internal commit of the statement.
218
219 @return Error code on failure, zero on success.
220 */
221 virtual int prepare(THD *thd, bool all) = 0;
222};
223
224class TC_LOG_DUMMY : public TC_LOG // use it to disable the logging
225{
226 public:
227 TC_LOG_DUMMY() = default;
228 int open(const char *) override;
229 void close() override {}
230 enum_result commit(THD *thd, bool all) override;
231 int rollback(THD *thd, bool all) override;
232 int prepare(THD *thd, bool all) override;
233};
234
235class TC_LOG_MMAP : public TC_LOG {
236 public: // only to keep Sun Forte on sol9x86 happy
237 typedef enum {
238 PS_POOL, // page is in pool
239 PS_ERROR, // last sync failed
240 PS_DIRTY // new xids added since last sync
242
243 private:
244 struct PAGE {
245 PAGE *next; // pages are linked in a fifo queue
246 my_xid *start, *end; // usable area of a page
247 my_xid *ptr; // next xid will be written here
248 int size, free; // max and current number of free xid slots on the page
249 int waiters; // number of waiters on condition
250 PAGE_STATE state; // see above
251 /**
252 Signalled when syncing of this page is done or when
253 this page is in "active" slot and syncing slot just
254 became free.
255 */
257 };
258
265 /*
266 LOCK_tc is used to protect access both to data members 'syncing',
267 'active', 'pool' and to the content of PAGE objects.
268 */
270 /**
271 Signalled when active PAGE is moved to syncing state,
272 thus member "active" becomes 0.
273 */
275 /**
276 Signalled when one more page becomes available in the
277 pool which we might select as active.
278 */
280
281 public:
283 int open(const char *opt_name) override;
284 void close() override;
285 enum_result commit(THD *thd, bool all) override;
286 int rollback(THD *thd, bool all) override;
287 int prepare(THD *thd, bool all) override;
288 int recover();
289 uint size() const;
290
291 private:
292 ulong log_xid(my_xid xid);
293 void unlog(ulong cookie, my_xid xid);
294 PAGE *get_active_from_pool();
295 bool sync();
296 void overflow();
297
298 protected:
299 // We want to mock away syncing to disk in unit tests.
300 virtual int do_msync_and_fsync(int fd_arg, void *addr, size_t len,
301 int flags) {
302 return my_msync(fd_arg, addr, len, flags);
303 }
304
305 private:
306 /**
307 Find empty slot in the page and write xid value there.
308
309 @param xid value of xid to store in the page
310 @param p pointer to the page where to store xid
311 @param data_arg pointer to the top of the mapped to memory file
312 to calculate offset value (cookie)
313
314 @return offset value from the top of the page where the xid was stored.
315 */
316 ulong store_xid_in_empty_slot(my_xid xid, PAGE *p, uchar *data_arg) {
317 /* searching for an empty slot */
318 while (*p->ptr) {
319 p->ptr++;
320 assert(p->ptr < p->end); // because p->free > 0
321 }
322
323 /* found! store xid there and mark the page dirty */
324 const ulong cookie =
325 (ulong)((uchar *)p->ptr - data_arg); // can never be zero
326 *p->ptr++ = xid;
327 p->free--;
328 p->state = PS_DIRTY;
329
330 return cookie;
331 }
332
333 /**
334 Wait for until page data will be written to the disk.
335
336 @param p pointer to the PAGE to store to the disk
337
338 @retval false Success
339 @retval true Failure
340 */
342 p->waiters++;
343 while (p->state == PS_DIRTY && syncing) {
344 mysql_cond_wait(&p->cond, &LOCK_tc);
345 }
346 p->waiters--;
347
348 return p->state == PS_ERROR;
349 }
350
351 /*
352 the following friend declaration is to grant access from TCLogMMapTest
353 to methods log_xid()/unlog() that are private.
354 */
355 friend class TCLogMMapTest;
356};
357
358extern TC_LOG *tc_log;
361
362#endif // TC_LOG_H
Definition: tc_log.h:225
TC_LOG_DUMMY()=default
int prepare(THD *thd, bool all) override
Log a prepare record of the transaction to the storage engines.
Definition: tc_log.cc:261
void close() override
Close the transaction coordinator log and free any resources.
Definition: tc_log.h:229
int rollback(THD *thd, bool all) override
Log a rollback record of the transaction to the transaction coordinator log.
Definition: tc_log.cc:254
enum_result commit(THD *thd, bool all) override
Log a commit record of the transaction to the transaction coordinator log.
Definition: tc_log.cc:246
int open(const char *) override
Initialize and open the coordinator log.
Definition: tc_log.cc:238
Definition: tc_log.h:235
ulong store_xid_in_empty_slot(my_xid xid, PAGE *p, uchar *data_arg)
Find empty slot in the page and write xid value there.
Definition: tc_log.h:316
PAGE * get_active_from_pool()
there is no active page, let's got one from the pool.
Definition: tc_log.cc:434
enum_result commit(THD *thd, bool all) override
Commit the transaction.
Definition: tc_log.cc:494
PAGE * pages
Definition: tc_log.h:264
uint size() const
Get the total amount of potentially usable slots for XIDs in TC log.
Definition: tc_log.cc:414
my_off_t file_length
Definition: tc_log.h:261
bool wait_sync_completion(PAGE *p)
Wait for until page data will be written to the disk.
Definition: tc_log.h:341
PAGE * pool
Definition: tc_log.h:264
File fd
Definition: tc_log.h:260
void unlog(ulong cookie, my_xid xid)
erase xid from the page, update page free space counters/pointers.
Definition: tc_log.cc:646
void close() override
Close the transaction coordinator log and free any resources.
Definition: tc_log.cc:665
virtual int do_msync_and_fsync(int fd_arg, void *addr, size_t len, int flags)
Definition: tc_log.h:300
uchar * data
Definition: tc_log.h:263
uint npages
Definition: tc_log.h:262
mysql_mutex_t LOCK_tc
Definition: tc_log.h:269
PAGE * syncing
Definition: tc_log.h:264
char logname[FN_REFLEN]
Definition: tc_log.h:259
TC_LOG_MMAP()
Definition: tc_log.h:282
void overflow()
Definition: tc_log.cc:468
PAGE_STATE
Definition: tc_log.h:237
@ PS_DIRTY
Definition: tc_log.h:240
@ PS_POOL
Definition: tc_log.h:238
@ PS_ERROR
Definition: tc_log.h:239
mysql_cond_t COND_pool
Signalled when one more page becomes available in the pool which we might select as active.
Definition: tc_log.h:279
friend class TCLogMMapTest
Definition: tc_log.h:355
PAGE ** pool_last_ptr
Definition: tc_log.h:264
int recover()
Definition: tc_log.cc:696
int open(const char *opt_name) override
Initialize and open the coordinator log.
Definition: tc_log.cc:316
PAGE * active
Definition: tc_log.h:264
uint inited
Definition: tc_log.h:262
ulong log_xid(my_xid xid)
Record that transaction XID is committed on the persistent storage.
Definition: tc_log.cc:558
mysql_cond_t COND_active
Signalled when active PAGE is moved to syncing state, thus member "active" becomes 0.
Definition: tc_log.h:274
int rollback(THD *thd, bool all) override
Log a rollback record of the transaction to the transaction coordinator log.
Definition: tc_log.cc:517
int prepare(THD *thd, bool all) override
Log a prepare record of the transaction to the storage engines.
Definition: tc_log.cc:524
bool sync()
Write the page data being synchronized to the disk.
Definition: tc_log.cc:611
Transaction Coordinator Log.
Definition: tc_log.h:144
virtual int open(const char *opt_name)=0
Initialize and open the coordinator log.
virtual enum_result commit(THD *thd, bool all)=0
Log a commit record of the transaction to the transaction coordinator log.
virtual ~TC_LOG()=default
bool using_heuristic_recover()
Perform heuristic recovery, if –tc-heuristic-recover was used.
Definition: tc_log.cc:740
virtual void close()=0
Close the transaction coordinator log and free any resources.
TC_LOG()=default
virtual int prepare(THD *thd, bool all)=0
Log a prepare record of the transaction to the storage engines.
virtual int rollback(THD *thd, bool all)=0
Log a rollback record of the transaction to the transaction coordinator log.
enum_result
Definition: tc_log.h:160
@ RESULT_INCONSISTENT
Definition: tc_log.h:160
@ RESULT_SUCCESS
Definition: tc_log.h:160
@ RESULT_ABORTED
Definition: tc_log.h:160
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_lexer_thd.h:36
#define mysql_cond_wait(C, M)
Definition: mysql_cond.h:48
const char * p
Definition: ctype-mb.cc:1235
int my_msync(int, void *, size_t, int)
Definition: my_mmap.cc:51
static int flags[50]
Definition: hp_test1.cc:40
Some integer typedefs for easier portability.
unsigned long long int ulonglong
Definition: my_inttypes.h:56
ulonglong my_off_t
Definition: my_inttypes.h:72
unsigned char uchar
Definition: my_inttypes.h:52
Common #defines and includes for file and socket I/O.
#define FN_REFLEN
Definition: my_io.h:83
int File
Definition: my_io_bits.h:51
Common header for many mysys elements.
Instrumentation helpers for conditions.
ABI for instrumented mutexes.
Definition: tc_log.h:44
bool commit_detached_by_xid(THD *thd, bool run_after_commit=true)
Commits detached XA transaction by XID in all storage engines.
Definition: tc_log.cc:109
bool commit_in_engines(THD *thd, bool all=false, bool run_after_commit=true)
Commits the underlying transaction in storage engines.
Definition: tc_log.cc:137
bool should_statement_set_prepared_in_tc(THD *thd)
Checks whether or not the underlying statement should trigger setting the transaction to PREPARED_IN_...
Definition: tc_log.cc:180
int set_prepared_in_tc_in_engines(THD *thd, bool all=false)
Marks the underlying transaction as PREPARED_IN_TC in storage engines.
Definition: tc_log.cc:162
bool rollback_detached_by_xid(THD *thd)
Rolls back detached XA transaction by XID in all storage engines.
Definition: tc_log.cc:127
bool rollback_in_engines(THD *thd, bool all=false)
Rolls back the underlying transaction in storage engines.
Definition: tc_log.cc:150
Instrumentation helpers for conditions.
ulonglong my_xid
Definition: handler.h:1235
Definition: tc_log.h:244
PAGE * next
Definition: tc_log.h:245
my_xid * start
Definition: tc_log.h:246
int waiters
Definition: tc_log.h:249
my_xid * end
Definition: tc_log.h:246
int free
Definition: tc_log.h:248
PAGE_STATE state
Definition: tc_log.h:250
int size
Definition: tc_log.h:248
mysql_cond_t cond
Signalled when syncing of this page is done or when this page is in "active" slot and syncing slot ju...
Definition: tc_log.h:256
my_xid * ptr
Definition: tc_log.h:247
An instrumented cond structure.
Definition: mysql_cond_bits.h:50
An instrumented mutex structure.
Definition: mysql_mutex_bits.h:50
TC_LOG_DUMMY tc_log_dummy
Definition: tc_log.cc:737
TC_LOG_MMAP tc_log_mmap
Definition: tc_log.cc:738
TC_LOG * tc_log
Definition: tc_log.cc:736
ulonglong my_xid
Definition: tc_log.h:38