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