MySQL 8.0.30
Source Code Documentation
transaction_cache.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2022, Oracle and/or its affiliates.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2.0,
6 as published by the Free Software Foundation.
7
8 This program is also distributed with certain software (including
9 but not limited to OpenSSL) that is licensed under separate terms,
10 as designated in a particular file or component or in included license
11 documentation. The authors of MySQL hereby grant you an additional
12 permission to link the program and your derivative works with the
13 separately licensed software that they have included with MySQL.
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 XA_TRANSACTION_CACHE_H_INCLUDED
25#define XA_TRANSACTION_CACHE_H_INCLUDED
26
27#include <string.h>
28#include <sys/types.h>
29#include <list>
30#include <mutex>
31
32#include "lex_string.h"
33#include "my_dbug.h"
34#include "my_inttypes.h"
35#include "my_sqlcommand.h"
36#include "sql/malloc_allocator.h" // Malloc_allocator
37#include "sql/psi_memory_key.h" // key_memory_xa_recovered_transactions
38#include "sql/xa_aux.h" // serialize_xid
39
40class Transaction_ctx;
41
42namespace xa {
43
44/**
45 @class Transaction_cache
46
47 Class responsible for managing a cache of `Transaction_ctx` objects
48 associated with XA transactions.
49
50 The cache is used during the recovery stage of an XA transaction.
51
52 @note this class is a singleton class.
53 */
55 public:
56 using transaction_ptr = std::shared_ptr<Transaction_ctx>;
58 using list = std::vector<transaction_ptr>;
59 using filter_predicate_t = std::function<bool(transaction_ptr const &)>;
60
61 virtual ~Transaction_cache() = default;
62
63 // Disallow copy/move semantics
68
69 /**
70 Transaction is marked in the cache as if it's recovered.
71 The method allows to sustain prepared transaction disconnection.
72
73 @param transaction
74 Pointer to Transaction object that is replaced.
75
76 @return operation result
77 @retval false success or a cache already contains XID_STATE
78 for this XID value
79 @retval true failure
80 */
81 static bool detach(Transaction_ctx *transaction);
82 /**
83 Remove information about transaction from a cache.
84
85 @param transaction Pointer to a Transaction_ctx that has to be removed
86 from a cache.
87 */
88 static void remove(Transaction_ctx *transaction);
89 /**
90 Inserts a transaction context identified by a given XID.
91
92 @param xid The XID of the transaction.
93 @param transaction The object containing the context of the transaction.
94
95 @return false if the pair was successfully inserted, true otherwise.
96 */
97 static bool insert(XID *xid, Transaction_ctx *transaction);
98 /**
99 Creates a new transaction context for the recovering transaction
100 identified by a given XID.
101
102 @param xid The XID of the transaction being recovered.
103
104 @return false if the pair was successfully inserted, true otherwise.
105 */
106 static bool insert(XID *xid);
107 /**
108 Searches the cache for the transaction context identified by the given
109 XID.
110
111 An aditional filtering predicate can be provided, to allow for futher
112 validations on values for mathching XID. The predicate is evaluated
113 while holding the necessary locks to ensure the validaty of the
114 `Transaction_ctx` shared pointer.
115
116 A non-null value is returned if and only if:
117
118 1. The value is found in the underlying map
119 2. The found value underlying XID
120 (`Transaction_ctx::xid_state()::get_xid()`) equals to the parameter
121 `xid`. This validation is necessary since the XID representation for
122 the key used in the underlying map isn't an exact match for the full
123 XID representation.
124 3. If a predicate parameter is provided, the evaluation of passing the
125 value as a predicate parameter must be `true`.
126
127 @param xid The XID of the transaction to search the context for.
128 @param filter A predicate to be evaluated when an value for `xid` is
129 found. If predicate returns false, the found element is
130 filtered out.
131
132 @return The transaction context if found and valid, nullptr otherwise.
133 */
134 static transaction_ptr find(XID *xid, filter_predicate_t filter = nullptr);
135 /**
136 Retrieves the list of transaction contexts cached.
137
138 @return A vector with all transaction contexts cached so far.
139 */
141 /**
142 Initializes the transaction cache underlying resources.
143 */
144 static void initialize();
145 /**
146 Disposes of the transaction cache allocated resources.
147 */
148 static void dispose();
149
150 private:
151 /** A lock to serialize the access to `m_transaction_cache` */
153#ifdef HAVE_PSI_INTERFACE
154 /** The PSI key for the above lock */
156 /** The PSI configuration of the above lock and key */
158 {&m_key_LOCK_transaction_cache, "LOCK_transaction_cache",
160#endif
161 /** A map holding the cached transaction context, indexed by XID */
163
164 /**
165 Class constructor.
166
167 It's declared private since this class is a singleton class.
168 */
170
171 /**
172 Initialize a cache to store Transaction_ctx and a mutex to protect access
173 to the cache
174
175 @return The initialized class instance.
176 */
177 static Transaction_cache &instance();
178 /**
179 Creates a new transaction context for the transaction with the given
180 XID and adds it to the cache.
181
182 @param xid The XID of the transaction to create and add.
183 @param is_binlogged_arg Whether or not the transaction has already been
184 binlogged.
185 @param src The transaction context and info to be added to the newly
186 created cache item.
187
188 @return false if the pair was successfully inserted, true otherwise.
189 */
190 static bool create_and_insert_new_transaction(XID *xid, bool is_binlogged_arg,
191 const Transaction_ctx *src);
192};
193} // namespace xa
194#endif // XA_TRANSACTION_CACHE_H_INCLUDED
Definition: transaction_info.h:52
Class responsible for managing a cache of Transaction_ctx objects associated with XA transactions.
Definition: transaction_cache.h:54
Transaction_cache()
Class constructor.
Definition: transaction_cache.cc:82
static list get_cached_transactions()
Retrieves the list of transaction contexts cached.
Definition: transaction_cache.cc:170
PSI_mutex_key m_key_LOCK_transaction_cache
The PSI key for the above lock.
Definition: transaction_cache.h:155
std::shared_ptr< Transaction_ctx > transaction_ptr
Definition: transaction_cache.h:56
static void dispose()
Disposes of the transaction cache allocated resources.
Definition: transaction_cache.cc:180
static Transaction_cache & instance()
Initialize a cache to store Transaction_ctx and a mutex to protect access to the cache.
Definition: transaction_cache.cc:185
static bool detach(Transaction_ctx *transaction)
Transaction is marked in the cache as if it's recovered.
Definition: transaction_cache.cc:98
virtual ~Transaction_cache()=default
unordered_map m_transaction_cache
A map holding the cached transaction context, indexed by XID.
Definition: transaction_cache.h:162
static void remove(Transaction_ctx *transaction)
Remove information about transaction from a cache.
Definition: transaction_cache.cc:117
std::vector< transaction_ptr > list
Definition: transaction_cache.h:58
static bool insert(XID *xid, Transaction_ctx *transaction)
Inserts a transaction context identified by a given XID.
Definition: transaction_cache.cc:127
PSI_mutex_info m_transaction_cache_mutexes[1]
The PSI configuration of the above lock and key.
Definition: transaction_cache.h:157
std::function< bool(transaction_ptr const &)> filter_predicate_t
Definition: transaction_cache.h:59
static transaction_ptr find(XID *xid, filter_predicate_t filter=nullptr)
Searches the cache for the transaction context identified by the given XID.
Definition: transaction_cache.cc:159
static void initialize()
Initializes the transaction cache underlying resources.
Definition: transaction_cache.cc:178
Transaction_cache & operator=(Transaction_cache const &)=delete
Transaction_cache(Transaction_cache &&)=delete
mysql_mutex_t m_LOCK_transaction_cache
A lock to serialize the access to m_transaction_cache
Definition: transaction_cache.h:152
Transaction_cache & operator=(Transaction_cache &&)=delete
Transaction_cache(Transaction_cache const &)=delete
static bool create_and_insert_new_transaction(XID *xid, bool is_binlogged_arg, const Transaction_ctx *src)
Creates a new transaction context for the transaction with the given XID and adds it to the cache.
Definition: transaction_cache.cc:190
#define PSI_DOCUMENT_ME
Definition: component_common.h:28
#define PSI_FLAG_SINGLETON
Singleton flag.
Definition: component_common.h:34
unsigned int PSI_mutex_key
Instrumented mutex key.
Definition: psi_mutex_bits.h:51
Some integer typedefs for easier portability.
Definition: recovery.h:38
Mutex information.
Definition: psi_mutex_bits.h:72
An instrumented mutex structure.
Definition: mysql_mutex_bits.h:49
struct xid_t is binary compatible with the XID structure as in the X/Open CAE Specification,...
Definition: xa.h:82