MySQL 9.0.0
Source Code Documentation
table_cache.h
Go to the documentation of this file.
1/* Copyright (c) 2012, 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 TABLE_CACHE_INCLUDED
25#define TABLE_CACHE_INCLUDED
26
27#include <assert.h>
28#include <stddef.h>
29#include <sys/types.h>
30#include <memory>
31#include <string>
32#include <unordered_map>
33#include <utility>
34
35#include "lex_string.h"
36#include "my_base.h"
37
38#include "my_psi_config.h"
43#include "sql/handler.h"
44#include "sql/sql_base.h"
45#include "sql/sql_class.h"
46#include "sql/sql_plist.h"
48#include "sql/table.h"
49
51
54
55/**
56 Cache for open TABLE objects.
57
58 The idea behind this cache is that most statements don't need to
59 go to a central table definition cache to get a TABLE object and
60 therefore don't need to lock LOCK_open mutex.
61 Instead they only need to go to one Table_cache instance (the
62 specific instance is determined by thread id) and only lock the
63 mutex protecting this cache.
64 DDL statements that need to remove all TABLE objects from all caches
65 need to lock mutexes for all Table_cache instances, but they are rare.
66
67 This significantly increases scalability in some scenarios.
68*/
69
71 private:
72 /**
73 The table cache lock protects the following data:
74
75 1) m_unused_tables list.
76 2) m_cache hash.
77 3) used_tables, free_tables lists in Table_cache_element objects in
78 this cache.
79 4) m_table_count - total number of TABLE objects in this cache.
80 5) the element in TABLE_SHARE::cache_element[] array that corresponds
81 to this cache,
82 6) in_use member in TABLE object.
83 7) Also ownership of mutexes for all caches are required to update
84 the refresh_version and table_def_shutdown_in_progress variables
85 and TABLE_SHARE::version member.
86
87 The intention is that any query that finds a cached table object in
88 its designated table cache should only need to lock this mutex
89 instance and there should be no need to lock LOCK_open. LOCK_open is
90 still required however to create and release TABLE objects. However
91 most usage of the MySQL Server should be able to set the cache size
92 big enough so that the majority of the queries only need to lock this
93 mutex instance and not LOCK_open.
94 */
96
97 /**
98 The hash of Table_cache_element objects, each table/table share that
99 has any TABLE object in the Table_cache has a Table_cache_element from
100 which the list of free TABLE objects in this table cache AND the list
101 of used TABLE objects in this table cache is stored.
102 We use Table_cache_element::share::table_cache_key as key for this hash.
103 */
104 std::unordered_map<std::string, std::unique_ptr<Table_cache_element>> m_cache;
105
106 /**
107 List that contains all TABLE instances for tables in this particular
108 table cache that are in not use by any thread. Recently used TABLE
109 instances are appended to the end of the list. Thus the beginning of
110 the list contains which have been least recently used.
111 */
113
114 /**
115 Total number of TABLE instances for tables in this particular table
116 cache (both in use by threads and not in use).
117 This value summed over all table caches is accessible to users as
118 Open_tables status variable.
119 */
121
122#ifdef HAVE_PSI_INTERFACE
125#endif
126
127 private:
128#ifdef EXTRA_DEBUG
129 void check_unused();
130#else
131 void check_unused() {}
132#endif
133 inline void link_unused_table(TABLE *table);
134 inline void unlink_unused_table(TABLE *table);
135
136 inline void free_unused_tables_if_necessary(THD *thd);
137
138 public:
139 bool init();
140 void destroy();
141 static void init_psi_keys();
142
143 /** Acquire lock on table cache instance. */
145 /** Release lock on table cache instance. */
147 /** Assert that caller owns lock on the table cache. */
149
150 inline TABLE *get_table(THD *thd, const char *key, size_t key_length,
151 TABLE_SHARE **share);
152
153 inline void release_table(THD *thd, TABLE *table);
154
155 inline bool add_used_table(THD *thd, TABLE *table);
156 inline void remove_table(TABLE *table);
157
158 /** Get number of TABLE instances in the cache. */
159 uint cached_tables() const { return m_table_count; }
160
162
163#ifndef NDEBUG
164 void print_tables();
165#endif
166};
167
168/**
169 Container class for all table cache instances in the system.
170*/
171
173 public:
174 /** Maximum supported number of table cache instances. */
175 static const int MAX_TABLE_CACHES = 64;
176
177 /** Default number of table cache instances */
178 static const int DEFAULT_MAX_TABLE_CACHES = 16;
179
180 bool init();
181 void destroy();
182
183 /** Get instance of table cache to be used by particular connection. */
186 }
187
188 /** Get index for the table cache in container. */
189 uint cache_index(Table_cache *cache) const {
190 return static_cast<uint>(cache - &m_table_cache[0]);
191 }
192
193 uint cached_tables();
194
195 void lock_all_and_tdc();
196 void unlock_all_and_tdc();
197 void assert_owner(THD *thd);
198 void assert_owner_all();
200
201 void free_table(THD *thd, enum_tdc_remove_table_type remove_type,
202 TABLE_SHARE *share);
203
205
206#ifndef NDEBUG
207 void print_tables();
208#endif
209
211
212 private:
213 /**
214 An array of Table_cache instances.
215 Only the first table_cache_instances elements in it are used.
216 */
218};
219
221
222/**
223 Element that represents the table in the specific table cache.
224 Plays for table cache instance role similar to role of TABLE_SHARE
225 for table definition cache.
226
227 It is an implementation detail of Table_cache and is present
228 in the header file only to allow inlining of some methods.
229*/
230
232 private:
233 /*
234 Doubly-linked (back-linked) lists of used and unused TABLE objects
235 for this table in this table cache (one such list per table cache).
236 */
237 typedef I_P_List<
240
244
245 public:
246 Table_cache_element(TABLE_SHARE *share_arg) : share(share_arg) {}
247
248 TABLE_SHARE *get_share() const { return share; }
249
250 friend class Table_cache;
253};
254
255/**
256 Iterator which allows to go through all used TABLE instances
257 for the table in all table caches.
258*/
259
264
265 inline void move_to_next_table();
266
267 public:
268 /**
269 Construct iterator over all used TABLE objects for the table share.
270
271 @note Assumes that caller owns locks on all table caches.
272 */
273 inline Table_cache_iterator(const TABLE_SHARE *share_arg);
274 inline TABLE *operator++(int);
275 inline void rewind();
276};
277
278/**
279 Add table to the tail of unused tables list for table cache
280 (i.e. as the most recently used table in this list).
281*/
282
284 if (m_unused_tables) {
285 table->next = m_unused_tables;
286 table->prev = m_unused_tables->prev;
288 table->prev->next = table;
289 } else
290 m_unused_tables = table->next = table->prev = table;
291 check_unused();
292}
293
294/** Remove table from the unused tables list for table cache. */
295
297 table->next->prev = table->prev;
298 table->prev->next = table->next;
299 if (table == m_unused_tables) {
301 if (table == m_unused_tables) m_unused_tables = nullptr;
302 }
303 check_unused();
304}
305
306/**
307 Free unused TABLE instances if total number of TABLE objects
308 in table cache has exceeded table_cache_size_per_instance
309 limit.
310
311 @note That we might need to free more than one instance during
312 this call if table_cache_size was changed dynamically.
313*/
314
316 /*
317 We have too many TABLE instances around let us try to get rid of them.
318
319 Note that we might need to free more than one TABLE object, and thus
320 need the below loop, in case when table_cache_size is changed dynamically,
321 at server run time.
322 */
326 TABLE *table_to_free = m_unused_tables;
327 remove_table(table_to_free);
328 intern_close_table(table_to_free);
332 }
334 }
335}
336
337/**
338 Add newly created TABLE object which is going to be used right away
339 to the table cache.
340
341 @note Caller should own lock on the table cache.
342
343 @note Sets TABLE::in_use member as side effect.
344
345 @retval false - success.
346 @retval true - failure.
347*/
348
351
352 assert_owner();
353
354 assert(table->in_use == thd);
355
356 /*
357 Try to get Table_cache_element representing this table in the cache
358 from array in the TABLE_SHARE.
359 */
360 el = table->s->cache_element[table_cache_manager.cache_index(this)];
361
362 if (!el) {
363 /*
364 If TABLE_SHARE doesn't have pointer to the element representing table
365 in this cache, the element for the table must be absent from table the
366 cache.
367
368 Allocate new Table_cache_element object and add it to the cache
369 and array in TABLE_SHARE.
370 */
371 const std::string key(table->s->table_cache_key.str,
372 table->s->table_cache_key.length);
373 assert(m_cache.count(key) == 0);
374
375 el = new Table_cache_element(table->s);
376 m_cache.emplace(key, std::unique_ptr<Table_cache_element>(el));
377 table->s->cache_element[table_cache_manager.cache_index(this)] = el;
378 }
379
380 /* Add table to the used tables list */
382
384
386
387 return false;
388}
389
390/**
391 Prepare used or unused TABLE instance for destruction by removing
392 it from the table cache.
393
394 @note Caller should own lock on the table cache.
395*/
396
399 table->s->cache_element[table_cache_manager.cache_index(this)];
400
401 assert_owner();
402
403 if (table->in_use) {
404 /* Remove from per-table chain of used TABLE objects. */
406 } else {
407 /* Remove from per-table chain of unused TABLE objects. */
409
410 /* And per-cache unused chain. */
412 }
413
415
416 if (el->used_tables.is_empty() && el->free_tables.is_empty()) {
417 const std::string key(table->s->table_cache_key.str,
418 table->s->table_cache_key.length);
419 m_cache.erase(key);
420 /*
421 Remove reference to deleted cache element from array
422 in the TABLE_SHARE.
423 */
424 table->s->cache_element[table_cache_manager.cache_index(this)] = nullptr;
425 }
426}
427
428/**
429 Get an unused TABLE instance from the table cache.
430
431 @param thd Thread context.
432 @param key Key identifying table.
433 @param key_length Length of key for the table.
434 @param[out] share NULL - if table cache doesn't contain any
435 information about the table (i.e. doesn't have
436 neither used nor unused TABLE objects for it).
437 Pointer to TABLE_SHARE for the table otherwise.
438
439 @note Caller should own lock on the table cache.
440 @note Sets TABLE::in_use member as side effect.
441
442 @retval non-NULL - pointer to unused TABLE object, "share" out-parameter
443 contains pointer to TABLE_SHARE for this table.
444 @retval NULL - no unused TABLE object was found, "share" parameter
445 contains pointer to TABLE_SHARE for this table if there
446 are used TABLE objects in cache and NULL otherwise.
447*/
448
449TABLE *Table_cache::get_table(THD *thd, const char *key, size_t key_length,
450 TABLE_SHARE **share) {
451 TABLE *table;
452
453 assert_owner();
454
455 *share = nullptr;
456
457 const std::string key_str(key, key_length);
458 const auto el_it = m_cache.find(key_str);
459 if (el_it == m_cache.end()) return nullptr;
460 Table_cache_element *el = el_it->second.get();
461
462 *share = el->share;
463
464 if ((table = el->free_tables.front())) {
465 assert(!table->in_use);
466
467 /*
468 Unlink table from list of unused TABLE objects for this
469 table in this cache.
470 */
472
473 /* Unlink table from unused tables list for this cache. */
475
476 /*
477 Add table to list of used TABLE objects for this table
478 in the table cache.
479 */
481
482 table->in_use = thd;
483 /* The ex-unused table must be fully functional. */
484 assert(table->db_stat && table->file);
485 /* The children must be detached from the table. */
486 assert(!table->file->ha_extra(HA_EXTRA_IS_ATTACHED_CHILDREN));
487 }
488
489 return table;
490}
491
492/**
493 Put used TABLE instance back to the table cache and mark
494 it as unused.
495
496 @note Caller should own lock on the table cache.
497 @note Sets TABLE::in_use member as side effect.
498*/
499
502 table->s->cache_element[table_cache_manager.cache_index(this)];
503
504 assert_owner();
505
506 assert(table->in_use);
507 assert(table->file);
508
509 /* We shouldn't put the table to 'unused' list if the share is old. */
510 assert(!table->s->has_old_version());
511
512 table->in_use = nullptr;
513
514 /* Remove TABLE from the list of used objects for the table in this cache. */
516 /* Add TABLE to the list of unused objects for the table in this cache. */
518 /* Also link it last in the list of unused TABLE objects for the cache. */
520
521 /*
522 We free the least used tables, not the subject table, to keep the LRU order.
523 Note that in most common case the below call won't free anything.
524 */
526}
527
528/**
529 Construct iterator over all used TABLE objects for the table share.
530
531 @note Assumes that caller owns locks on all table caches.
532*/
534 : share(share_arg), current_cache_index(0), current_table(nullptr) {
537}
538
539/** Helper that moves iterator to the next used TABLE for the table share. */
540
544
546 if ((current_table = el->used_tables.front())) break;
547 }
548 }
549}
550
551/**
552 Get current used TABLE instance and move iterator to the next one.
553
554 @note Assumes that caller owns locks on all table caches.
555*/
556
559
561
562 if (current_table) {
565
566 current_table = ++it;
567
568 if (!current_table) {
571 }
572 }
573
574 return result;
575}
576
579 current_table = nullptr;
581}
582
583#endif /* TABLE_CACHE_INCLUDED */
Kerberos Client Authentication nullptr
Definition: auth_kerberos_client_plugin.cc:251
Iterator for I_P_List.
Definition: sql_plist.h:168
Intrusive parameterized list.
Definition: sql_plist.h:75
void remove(T *a)
Definition: sql_plist.h:124
bool is_empty() const
Definition: sql_plist.h:90
T * front()
Definition: sql_plist.h:133
void push_front(T *a)
Definition: sql_plist.h:91
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_lexer_thd.h:36
my_thread_id thread_id() const
Definition: sql_class.h:2539
struct System_status_var status_var
Definition: sql_class.h:1152
Element that represents the table in the specific table cache.
Definition: table_cache.h:231
TABLE_SHARE * get_share() const
Definition: table_cache.h:248
Table_cache_element(TABLE_SHARE *share_arg)
Definition: table_cache.h:246
TABLE_list used_tables
Definition: table_cache.h:241
I_P_List< TABLE, I_P_List_adapter< TABLE, &TABLE::cache_next, &TABLE::cache_prev > > TABLE_list
Definition: table_cache.h:239
TABLE_list free_tables
Definition: table_cache.h:242
TABLE_SHARE * share
Definition: table_cache.h:243
Iterator which allows to go through all used TABLE instances for the table in all table caches.
Definition: table_cache.h:260
const TABLE_SHARE * share
Definition: table_cache.h:261
Table_cache_iterator(const TABLE_SHARE *share_arg)
Construct iterator over all used TABLE objects for the table share.
Definition: table_cache.h:533
uint current_cache_index
Definition: table_cache.h:262
void move_to_next_table()
Helper that moves iterator to the next used TABLE for the table share.
Definition: table_cache.h:541
TABLE * current_table
Definition: table_cache.h:263
void rewind()
Definition: table_cache.h:577
TABLE * operator++(int)
Get current used TABLE instance and move iterator to the next one.
Definition: table_cache.h:557
Container class for all table cache instances in the system.
Definition: table_cache.h:172
Table_cache m_table_cache[MAX_TABLE_CACHES]
An array of Table_cache instances.
Definition: table_cache.h:217
uint cached_tables()
Get total number of used and unused TABLE objects in all table caches.
Definition: table_cache.cc:214
void unlock_all_and_tdc()
Release locks on all instances of table cache and table definition cache.
Definition: table_cache.cc:239
void print_tables()
Print debug information for the contents of all table cache instances.
Definition: table_cache.cc:349
void lock_all_and_tdc()
Acquire locks on all instances of table cache and table definition cache (i.e.
Definition: table_cache.cc:228
void assert_owner_all_and_tdc()
Assert that caller owns locks on all instances of table cache and table definition cache.
Definition: table_cache.cc:269
bool init()
Initialize all instances of table cache to be used by server.
Definition: table_cache.cc:189
uint cache_index(Table_cache *cache) const
Get index for the table cache in container.
Definition: table_cache.h:189
void assert_owner_all()
Assert that caller owns locks on all instances of table cache.
Definition: table_cache.cc:259
void free_all_unused_tables()
Free all unused TABLE objects in all table cache instances.
Definition: table_cache.cc:337
static const int MAX_TABLE_CACHES
Maximum supported number of table cache instances.
Definition: table_cache.h:175
Table_cache * get_cache(THD *thd)
Get instance of table cache to be used by particular connection.
Definition: table_cache.h:184
void free_table(THD *thd, enum_tdc_remove_table_type remove_type, TABLE_SHARE *share)
Remove and free all or some (depending on parameter) TABLE objects for the table from all table cache...
Definition: table_cache.cc:286
static const int DEFAULT_MAX_TABLE_CACHES
Default number of table cache instances.
Definition: table_cache.h:178
void assert_owner(THD *thd)
Assert that caller owns lock on the table cache.
Definition: table_cache.cc:250
void destroy()
Destroy all instances of table cache which were used by server.
Definition: table_cache.cc:203
Cache for open TABLE objects.
Definition: table_cache.h:70
TABLE * get_table(THD *thd, const char *key, size_t key_length, TABLE_SHARE **share)
Get an unused TABLE instance from the table cache.
Definition: table_cache.h:449
void lock()
Acquire lock on table cache instance.
Definition: table_cache.h:144
bool add_used_table(THD *thd, TABLE *table)
Add newly created TABLE object which is going to be used right away to the table cache.
Definition: table_cache.h:349
void unlock()
Release lock on table cache instance.
Definition: table_cache.h:146
bool init()
Initialize instance of table cache.
Definition: table_cache.cc:55
void release_table(THD *thd, TABLE *table)
Put used TABLE instance back to the table cache and mark it as unused.
Definition: table_cache.h:500
std::unordered_map< std::string, std::unique_ptr< Table_cache_element > > m_cache
The hash of Table_cache_element objects, each table/table share that has any TABLE object in the Tabl...
Definition: table_cache.h:104
void destroy()
Destroy instance of table cache.
Definition: table_cache.cc:64
mysql_mutex_t m_lock
The table cache lock protects the following data:
Definition: table_cache.h:95
uint m_table_count
Total number of TABLE instances for tables in this particular table cache (both in use by threads and...
Definition: table_cache.h:120
void assert_owner()
Assert that caller owns lock on the table cache.
Definition: table_cache.h:148
void free_all_unused_tables()
Free all unused TABLE objects in the table cache.
Definition: table_cache.cc:123
void check_unused()
Definition: table_cache.h:131
TABLE * m_unused_tables
List that contains all TABLE instances for tables in this particular table cache that are in not use ...
Definition: table_cache.h:112
void link_unused_table(TABLE *table)
Add table to the tail of unused tables list for table cache (i.e.
Definition: table_cache.h:283
static PSI_mutex_info m_mutex_keys[]
Definition: table_cache.h:124
static void init_psi_keys()
Init P_S instrumentation key for mutex protecting Table_cache instance.
Definition: table_cache.cc:68
void unlink_unused_table(TABLE *table)
Remove table from the unused tables list for table cache.
Definition: table_cache.h:296
uint cached_tables() const
Get number of TABLE instances in the cache.
Definition: table_cache.h:159
static PSI_mutex_key m_lock_key
Definition: table_cache.h:123
void print_tables()
Print debug information for the contents of the table cache.
Definition: table_cache.cc:138
void remove_table(TABLE *table)
Prepare used or unused TABLE instance for destruction by removing it from the table cache.
Definition: table_cache.h:397
void free_unused_tables_if_necessary(THD *thd)
Free unused TABLE instances if total number of TABLE objects in table cache has exceeded table_cache_...
Definition: table_cache.h:315
#define mysql_mutex_lock(M)
Definition: mysql_mutex.h:50
#define mysql_mutex_unlock(M)
Definition: mysql_mutex.h:57
mysql_mutex_t LOCK_open
LOCK_open protects the following variables/objects:
Definition: sql_base.cc:276
void intern_close_table(TABLE *table)
Definition: sql_base.cc:1191
unsigned int PSI_mutex_key
Instrumented mutex key.
Definition: psi_mutex_bits.h:52
#define mysql_mutex_assert_owner(M)
Wrapper, to use safe_mutex_assert_owner with instrumented mutexes.
Definition: mysql_mutex.h:112
This file includes constants used by all storage engines.
@ HA_EXTRA_IS_ATTACHED_CHILDREN
Definition: my_base.h:400
Defines various enable/disable and HAVE_ macros related to the performance schema instrumentation sys...
ABI for instrumented mutexes.
static PFS_engine_table_share_proxy table
Definition: pfs.cc:61
struct result result
Definition: result.h:34
Instrumentation helpers for mutexes.
Instrumentation helpers for mutexes.
required string key
Definition: replication_asynchronous_connection_failover.proto:60
enum_tdc_remove_table_type
Definition: sql_base.h:101
Hook class which via its methods specifies which members of T should be used for participating in a i...
Definition: sql_plist.h:198
Mutex information.
Definition: psi_mutex_bits.h:73
ulonglong table_open_cache_overflows
Definition: system_variables.h:556
This structure is shared between different table objects.
Definition: table.h:701
Table_cache_element ** cache_element
Array of table_cache_instances pointers to elements of table caches respresenting this table in each ...
Definition: table.h:746
Definition: table.h:1407
TABLE * next
Definition: table.h:1410
TABLE * prev
Definition: table.h:1410
std::atomic_uint64_t table_open_cache_overflows
Definition: aggregated_stats_buffer.h:60
To facilitate calculating values of status variables aggregated per all THDs in real-time,...
Definition: aggregated_stats.h:39
aggregated_stats_buffer & get_shard(my_thread_id thread_id)
Definition: aggregated_stats.h:42
An instrumented mutex structure.
Definition: mysql_mutex_bits.h:50
Definition: result.h:30
ulong table_cache_instances
Definition: table_cache.h:52
struct aggregated_stats global_aggregated_stats
Definition: mysqld.cc:1540
Table_cache_manager table_cache_manager
Container for all table cache instances in the system.
Definition: table_cache.cc:40
ulong table_cache_size_per_instance
Definition: mysqld.cc:1345