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