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