MySQL 9.0.0
Source Code Documentation
log0chkp.h
Go to the documentation of this file.
1/*****************************************************************************
2
3Copyright (c) 1995, 2024, 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 designed to work with certain software (including
10but not limited to OpenSSL) that is licensed under separate terms,
11as designated in a particular file or component or in included license
12documentation. The authors of MySQL hereby grant you an additional
13permission to link the program and your derivative works with the
14separately licensed software that they have either included with
15the program or referenced in the documentation.
16
17This program is distributed in the hope that it will be useful, but WITHOUT
18ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
19FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
20for more details.
21
22You should have received a copy of the GNU General Public License along with
23this program; if not, write to the Free Software Foundation, Inc.,
2451 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
25
26*****************************************************************************/
27
28/**************************************************/ /**
29 @file include/log0chkp.h
30
31 Redo log functions related to checkpointing and log free check.
32
33 *******************************************************/
34
35#ifndef log0chkp_h
36#define log0chkp_h
37
38#ifndef UNIV_HOTBACKUP
39
40/* log_get_sn */
41#include "log0log.h"
42
43/* log.last_checkpoint_lsn */
44#include "log0sys.h"
45
46/* log_t&, lsn_t */
47#include "log0types.h"
48
49/* srv_threads.*, srv_read_only_mode, ... */
50#include "srv0srv.h"
51
52/* sync_check_iterate */
53#include "sync0debug.h"
54
55/* sync_allowed_latches, latch_level_t */
56#include "sync0types.h"
57
58/**************************************************/ /**
59
60 @name Log - checkpointer thread and checkpointer mutex.
61
62 *******************************************************/
63
64/** @{ */
65
66/** The log checkpointer thread routine.
67@param[in,out] log_ptr pointer to redo log */
68void log_checkpointer(log_t *log_ptr);
69
70/** Checks if log checkpointer thread is active.
71@return true if and only if the log checkpointer thread is active */
74}
75
76#define log_checkpointer_mutex_enter(log) \
77 mutex_enter(&((log).checkpointer_mutex))
78
79#define log_checkpointer_mutex_exit(log) mutex_exit(&((log).checkpointer_mutex))
80
81#define log_checkpointer_mutex_own(log) \
82 (mutex_own(&((log).checkpointer_mutex)) || !log_checkpointer_is_active())
83
84/** @} */
85
86/**************************************************/ /**
87
88 @name Log - basic information about checkpoints.
89
90 *******************************************************/
91
92/** @{ */
93
94/** Gets the last checkpoint lsn stored and flushed to disk.
95@return last checkpoint lsn */
97 return log.last_checkpoint_lsn.load();
98}
99
100/** Calculates age of current checkpoint as number of bytes since
101last checkpoint. This includes bytes for headers and footers of
102all log blocks. The calculation is based on the latest written
103checkpoint lsn, and the current lsn, which points to the first
104non reserved data byte. Note that the current lsn could not fit
105the free space in the log files. This means that the checkpoint
106age could potentially be larger than capacity of the log files.
107However we do the best effort to avoid such situations, and if
108they happen, user threads wait until the space is reclaimed.
109@param[in] log redo log
110@return checkpoint age as number of bytes */
112
113/** Provides opposite checkpoint header number to the given checkpoint
114header number.
115@param[in] checkpoint_header_no the given checkpoint header number
116@return the opposite checkpoint header number */
118 Log_checkpoint_header_no checkpoint_header_no);
119
120/** Computes lsn up to which sync flush should be done or returns 0
121if there is no need to execute sync flush now.
122@param[in,out] log redo log
123@return lsn for which we want to have oldest_lsn >= lsn in each BP,
124 or 0 if there is no need for sync flush */
126
127/** @} */
128
129/**************************************************/ /**
130
131 @name Log - requests to make checkpoint.
132
133 *******************************************************/
134
135/** @{ */
136
137/** Requests a fuzzy checkpoint write (for currently available lsn).
138@param[in, out] log redo log
139@param[in] sync whether request is sync (function should wait) */
140void log_request_checkpoint(log_t &log, bool sync);
141
142/** Requests a checkpoint written in the next log file (not in the one,
143to which current log.last_checkpoint_lsn belongs to).
144@param[in,out] log redo log */
146
147/** Requests a checkpoint at the current lsn.
148@param[in,out] log redo log
149@param[out] requested_lsn lsn for which checkpoint was requested, or
150 stays unmodified if it wasn't requested
151@return true iff requested (false if checkpoint_lsn was already at that lsn) */
152bool log_request_latest_checkpoint(log_t &log, lsn_t &requested_lsn);
153
154/** Make a checkpoint at the current lsn. Reads current lsn and waits
155until all dirty pages have been flushed up to that lsn. Afterwards
156requests a checkpoint write and waits until it is finished.
157@param[in,out] log redo log
158@return true iff current lsn was greater than last checkpoint lsn */
160
161/** Make a checkpoint at the current lsn. Reads current lsn and waits
162until all dirty pages have been flushed up to that lsn. Afterwards
163requests a checkpoint write and waits until it is finished.
164@return true iff current lsn was greater than last checkpoint lsn */
166
167/** Updates the field log.dict_max_allowed_checkpoint_lsn. This is limitation
168for lsn at which checkpoint might be written, imposed by cached changes to the
169DD table buffer. It is called from DD code.
170@param[in,out] log redo log
171@param[in] max_lsn new value for the limitation */
173
174/** @} */
175
176/**************************************************/ /**
177
178 @name Log - concurrency margins.
179
180 *******************************************************/
181
182/** @{ */
183
184/** Computes concurrency margin to be used within log_free_check calls,
185for a given redo log capacity (soft_logical_capacity).
186@param[in] log_capacity redo log capacity (soft)
187@param[out] is_safe true iff the computed margin wasn't truncated
188 because of too small log_capacity
189@return the computed margin */
190sn_t log_concurrency_margin(lsn_t log_capacity, bool &is_safe);
191
192/** Updates log.concurrency_margin and log.concurrency_margin_is_safe for the
193current capacity of the redo log and current innodb_thread_concurrency value.
194@param[in,out] log redo log */
196
197/** @} */
198
199/**************************************************/ /**
200
201 @name Log - free check waiting.
202
203 *******************************************************/
204
205/** @{ */
206
207/** Waits until there is free space in log files which includes
208concurrency margin required for all threads. You should rather
209use log_free_check().
210@param[in] log redo log */
211void log_free_check_wait(log_t &log);
212
213/** Provides current margin used in the log_free_check calls.
214It is a sum of dict_persist_margin and concurrency_margin.
215@param[in] log redo log
216@return margin that would be used in log_free_check() */
218
219/** Computes capacity of redo log available until log_free_check()
220needs to wait. It uses a provided size of the log_free_check_margin.
221@param[in] log redo log
222@param[in] free_check_margin size of the log_free_check_margin;
223 @see log_free_check_margin(log)
224@return lsn capacity up to free_check_wait happens */
225lsn_t log_free_check_capacity(const log_t &log, lsn_t free_check_margin);
226
227/** Computes capacity of redo log available until log_free_check()
228needs to wait. It calls log_free_check_margin(log) to obtain the
229current log_free_check_margin.
230@param[in] log redo log
231@return lsn capacity up to free_check_wait happens */
233
234/** Checks if log_free_check() call should better be executed.
235@param[in] log redo log
236@return true iff log_free_check should be executed */
237inline bool log_free_check_is_required(const log_t &log) {
238 if (srv_read_only_mode) {
239 return false;
240 }
241 const lsn_t lsn = log_get_lsn(log);
242 return lsn > log.free_check_limit_lsn.load();
243}
244
245/** Checks if log_free_check() call should better be executed.
246@return true iff log_free_check should be executed */
248 ut_ad(log_sys != nullptr);
250}
251
252#ifdef UNIV_DEBUG
253/** Performs debug checks to validate some of the assumptions. */
255#endif /* UNIV_DEBUG */
256
257/** Reserves free_check_margin in the redo space for the current thread.
258For further details please look at description of @see log_free_check_margin().
259@param[in] log redo log */
260inline void log_free_check(log_t &log) {
262
263 /** We prefer to wait now for the space in log file, because now
264 are not holding any latches of dirty pages. */
265
267 /* We need to wait, because the concurrency margin could be violated
268 if we let all threads to go forward after making this check now.
269
270 The waiting procedure is rather unlikely to happen for proper my.cnf.
271 Therefore we extracted the code to separate function, to make the
272 inlined log_free_check() small. */
273
275 }
276}
277
278/** Checks for free space in the redo log. Must be called when no latches
279are held (except those listed as exceptions). Any database operation must
280call this before it has produced LOG_CHECKPOINT_FREE_PER_THREAD * UNIV_PAGE_SIZE
281bytes of redo log records. That's because that is the margin in redo log we
282reserve by calling this function.
283
284@remarks
285Checks if lsn corresponding to current log.sn exceeds log.free_check_limit_lsn,
286in which case waits (until it does not exceed). This function is called before
287starting a mini-transaction, because thread must not hold block latches when
288calling this function. It is also important that the caller does NOT hold any
289latch, that might be tried to be acquired:
290 - by the page cleaner (e.g. page/block latches),
291 - or by the log flush process (e.g. file space latches),
292 - or by any other thread, which might at that time already hold another
293 latch, that could further lead to a similar problem in chain of threads.
294For example, suppose a thread holding some latch X, which is neither used by
295the page cleaners nor by the log flush process, called log_free_check() and
296started to wait for the free space. Another thread, holding block's latch
297(which obviously might be needed for the page cleaners) tries to acquire the
298latch X. It needs to wait, because X has already been taken. Therefore, the
299latched block cannot be flushed. If this block had old modifications
300(low oldest_modification), it could effectively prevent any further attempts
301to reclaim space in the redo log. The chain of waiting for each other threads
302could obviously be even longer than the one in example. Therefore it is very
303important not to call log_free_check() if we are holding any latchs which
304might exist in any of such chains. As you can see, it is not that easy to see
305if log_free_check() might be called. It is not only about direct holding
306of block latches, but also such X (or Y acquired by thread holding such X),
307could lead to a deadlock.
308
309For sake of simplicity, you should better not keep any latch when calling to
310the log_free_check() unless you are really sure about what you are doing. */
311inline void log_free_check() {
312 ut_ad(log_sys != nullptr);
314}
315
316/** @} */
317
318/**************************************************/ /**
319
320 @name Log - free check updates.
321
322 *******************************************************/
323
324/** @{ */
325
326/** Updates log.free_check_limit_lsn in the log. The log_limits_mutex
327must be acquired before a call (unless srv_is_being_started is true).
328@param[in,out] log redo log */
330
331/** Updates log.dict_persist_margin and recompute free check limit.
332@param[in,out] log redo log
333@param[in] margin new value for log.dict_persist_margin */
334void log_set_dict_persist_margin(log_t &log, sn_t margin);
335
336/** @} */
337
338/**************************************************/ /**
339
340 @name Log - other functions related to checkpoints.
341
342 *******************************************************/
343
344/** @{ */
345
346/** Writes checkpoint to the file containing the written checkpoint_lsn.
347The checkpoint is written to the given checkpoint header. Unless InnoDB
348is starting: checkpointer, writer and files mutexes must be acquired
349before calling this function.
350@param[in,out] log redo log
351@param[in] checkpoint_file_handle handle to opened file
352@param[in] checkpoint_header_no checkpoint header to be written
353@param[in] next_checkpoint_lsn the checkpoint lsn to write
354@return DB_SUCCESS or error */
356 log_t &log, Log_file_handle &checkpoint_file_handle,
357 Log_checkpoint_header_no checkpoint_header_no, lsn_t next_checkpoint_lsn);
358
359/** Writes the first data block to the log file using the provided handle
360to the opened log file. The block is addressed by the given checkpoint_lsn,
361filled with 0x00 and its data length points to checkpoint_lsn inside, making
362the block logically empty.
363@remarks This is used only during creation of new log files.
364@param[in,out] log redo log
365@param[in] file_handle handle to the opened log file
366@param[in] checkpoint_lsn the checkpoint lsn
367@param[in] file_start_lsn start_lsn of the file
368@return DB_SUCCESS or error */
370 Log_file_handle &file_handle,
371 lsn_t checkpoint_lsn,
372 lsn_t file_start_lsn);
373
374/** Writes the next checkpoint to the log file, by writing a single
375checkpoint header with the checkpoint lsn. Flushes the file after the
376write and updates the log.last_checkpoint_lsn.
377
378@remarks Note that two checkpoint headers are used alternately for
379consecutive checkpoints. If InnoDB crashed during the write, it would
380still have the previous checkpoint info and recovery would work.
381@param[in,out] log redo log
382@param[in] lsn writes checkpoint at this lsn
383@return DB_SUCCESS or error */
385
386/** @} */
387
388#endif /* !UNIV_HOTBACKUP */
389
390#endif /* !log0chkp_h */
Handle which allows to do reads / writes for the opened file.
Definition: log0types.h:309
dberr_t
Definition: db0err.h:39
lsn_t log_get_checkpoint_age(const log_t &log)
Calculates age of current checkpoint as number of bytes since last checkpoint.
Definition: log0chkp.cc:1075
bool log_request_latest_checkpoint(log_t &log, lsn_t &requested_lsn)
Requests a checkpoint at the current lsn.
Definition: log0chkp.cc:666
void log_free_check_validate()
Performs debug checks to validate some of the assumptions.
Definition: log0chkp.cc:1273
bool log_free_check_is_required(const log_t &log)
Checks if log_free_check() call should better be executed.
Definition: log0chkp.h:237
lsn_t log_get_checkpoint_lsn(const log_t &log)
Gets the last checkpoint lsn stored and flushed to disk.
Definition: log0chkp.h:96
void log_update_concurrency_margin(log_t &log)
Updates log.concurrency_margin and log.concurrency_margin_is_safe for the current capacity of the red...
Definition: log0chkp.cc:1179
dberr_t log_files_write_first_data_block_low(log_t &log, Log_file_handle &file_handle, lsn_t checkpoint_lsn, lsn_t file_start_lsn)
Writes the first data block to the log file using the provided handle to the opened log file.
Definition: log0chkp.cc:519
lsn_t log_free_check_capacity(const log_t &log, lsn_t free_check_margin)
Computes capacity of redo log available until log_free_check() needs to wait.
Definition: log0chkp.cc:1228
void log_request_checkpoint_in_next_file(log_t &log)
Requests a checkpoint written in the next log file (not in the one, to which current log....
Definition: log0chkp.cc:660
void log_free_check_wait(log_t &log)
Waits until there is free space in log files which includes concurrency margin required for all threa...
Definition: log0chkp.cc:1240
void log_set_dict_max_allowed_checkpoint_lsn(log_t &log, lsn_t max_lsn)
Updates the field log.dict_max_allowed_checkpoint_lsn.
Definition: log0chkp.cc:323
lsn_t log_free_check_margin(const log_t &log)
Provides current margin used in the log_free_check calls.
Definition: log0chkp.cc:1220
void log_free_check(log_t &log)
Reserves free_check_margin in the redo space for the current thread.
Definition: log0chkp.h:260
bool log_checkpointer_is_active()
Checks if log checkpointer thread is active.
Definition: log0chkp.h:72
sn_t log_concurrency_margin(lsn_t log_capacity, bool &is_safe)
Computes concurrency margin to be used within log_free_check calls, for a given redo log capacity (so...
Definition: log0chkp.cc:1104
void log_update_limits_low(log_t &log)
Updates log.free_check_limit_lsn in the log.
Definition: log0chkp.cc:1193
dberr_t log_files_next_checkpoint(log_t &log, lsn_t lsn)
Writes the next checkpoint to the log file, by writing a single checkpoint header with the checkpoint...
Definition: log0chkp.cc:350
bool log_make_latest_checkpoint(log_t &log)
Make a checkpoint at the current lsn.
Definition: log0chkp.cc:689
void log_checkpointer(log_t *log_ptr)
The log checkpointer thread routine.
Definition: log0chkp.cc:977
void log_set_dict_persist_margin(log_t &log, sn_t margin)
Updates log.dict_persist_margin and recompute free check limit.
Definition: log0chkp.cc:1213
void log_request_checkpoint(log_t &log, bool sync)
Requests a fuzzy checkpoint write (for currently available lsn).
Definition: log0chkp.cc:594
dberr_t log_files_write_checkpoint_low(log_t &log, Log_file_handle &checkpoint_file_handle, Log_checkpoint_header_no checkpoint_header_no, lsn_t next_checkpoint_lsn)
Writes checkpoint to the file containing the written checkpoint_lsn.
Definition: log0chkp.cc:440
Log_checkpoint_header_no log_next_checkpoint_header(Log_checkpoint_header_no checkpoint_header_no)
Provides opposite checkpoint header number to the given checkpoint header number.
Definition: log0chkp.cc:428
lsn_t log_sync_flush_lsn(log_t &log)
Computes lsn up to which sync flush should be done or returns 0 if there is no need to execute sync f...
Definition: log0chkp.cc:761
Redo log - the main header.
lsn_t log_get_lsn(const log_t &log)
Gets the current lsn value.
Definition: log0log.h:168
Redo log - the log_sys.
log_t * log_sys
Redo log system (singleton).
Definition: log0log.cc:431
Redo log basic types.
Log_checkpoint_header_no
Enumerates checkpoint headers in the redo log file.
Definition: log0types.h:95
uint64_t sn_t
Type used for sn values, which enumerate bytes of data stored in the log.
Definition: log0types.h:86
uint64_t lsn_t
Type used for all log sequence number storage and arithmetic.
Definition: log0types.h:63
The server main program.
bool srv_thread_is_active(const IB_thread &thread)
Check if given thread is still active.
Definition: srv0srv.cc:3260
bool srv_read_only_mode
Set if InnoDB must operate in read-only mode.
Definition: srv0srv.cc:200
Srv_threads srv_threads
Structure with state of srv background threads.
Definition: srv0srv.cc:104
IB_thread m_log_checkpointer
Redo checkpointer thread.
Definition: srv0srv.h:176
Redo log - single data structure with state of the redo log system.
Definition: log0sys.h:77
atomic_lsn_t free_check_limit_lsn
Maximum lsn up to which there is free space in the redo log.
Definition: log0sys.h:661
atomic_lsn_t last_checkpoint_lsn
Latest checkpoint lsn.
Definition: log0sys.h:701
Debug checks for latches, header file.
Global types for sync.
#define ut_ad(EXPR)
Debug assertion.
Definition: ut0dbg.h:105
#define ut_d(EXPR)
Debug statement.
Definition: ut0dbg.h:107
static uint64_t lsn
Definition: xcom_base.cc:446