MySQL 8.1.0
Source Code Documentation
ibuf0ibuf.h
Go to the documentation of this file.
1/*****************************************************************************
2
3Copyright (c) 1997, 2023, Oracle and/or its affiliates.
4
5This program is free software; you can redistribute it and/or modify it under
6the terms of the GNU General Public License, version 2.0, as published by the
7Free Software Foundation.
8
9This program is also distributed with certain software (including but not
10limited to OpenSSL) that is licensed under separate terms, as designated in a
11particular file or component or in included license documentation. The authors
12of MySQL hereby grant you an additional permission to link the program and
13your derivative works with the separately licensed software that they have
14included with MySQL.
15
16This program is distributed in the hope that it will be useful, but WITHOUT
17ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
19for more details.
20
21You should have received a copy of the GNU General Public License along with
22this program; if not, write to the Free Software Foundation, Inc.,
2351 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24
25*****************************************************************************/
26
27/** @file include/ibuf0ibuf.h
28 Insert buffer
29
30 Created 7/19/1997 Heikki Tuuri
31 *******************************************************/
32
33#ifndef ibuf0ibuf_h
34#define ibuf0ibuf_h
35
36#include "univ.i"
37
38#include "dict0mem.h"
39#include "fsp0fsp.h"
40#include "mtr0mtr.h"
41
42#include "ibuf0types.h"
43
44/** Default value for maximum on-disk size of change buffer in terms
45of percentage of the buffer pool. */
46constexpr uint32_t CHANGE_BUFFER_DEFAULT_SIZE = 25;
47
48#ifndef UNIV_HOTBACKUP
49/* Possible operations buffered in the insert/whatever buffer. See
50ibuf_insert(). DO NOT CHANGE THE VALUES OF THESE, THEY ARE STORED ON DISK. */
51typedef enum {
55
56 /* Number of different operation types. */
59
60/** Combinations of operations that can be buffered.
61@see innodb_change_buffering_names */
64 IBUF_USE_INSERT, /* insert */
66 IBUF_USE_INSERT_DELETE_MARK, /* insert+delete */
67 IBUF_USE_DELETE, /* delete+purge */
68 IBUF_USE_ALL /* insert+delete+purge */
69};
70
71/** Operations that can currently be buffered. */
72extern ulong innodb_change_buffering;
73
74/** The insert buffer control structure */
75extern ibuf_t *ibuf;
76
77/* The purpose of the insert buffer is to reduce random disk access.
78When we wish to insert a record into a non-unique secondary index and
79the B-tree leaf page where the record belongs to is not in the buffer
80pool, we insert the record into the insert buffer B-tree, indexed by
81(space_id, page_no). When the page is eventually read into the buffer
82pool, we look up the insert buffer B-tree for any modifications to the
83page, and apply these upon the completion of the read operation. This
84is called the insert buffer merge. */
85
86/* The insert buffer merge must always succeed. To guarantee this,
87the insert buffer subsystem keeps track of the free space in pages for
88which it can buffer operations. Two bits per page in the insert
89buffer bitmap indicate the available space in coarse increments. The
90free bits in the insert buffer bitmap must never exceed the free space
91on a page. It is safe to decrement or reset the bits in the bitmap in
92a mini-transaction that is committed before the mini-transaction that
93affects the free space. It is unsafe to increment the bits in a
94separately committed mini-transaction, because in crash recovery, the
95free bits could momentarily be set too high. */
96
97/** Creates the insert buffer data structure at a database startup. */
98void ibuf_init_at_db_start(void);
99/** Updates the max_size value for ibuf. */
100void ibuf_max_size_update(ulint new_val); /*!< in: new value in terms of
101 percentage of the buffer pool size */
102/** Reads the biggest tablespace id from the high end of the insert buffer
103 tree and updates the counter in fil_system. */
105/** Starts an insert buffer mini-transaction. */
106static inline void ibuf_mtr_start(mtr_t *mtr); /*!< out: mini-transaction */
107/** Commits an insert buffer mini-transaction. */
108static inline void ibuf_mtr_commit(mtr_t *mtr); /*!< in/out: mini-transaction */
109
110/** Initializes an ibuf bitmap page. */
111void ibuf_bitmap_page_init(buf_block_t *block, /*!< in: bitmap page */
112 mtr_t *mtr /*!< in: mtr */);
113
114/** Resets the free bits of the page in the ibuf bitmap. This is done in a
115 separate mini-transaction, hence this operation does not restrict
116 further work to only ibuf bitmap operations, which would result if the
117 latch to the bitmap page were kept. NOTE: The free bits in the insert
118 buffer bitmap must never exceed the free space on a page. It is safe
119 to decrement or reset the bits in the bitmap in a mini-transaction
120 that is committed before the mini-transaction that affects the free
121 space. */
123 buf_block_t *block); /*!< in: index page; free bits are set to 0
124 if the index is a non-clustered
125 non-unique, and page level is 0 */
126
127/** Updates the free bits of an uncompressed page in the ibuf bitmap if there
128is not enough free on the page any more. This is done in a separate
129mini-transaction, hence this operation does not restrict further work to only
130ibuf bitmap operations, which would result if the latch to the bitmap page were
131kept. NOTE: The free bits in the insert buffer bitmap must never exceed the
132free space on a page. It is unsafe to increment the bits in a separately
133committed mini-transaction, because in crash recovery, the free bits could
134momentarily be set too high. It is only safe to use this function for
135decrementing the free bits. Should more free space become available, we must
136not update the free bits here, because that would break crash recovery.
137@param[in] block index page to which we have added new records;
138 the free bits are updated if the index is
139 non-clustered and non-unique and the page level
140 is 0, and the page becomes fuller
141@param[in] max_ins_size value of maximum insert size with reorganize
142 before the latest operation performed to the
143 page
144@param[in] increase upper limit for the additional space used in
145 the latest operation, if known, or
146 ULINT_UNDEFINED */
148 ulint max_ins_size,
149 ulint increase);
150
151/** Updates the free bits for an uncompressed page to reflect the present
152 state. Does this in the mtr given, which means that the latching
153 order rules virtually prevent any further operations for this OS
154 thread until mtr is committed. NOTE: The free bits in the insert
155 buffer bitmap must never exceed the free space on a page. It is safe
156 to set the free bits in the same mini-transaction that updated the
157 page. */
158void ibuf_update_free_bits_low(const buf_block_t *block, /*!< in: index page */
159 ulint max_ins_size, /*!< in: value of
160 maximum insert size
161 with reorganize before
162 the latest operation
163 performed to the page */
164 mtr_t *mtr); /*!< in/out: mtr */
165/** Updates the free bits for a compressed page to reflect the present
166 state. Does this in the mtr given, which means that the latching
167 order rules virtually prevent any further operations for this OS
168 thread until mtr is committed. NOTE: The free bits in the insert
169 buffer bitmap must never exceed the free space on a page. It is safe
170 to set the free bits in the same mini-transaction that updated the
171 page. */
172void ibuf_update_free_bits_zip(buf_block_t *block, /*!< in/out: index page */
173 mtr_t *mtr); /*!< in/out: mtr */
174/** Updates the free bits for the two pages to reflect the present state.
175 Does this in the mtr given, which means that the latching order rules
176 virtually prevent any further operations until mtr is committed.
177 NOTE: The free bits in the insert buffer bitmap must never exceed the
178 free space on a page. It is safe to set the free bits in the same
179 mini-transaction that updated the pages. */
181 buf_block_t *block1, /*!< in: index page */
182 buf_block_t *block2, /*!< in: index page */
183 mtr_t *mtr); /*!< in: mtr */
184
185/** A basic partial test if an insert to the insert buffer could be possible
186and recommended.
187@param[in] index index where to insert
188@param[in] ignore_sec_unique if != 0, we should ignore UNIQUE
189 constraint on a secondary index when
190 we decide*/
191static inline bool ibuf_should_try(dict_index_t *index,
192 ulint ignore_sec_unique);
193
194/** Returns true if the current OS thread is performing an insert buffer
195 routine.
196
197 For instance, a read-ahead of non-ibuf pages is forbidden by threads
198 that are executing an insert buffer routine.
199 @return true if inside an insert buffer routine */
200[[nodiscard]] static inline bool ibuf_inside(
201 const mtr_t *mtr); /*!< in: mini-transaction */
202
203/** Checks if a page address is an ibuf bitmap page (level 3 page) address.
204@param[in] page_id page id
205@param[in] page_size page size
206@return true if a bitmap page */
207static inline bool ibuf_bitmap_page(const page_id_t &page_id,
208 const page_size_t &page_size);
209
210/** Checks if a page is a level 2 or 3 page in the ibuf hierarchy of pages.
211Must not be called when recv_no_ibuf_operations==true.
212@param[in] page_id page id
213@param[in] page_size page size
214@param[in] x_latch false if relaxed check (avoid latching the
215bitmap page)
216@param[in] location Location where called
217@param[in,out] mtr mtr which will contain an x-latch to the
218bitmap page if the page is not one of the fixed address ibuf pages, or NULL,
219in which case a new transaction is created.
220@return true if level 2 or level 3 page */
221[[nodiscard]] bool ibuf_page_low(const page_id_t &page_id,
222 const page_size_t &page_size,
223 IF_DEBUG(bool x_latch, ) ut::Location location,
224 mtr_t *mtr) MY_ATTRIBUTE((warn_unused_result));
225
226/** Checks if a page is a level 2 or 3 page in the ibuf hierarchy of pages.
227Must not be called when recv_no_ibuf_operations==true.
228@param[in] page_id Tablespace/page identifier
229@param[in] page_size Page size
230@param[in] location Location where requested
231@param[in,out] mtr Mini-transaction or NULL
232@return true if level 2 or level 3 page */
233inline bool ibuf_page(const page_id_t &page_id, const page_size_t &page_size,
234 ut::Location location, mtr_t *mtr) {
235 return ibuf_page_low(page_id, page_size, IF_DEBUG(true, ) location, mtr);
236}
237
238/** Frees excess pages from the ibuf free list. This function is called when an
239OS thread calls fsp services to allocate a new file segment, or a new page to a
240file segment, and the thread did not own the fsp latch before this call. */
241void ibuf_free_excess_pages(void);
242
243/** Buffer an operation in the insert/delete buffer, instead of doing it
244directly to the disk page, if this is possible. Does not do it if the index
245is clustered or unique.
246@param[in] op operation type
247@param[in] entry index entry to insert
248@param[in,out] index index where to insert
249@param[in] page_id page id where to insert
250@param[in] page_size page size
251@param[in,out] thr query thread
252@return true if success */
253bool ibuf_insert(ibuf_op_t op, const dtuple_t *entry, dict_index_t *index,
254 const page_id_t &page_id, const page_size_t &page_size,
255 que_thr_t *thr);
256
257/** When an index page is read from a disk to the buffer pool, this function
258applies any buffered operations to the page and deletes the entries from the
259insert buffer. If the page is not read, but created in the buffer pool, this
260function deletes its buffered entries from the insert buffer; there can
261exist entries for such a page if the page belonged to an index which
262subsequently was dropped.
263@param[in,out] block if page has been read from disk,
264pointer to the page x-latched, else NULL
265@param[in] page_id page id of the index page
266@param[in] update_ibuf_bitmap normally this is set to true, but
267if we have deleted or are deleting the tablespace, then we naturally do not
268want to update a non-existent bitmap page
269@param[in] page_size page size */
270void ibuf_merge_or_delete_for_page(buf_block_t *block, const page_id_t &page_id,
271 const page_size_t *page_size,
272 bool update_ibuf_bitmap);
273
274/** Deletes all entries in the insert buffer for a given space id. This is used
275in DISCARD TABLESPACE and IMPORT TABLESPACE.
276NOTE: this does not update the page free bitmaps in the space. The space will
277become CORRUPT when you call this function! */
278void ibuf_delete_for_discarded_space(space_id_t space); /*!< in: space id */
279/** Contract the change buffer by reading pages to the buffer pool.
280@param[in] full If true, do a full contraction based on
281PCT_IO(100). If false, the size of contract batch is determined based on the
282current size of the change buffer.
283@return a lower limit for the combined size in bytes of entries which will be
284merged from ibuf trees to the pages read, 0 if ibuf is empty */
286
287/** Contracts insert buffer trees by reading pages referring to space_id
288to the buffer pool.
289@returns number of pages merged.*/
290ulint ibuf_merge_space(space_id_t space); /*!< in: space id */
291
292#endif /* !UNIV_HOTBACKUP */
293/** Parses a redo log record of an ibuf bitmap page init.
294@param[in] ptr Buffer.
295@param[in] end_ptr Buffer end.
296@param[in] block Block or nullptr.
297@param[in] mtr MTR or nullptr.
298@return end of log record or NULL */
299byte *ibuf_parse_bitmap_init(byte *ptr, byte *end_ptr, buf_block_t *block,
300 mtr_t *mtr);
301#ifndef UNIV_HOTBACKUP
302#ifdef UNIV_IBUF_COUNT_DEBUG
303
304/** Gets the ibuf count for a given page.
305@param[in] page_id page id
306@return number of entries in the insert buffer currently buffered for
307this page */
308ulint ibuf_count_get(const page_id_t &page_id);
309
310#endif /* UNIV_IBUF_COUNT_DEBUG */
311
312/** Looks if the insert buffer is empty.
313 @return true if empty */
314bool ibuf_is_empty(void);
315/** Prints info of ibuf. */
316void ibuf_print(FILE *file); /*!< in: file where to print */
317/********************************************************************
318Read the first two bytes from a record's fourth field (counter field in new
319records; something else in older records).
320@return "counter" field, or ULINT_UNDEFINED if for some reason it can't be read
321*/
322ulint ibuf_rec_get_counter(const rec_t *rec); /*!< in: ibuf record */
323
324/** Determine if there is any multi-value field data on the change buffer
325record
326@param[in] rec ibuf record
327@return true if there is any multi-value field in the record */
328bool ibuf_rec_has_multi_value(const rec_t *rec);
329
330/** Closes insert buffer and frees the data structures. */
331void ibuf_close(void);
332
333/** Checks the insert buffer bitmaps on IMPORT TABLESPACE.
334 @return DB_SUCCESS or error code */
336 const trx_t *trx, /*!< in: transaction */
337 space_id_t space_id); /*!< in: tablespace identifier */
338
339/** Updates free bits and buffered bits for bulk loaded page.
340@param[in] block index page
341@param[in] reset flag if reset free val */
343
346
347#endif /* !UNIV_HOTBACKUP */
348
349/* The ibuf header page currently contains only the file segment header
350for the file segment from which the pages for the ibuf tree are allocated */
351constexpr uint32_t IBUF_HEADER = PAGE_DATA;
352/** fseg header for ibuf tree */
353constexpr uint32_t IBUF_TREE_SEG_HEADER = 0;
354
355#include "ibuf0ibuf.ic"
356
357#endif
uint32_t space_id_t
Tablespace identifier.
Definition: api0api.h:50
Page identifier.
Definition: buf0types.h:206
Page size descriptor.
Definition: page0size.h:49
dberr_t
Definition: db0err.h:38
Data dictionary memory object creation.
File space management.
constexpr uint32_t FSP_IBUF_TREE_ROOT_PAGE_NO
insert buffer B-tree root page in tablespace 0; The ibuf tree root page number in tablespace 0; its f...
Definition: fsp0types.h:167
constexpr uint32_t FSP_IBUF_HEADER_PAGE_NO
The following pages exist in the system tablespace (space 0).
Definition: fsp0types.h:163
static bool ibuf_bitmap_page(const page_id_t &page_id, const page_size_t &page_size)
Checks if a page address is an ibuf bitmap page (level 3 page) address.
bool ibuf_page(const page_id_t &page_id, const page_size_t &page_size, ut::Location location, mtr_t *mtr)
Checks if a page is a level 2 or 3 page in the ibuf hierarchy of pages.
Definition: ibuf0ibuf.h:233
ulint ibuf_merge_in_background(bool full)
Contract the change buffer by reading pages to the buffer pool.
Definition: ibuf0ibuf.cc:2392
constexpr uint32_t IBUF_TREE_SEG_HEADER
fseg header for ibuf tree
Definition: ibuf0ibuf.h:353
void ibuf_print(FILE *file)
Prints info of ibuf.
Definition: ibuf0ibuf.cc:4378
void ibuf_delete_for_discarded_space(space_id_t space)
Deletes all entries in the insert buffer for a given space id.
Definition: ibuf0ibuf.cc:4283
bool ibuf_rec_has_multi_value(const rec_t *rec)
Determine if there is any multi-value field data on the change buffer record.
Definition: ibuf0ibuf.cc:1213
bool ibuf_is_empty(void)
Looks if the insert buffer is empty.
Definition: ibuf0ibuf.cc:4359
void ibuf_init_at_db_start(void)
Creates the insert buffer data structure at a database startup.
Definition: ibuf0ibuf.cc:456
void ibuf_merge_or_delete_for_page(buf_block_t *block, const page_id_t &page_id, const page_size_t *page_size, bool update_ibuf_bitmap)
When an index page is read from a disk to the buffer pool, this function applies any buffered operati...
Definition: ibuf0ibuf.cc:3961
static bool ibuf_inside(const mtr_t *mtr)
Returns true if the current OS thread is performing an insert buffer routine.
constexpr uint32_t IBUF_HEADER
Definition: ibuf0ibuf.h:351
byte * ibuf_parse_bitmap_init(byte *ptr, byte *end_ptr, buf_block_t *block, mtr_t *mtr)
Parses a redo log record of an ibuf bitmap page init.
Definition: ibuf0ibuf.cc:564
void ibuf_update_free_bits_low(const buf_block_t *block, ulint max_ins_size, mtr_t *mtr)
Updates the free bits for an uncompressed page to reflect the present state.
Definition: ibuf0ibuf.cc:838
static void ibuf_mtr_commit(mtr_t *mtr)
Commits an insert buffer mini-transaction.
void ibuf_max_size_update(ulint new_val)
Updates the max_size value for ibuf.
Definition: ibuf0ibuf.cc:529
void ibuf_update_max_tablespace_id(void)
Reads the biggest tablespace id from the high end of the insert buffer tree and updates the counter i...
Definition: ibuf0ibuf.cc:2808
static void ibuf_mtr_start(mtr_t *mtr)
Starts an insert buffer mini-transaction.
dberr_t ibuf_check_bitmap_on_import(const trx_t *trx, space_id_t space_id)
Checks the insert buffer bitmaps on IMPORT TABLESPACE.
Definition: ibuf0ibuf.cc:4419
ulong innodb_change_buffering
Operations that can currently be buffered.
Definition: ibuf0ibuf.cc:202
void ibuf_set_bitmap_for_bulk_load(buf_block_t *block, bool reset)
Updates free bits and buffered bits for bulk loaded page.
Definition: ibuf0ibuf.cc:4537
bool ibuf_page_low(const page_id_t &page_id, const page_size_t &page_size, bool x_latch, ut::Location location, mtr_t *mtr)
Checks if a page is a level 2 or 3 page in the ibuf hierarchy of pages.
Definition: ibuf0ibuf.cc:953
static void ibuf_update_free_bits_if_full(buf_block_t *block, ulint max_ins_size, ulint increase)
Updates the free bits of an uncompressed page in the ibuf bitmap if there is not enough free on the p...
void ibuf_free_excess_pages(void)
Frees excess pages from the ibuf free list.
Definition: ibuf0ibuf.cc:1959
void ibuf_update_free_bits_for_two_pages_low(buf_block_t *block1, buf_block_t *block2, mtr_t *mtr)
Updates the free bits for the two pages to reflect the present state.
Definition: ibuf0ibuf.cc:905
void ibuf_bitmap_page_init(buf_block_t *block, mtr_t *mtr)
Initializes an ibuf bitmap page.
Definition: ibuf0ibuf.cc:541
ibuf_use_t
Combinations of operations that can be buffered.
Definition: ibuf0ibuf.h:62
@ IBUF_USE_ALL
Definition: ibuf0ibuf.h:68
@ IBUF_USE_INSERT_DELETE_MARK
Definition: ibuf0ibuf.h:66
@ IBUF_USE_NONE
Definition: ibuf0ibuf.h:63
@ IBUF_USE_DELETE
Definition: ibuf0ibuf.h:67
@ IBUF_USE_DELETE_MARK
Definition: ibuf0ibuf.h:65
@ IBUF_USE_INSERT
Definition: ibuf0ibuf.h:64
ulint ibuf_merge_space(space_id_t space)
Contracts insert buffer trees by reading pages referring to space_id to the buffer pool.
Definition: ibuf0ibuf.cc:2290
void ibuf_update_free_bits_zip(buf_block_t *block, mtr_t *mtr)
Updates the free bits for a compressed page to reflect the present state.
Definition: ibuf0ibuf.cc:872
constexpr uint32_t CHANGE_BUFFER_DEFAULT_SIZE
Default value for maximum on-disk size of change buffer in terms of percentage of the buffer pool.
Definition: ibuf0ibuf.h:46
ulint ibuf_rec_get_counter(const rec_t *rec)
in: ibuf record
Definition: ibuf0ibuf.cc:1194
bool ibuf_insert(ibuf_op_t op, const dtuple_t *entry, dict_index_t *index, const page_id_t &page_id, const page_size_t &page_size, que_thr_t *thr)
Buffer an operation in the insert/delete buffer, instead of doing it directly to the disk page,...
Definition: ibuf0ibuf.cc:3276
ibuf_t * ibuf
The insert buffer control structure.
Definition: ibuf0ibuf.cc:210
constexpr uint32_t IBUF_TREE_ROOT_PAGE_NO
Definition: ibuf0ibuf.h:345
constexpr uint32_t IBUF_HEADER_PAGE_NO
Definition: ibuf0ibuf.h:344
void ibuf_reset_free_bits(buf_block_t *block)
Resets the free bits of the page in the ibuf bitmap.
Definition: ibuf0ibuf.cc:823
ibuf_op_t
Definition: ibuf0ibuf.h:51
@ IBUF_OP_DELETE_MARK
Definition: ibuf0ibuf.h:53
@ IBUF_OP_COUNT
Definition: ibuf0ibuf.h:57
@ IBUF_OP_DELETE
Definition: ibuf0ibuf.h:54
@ IBUF_OP_INSERT
Definition: ibuf0ibuf.h:52
static bool ibuf_should_try(dict_index_t *index, ulint ignore_sec_unique)
A basic partial test if an insert to the insert buffer could be possible and recommended.
void ibuf_close(void)
Closes insert buffer and frees the data structures.
Definition: ibuf0ibuf.cc:419
Insert buffer.
Insert buffer global types.
Mini-transaction buffer.
std::string HARNESS_EXPORT reset()
get 'reset attributes' ESC sequence.
Definition: vt100.cc:36
const std::string FILE("FILE")
Definition: os0file.h:85
constexpr uint32_t PAGE_DATA
start of data on the page
Definition: page0types.h:104
byte rec_t
Definition: rem0types.h:40
Definition: completion_hash.h:34
The buffer control block structure.
Definition: buf0buf.h:1689
Data structure for an index.
Definition: dict0mem.h:1045
Structure for an SQL data tuple of fields (logical record)
Definition: data0data.h:681
Insert buffer struct.
Definition: ibuf0ibuf.ic:61
Mini-transaction handle and buffer.
Definition: mtr0mtr.h:176
Definition: que0que.h:241
Definition: trx0trx.h:685
Definition: ut0core.h:35
Version control for database, common definitions, and include files.
#define IF_DEBUG(...)
Definition: univ.i:673
unsigned long int ulint
Definition: univ.i:405