MySQL 8.2.0
Source Code Documentation
sql_xa_second_phase.h
Go to the documentation of this file.
1/* Copyright (c) 2022, 2023, 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 XA_SQL_CMD_XA_SECOND_PHASE
24#define XA_SQL_CMD_XA_SECOND_PHASE
25
26#include "sql/mdl_context_backup.h" // MDL_context_backup_manager
27#include "sql/sql_cmd.h" // Sql_cmd
28#include "sql/xa.h" // xid_t
29
30/**
31 @class Sql_cmd_xa_second_phase
32
33 This class abstracts some functionality used by XA statements involved in
34 the second phase of the the XA two-phase commit, specifically, `XA
35 COMMIT` and `XA ROLLBACK` SQL statements.
36
37 Common usage of the available methods target the process of detached XA
38 transactions, code pattern looks like:
39
40 bool Sql_cmd_xa_statement::process_detached_xa_statement(THD *thd) {
41 DBUG_TRACE;
42
43 if (this->find_and_initialize_xa_context(thd)) return true;
44 if (this->acquire_locks(thd)) return true;
45 raii::Sentry<> xa_lock_guard{
46 [this]() -> void { this->release_locks(); }};
47 this->setup_thd_context(thd);
48 if (this->enter_commit_order(thd)) return true;
49
50 this->assign_xid_to_thd(thd);
51
52 // SPECIFIC STATEMENT EXECUTION HERE
53 this->m_result = exec_statement(thd);
54
55 this->exit_commit_order(thd);
56 this->cleanup_context(thd);
57
58 return this->m_result;
59 }
60
61 @see Sql_cmd
62*/
64 public:
65 /**
66 Class constructor.
67
68 @param xid_arg XID of the XA transacation about to be committed
69 */
71 virtual ~Sql_cmd_xa_second_phase() override = default;
72
73 protected:
74 /** The XID associated with the underlying XA transaction. */
75 xid_t *m_xid{nullptr};
76 /** The MDL savepoint used to rollback the MDL context when transient errors
77 occur */
79 /** The detached transaction context, retrieved from the transaction cache */
80 std::shared_ptr<Transaction_ctx> m_detached_trx_context{nullptr};
81 /** Whether or not the initialization of GTIDs returned an error */
82 bool m_gtid_error{false};
83 /** Whether or not the OWNED_GTID related structures need to be cleaned */
85 /** The incremental success of the several initialization and deinitialization
86 steps. Is mainly used to steer some of the deinitialization calls */
87 bool m_result{false};
88
89 /**
90 Tries to find and initialize the `Transaction_ctx` for the underlying
91 detached XA transaction.
92
93 Execution is as follows:
94 1. Find transaction in the transaction cache.
95 2. Ensure that the underlying state regards the detached XA
96 transaction.
97
98 @param thd The THD session object used to process the detached XA
99 transaction.
100
101 @return false if the transaction context was successfully initialized,
102 true otherwise.
103 */
105 /**
106 Tries to acquire the locks necessary to finalize the underlying
107 detached XA transaction. By function exit, all locks have been acquired
108 or none.
109
110 Execution is as follows:
111 1. An MDL savepoint is set, in order to allow the rollback to this
112 point if a timeout/locking error is triggered.
113 2. XID_STATE::m_xa_lock is acquired to prevent concurrent finalization
114 of the transaction (triggered from different client connections, for
115 instance).
116 3. Ensure that between steps 1. and 2. some other session didn't
117 finalize the transaction, by confirming that the transaction is in
118 the transaction cache and still in prepared state.
119 4. Acquire MDL commit locks.
120
121 @param thd The THD session object used to process the detached XA
122 transaction.
123
124 @return false if all necessary locks were acquired, true otherwise.
125 */
126 bool acquire_locks(THD *thd);
127 /**
128 Release any locks acquires in `acquire_locks` still needing
129 to be released.
130 */
131 void release_locks() const;
132 /**
133 Initializes the necessary parts of the `thd` parameter, transferring
134 some of the detached XA transaction context to the active session. This
135 is necessary to use other parts of the infra-structure that rely on
136 having the active THD session properly initialized.
137
138 Execution is as follows:
139 1. Determine if GTID infra-structure is consistent and ready to
140 finalize the transaction.
141 2. Check the detached transaction status.
142 3. Transfer to the THD session object the state of the detached XA
143 transaction w.r.t whether or not the transaction has already been
144 binlogged.
145
146 @param thd The THD session object used to process the detached XA
147 transaction.
148 */
149 void setup_thd_context(THD *thd);
150 /**
151 For replica applier threads, enters the wait on the commit order.
152
153 Execution is as follows:
154 1. Enters the wait on the commit order.
155 2. If the wait fails (timeout or possible deadlock found), resets the
156 overall state to a point where a retry is possible:
157 a. Resets the GTID infra-structure.
158 b. Rolls back the MDL context to the recorded savepoint.
159 c. Resets the transaction binlogging state.
160
161 @param thd The THD session object used to process the detached XA
162 transaction.
163
164 @return false if the commit order wait was successful, true otherwise.
165 */
166 bool enter_commit_order(THD *thd);
167 /**
168 Sets the XID_STATE of the THD session object parameter as in detached
169 state and copies into it the XID of the detached XA transaction.
170
171 @param thd The THD session object used to process the detached XA
172 transaction.
173 */
174 void assign_xid_to_thd(THD *thd) const;
175 /**
176 For replica applier threads, finishes the wait on the commit order and
177 allows other threads to proceed.
178
179 @param thd The THD session object used to process the detached XA
180 transaction.
181 */
182 void exit_commit_order(THD *thd) const;
183 /**
184 Cleans up the THD context in order to prepare it for re-use.
185
186 Execution is as follows:
187 1. The active THD session binlogging state is cleared.
188 2. Any MDL context backup, associated with the detached transaction, is
189 deleted.
190 3. The detached transaction context is deleted from the transaction
191 cache.
192 4. GTID state is finalized, either committing or rolling back the GTID
193 information.
194
195 @param thd The THD session object used to process the detached XA
196 transaction.
197 */
198 void cleanup_context(THD *thd) const;
199 /**
200 Disposes of member variables that need it, because destructors for `Sql_cmd`
201 classes aren't invoked (since they are created in the internal memory pool,
202 memory is disposed as a all block).
203 */
204 void dispose();
205};
206
207#endif // XA_SQL_CMD_XA_SECOND_PHASE
Savepoint for MDL context.
Definition: mdl.h:1316
This class abstracts some functionality used by XA statements involved in the second phase of the the...
Definition: sql_xa_second_phase.h:63
void release_locks() const
Release any locks acquires in acquire_locks still needing to be released.
Definition: sql_xa_second_phase.cc:109
MDL_savepoint m_mdl_savepoint
The MDL savepoint used to rollback the MDL context when transient errors occur.
Definition: sql_xa_second_phase.h:78
bool find_and_initialize_xa_context(THD *thd)
Tries to find and initialize the Transaction_ctx for the underlying detached XA transaction.
Definition: sql_xa_second_phase.cc:37
bool m_result
The incremental success of the several initialization and deinitialization steps.
Definition: sql_xa_second_phase.h:87
xid_t * m_xid
The XID associated with the underlying XA transaction.
Definition: sql_xa_second_phase.h:75
Sql_cmd_xa_second_phase(xid_t *xid_arg)
Class constructor.
Definition: sql_xa_second_phase.cc:34
void assign_xid_to_thd(THD *thd) const
Sets the XID_STATE of the THD session object parameter as in detached state and copies into it the XI...
Definition: sql_xa_second_phase.cc:156
bool m_gtid_error
Whether or not the initialization of GTIDs returned an error.
Definition: sql_xa_second_phase.h:82
void exit_commit_order(THD *thd) const
For replica applier threads, finishes the wait on the commit order and allows other threads to procee...
Definition: sql_xa_second_phase.cc:162
virtual ~Sql_cmd_xa_second_phase() override=default
void setup_thd_context(THD *thd)
Initializes the necessary parts of the thd parameter, transferring some of the detached XA transactio...
Definition: sql_xa_second_phase.cc:115
bool m_need_clear_owned_gtid
Whether or not the OWNED_GTID related structures need to be cleaned.
Definition: sql_xa_second_phase.h:84
bool acquire_locks(THD *thd)
Tries to acquire the locks necessary to finalize the underlying detached XA transaction.
Definition: sql_xa_second_phase.cc:50
void dispose()
Disposes of member variables that need it, because destructors for Sql_cmd classes aren't invoked (si...
Definition: sql_xa_second_phase.cc:184
std::shared_ptr< Transaction_ctx > m_detached_trx_context
The detached transaction context, retrieved from the transaction cache.
Definition: sql_xa_second_phase.h:80
void cleanup_context(THD *thd) const
Cleans up the THD context in order to prepare it for re-use.
Definition: sql_xa_second_phase.cc:168
bool enter_commit_order(THD *thd)
For replica applier threads, enters the wait on the commit order.
Definition: sql_xa_second_phase.cc:137
Representation of an SQL command.
Definition: sql_cmd.h:81
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_lexer_thd.h:35
Representation of an SQL command.
struct xid_t is binary compatible with the XID structure as in the X/Open CAE Specification,...
Definition: xa.h:82