MySQL 9.0.0
Source Code Documentation
log0log.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/log0log.h
30
31 Redo log - the main header.
32
33 Basic types are defined inside log0types.h.
34
35 Constant values are defined inside log0constants.h, but that
36 file should only be included by log0types.h.
37
38 The log_sys is defined in log0sys.h.
39
40 Functions related to the log buffer are declared in log0buf.h.
41
42 Functions related to the checkpoints are declared in log0chkp.h.
43
44 Functions related to the writer/flusher are declared in log0write.h.
45
46 Functions computing capacity of redo and related margins are declared
47 in log0files_capacity.h.
48
49 Functions doing IO to log files and formatting log blocks are declared
50 in log0files_io.h.
51
52 *******************************************************/
53
54#ifndef log0log_h
55#define log0log_h
56
57#include "log0files_capacity.h"
58#include "log0files_dict.h"
59#include "log0files_finder.h"
60#include "log0files_governor.h"
61#include "log0files_io.h"
62#include "log0sys.h"
63#include "log0types.h"
64
65/**************************************************/ /**
66
67 @name Log - LSN computations.
68
69 *******************************************************/
70
71/** @{ */
72
73/** Calculates lsn value for given sn value. Sequence of sn values
74enumerate all data bytes in the redo log. Sequence of lsn values
75enumerate all data bytes and bytes used for headers and footers
76of all log blocks in the redo log. For every LOG_BLOCK_DATA_SIZE
77bytes of data we have OS_FILE_LOG_BLOCK_SIZE bytes in the redo log.
78NOTE that LOG_BLOCK_DATA_SIZE + LOG_BLOCK_HDR_SIZE + LOG_BLOCK_TRL_SIZE
79== OS_FILE_LOG_BLOCK_SIZE. The calculated lsn value will always point
80to some data byte (will be % OS_FILE_LOG_BLOCK_SIZE >= LOG_BLOCK_HDR_SIZE,
81and < OS_FILE_LOG_BLOCK_SIZE - LOG_BLOCK_TRL_SIZE).
82
83@param[in] sn sn value
84@return lsn value for the provided sn value */
85constexpr inline lsn_t log_translate_sn_to_lsn(sn_t sn) {
88}
89
90/** Calculates sn value for given lsn value.
91@see log_translate_sn_to_lsn
92@param[in] lsn lsn value
93@return sn value for the provided lsn value */
95 /* Calculate sn of the beginning of log block, which contains
96 the provided lsn value. */
98
99 /* Calculate offset for the provided lsn within the log block.
100 The offset includes LOG_BLOCK_HDR_SIZE bytes of block's header. */
101 const uint32_t diff = lsn % OS_FILE_LOG_BLOCK_SIZE;
102
103 if (diff < LOG_BLOCK_HDR_SIZE) {
104 /* The lsn points to some bytes inside the block's header.
105 Return sn for the beginning of the block. Note, that sn
106 values don't enumerate bytes of blocks' headers, so the
107 value of diff does not matter at all. */
108 return sn;
109 }
110
112 /* The lsn points to some bytes inside the block's footer.
113 Return sn for the beginning of the next block. Note, that
114 sn values don't enumerate bytes of blocks' footer, so the
115 value of diff does not matter at all. */
116 return sn + LOG_BLOCK_DATA_SIZE;
117 }
118
119 /* Add the offset but skip bytes of block's header. */
120 return sn + diff - LOG_BLOCK_HDR_SIZE;
121}
122
123/** Validates a given lsn value. Checks if the lsn value points to data
124bytes inside log block (not to some bytes in header/footer). It is used
125by assertions.
126@return true if lsn points to data bytes within log block */
128 const uint32_t offset = lsn % OS_FILE_LOG_BLOCK_SIZE;
129
130 return lsn >= LOG_START_LSN && offset >= LOG_BLOCK_HDR_SIZE &&
132}
133
134/** @} */
135
136#ifndef UNIV_HOTBACKUP
137
138/**************************************************/ /**
139
140 @name Log - general functions.
141
142 *******************************************************/
143
144/** @{ */
145
146/** @return consistent sn value for locked state */
147static inline sn_t log_get_sn(const log_t &log) {
148 const sn_t sn = log.sn.load();
149 if ((sn & SN_LOCKED) != 0) {
150 return log.sn_locked.load();
151 } else {
152 return sn;
153 }
154}
155
156/** Gets the current lsn value. This value points to the first non
157reserved data byte in the redo log. When next user thread reserves
158space in the redo log, it starts at this lsn.
159
160If the last reservation finished exactly before footer of log block,
161this value points to the first byte after header of the next block.
162
163@note It is possible that the current lsn value does not fit free
164space in the log files or in the log buffer. In such case, user
165threads need to wait until the space becomes available.
166
167@return current lsn */
168inline lsn_t log_get_lsn(const log_t &log) {
170}
171
172/** Waits until there is free space for range of sn values ending
173at the provided sn, in both the log buffer and in the log files.
174@param[in] log redo log
175@param[in] end_sn end of the range of sn values */
176void log_wait_for_space(log_t &log, sn_t end_sn);
177
178/** Prints information about important lsn values used in the redo log,
179and some statistics about speed of writing and flushing of data.
180@param[in] log redo log for which print information
181@param[out] file file where to print */
182void log_print(const log_t &log, FILE *file);
183
184/** Refreshes the statistics used to print per-second averages in log_print().
185@param[in,out] log redo log */
186void log_refresh_stats(log_t &log);
187
188void log_update_exported_variables(const log_t &log);
189
190/** @} */
191
192/**************************************************/ /**
193
194 @name Log - initialization of the redo log system.
195
196 *******************************************************/
197
198/** @{ */
199
200/** Initializes log_sys and finds existing redo log files, or creates a new
201set of redo log files.
202
203New redo log files are created in following cases:
204 - there are no existing redo log files in the log directory,
205 - existing set of redo log files is not marked as fully initialized
206 (flag LOG_HEADER_FLAG_NOT_INITIALIZED exists in the newest file).
207
208After this call, the log_sys global variable is allocated and initialized.
209InnoDB might start recovery then.
210
211@remarks
212The redo log files are not resized in this function, because before resizing
213log files, InnoDB must run recovery and ensure log files are logically empty.
214The redo resize is currently the only scenario in which the initialized log_sys
215might become closed by log_sys_close() and then re-initialized by another call
216to log_sys_init().
217
218@note Note that the redo log system is NOT ready for user writes after this
219call is finished. The proper order of calls looks like this:
220 - log_sys_init(),
221 - log_start(),
222 - log_start_background_threads()
223and this sequence is executed inside srv_start() in srv0start.cc (interleaved
224with remaining logic of the srv_start())
225
226@note Note this function also verifies that REDO logs are in known format.
227
228@param[in] expect_no_files true means we should return DB_ERROR if log
229 files are present in the directory before
230 proceeding any further
231@param[in] flushed_lsn lsn at which new redo log files might be
232 started if they had to be created during
233 this call; this should be lsn stored in
234 the system tablespace header at offset
235 FIL_PAGE_FILE_FLUSH_LSN if the data
236 directory has been initialized;
237@param[out] new_files_lsn updated to the lsn of the first checkpoint
238 created in the new log files if new log files
239 are created; else: 0
240@return DB_SUCCESS or error */
241dberr_t log_sys_init(bool expect_no_files, lsn_t flushed_lsn,
242 lsn_t &new_files_lsn);
243
244/** Starts the initialized redo log system using a provided
245checkpoint_lsn and current lsn. Block for current_lsn must
246be properly initialized in the log buffer prior to calling
247this function. Therefore a proper value of first_rec_group
248must be set for that block before log_start is called.
249@param[in,out] log redo log
250@param[in] checkpoint_lsn checkpoint lsn
251@param[in] start_lsn current lsn to start at
252@param[in] allow_checkpoints true iff allows writing newer checkpoints
253@return DB_SUCCESS or error */
254dberr_t log_start(log_t &log, lsn_t checkpoint_lsn, lsn_t start_lsn,
255 bool allow_checkpoints = true);
256
257/** Close the log system and free all the related memory. */
258void log_sys_close();
259
260/** Resizes the write ahead buffer in the redo log.
261@param[in,out] log redo log
262@param[in] new_size new size (in bytes) */
263void log_write_ahead_resize(log_t &log, size_t new_size);
264
265/** @} */
266
267/**************************************************/ /**
268
269 @name Log - the log threads and mutexes
270
271 *******************************************************/
272
273/** @{ */
274
275/** Validates that all the log background threads are active.
276Used only to assert, that the state is correct.
277@param[in] log redo log */
279
280/** Validates that all the log background threads are inactive.
281Used only to assert, that the state is correct. */
283
284/** Starts all the log background threads. This can be called only,
285when the threads are inactive. This should never be called concurrently.
286This may not be called during read-only mode.
287@param[in,out] log redo log */
289
290/** Stops all the log background threads. This can be called only,
291when the threads are active. This should never be called concurrently.
292This may not be called in read-only mode. Note that is is impossible
293to start log background threads in such case.
294@param[in,out] log redo log */
296
297/** Marks the flag which tells log threads to stop and wakes them.
298Does not wait until they are stopped.
299@param[in,out] log redo log */
301
302/** Function similar to @see log_stop_background_threads() except that it
303stops all the log threads in such a way, that the redo log will be logically
304empty after the threads are stopped.
305@note It is caller responsibility to ensure that all threads other than the
306log_files_governor cannot produce new redo log records when this function
307is being called. */
309
310/** Wakes up all log threads which are alive.
311@param[in,out] log redo log */
312void log_wake_threads(log_t &log);
313
314#define log_limits_mutex_enter(log) mutex_enter(&((log).limits_mutex))
315
316#define log_limits_mutex_exit(log) mutex_exit(&((log).limits_mutex))
317
318#define log_limits_mutex_own(log) mutex_own(&(log).limits_mutex)
319
320/** @} */
321
322/**************************************************/ /**
323
324 @name Log - the log position locking.
325
326 *******************************************************/
327
328/** @{ */
329
330/** Lock redo log. Both current lsn and checkpoint lsn will not change
331until the redo log is unlocked.
332@param[in,out] log redo log to lock */
333void log_position_lock(log_t &log);
334
335/** Unlock the locked redo log.
336@param[in,out] log redo log to unlock */
337void log_position_unlock(log_t &log);
338
339/** Collect coordinates in the locked redo log.
340@param[in] log locked redo log
341@param[out] current_lsn stores current lsn there
342@param[out] checkpoint_lsn stores checkpoint lsn there */
343void log_position_collect_lsn_info(const log_t &log, lsn_t *current_lsn,
344 lsn_t *checkpoint_lsn);
345
346/** @} */
347
348/**************************************************/ /**
349
350 @name Log - persisting the flags.
351
352 *******************************************************/
353
354/** @{ */
355
356/** Disable redo logging and persist the information.
357@param[in,out] log redo log */
358void log_persist_disable(log_t &log);
359
360/** Enable redo logging and persist the information.
361@param[in,out] log redo log */
362void log_persist_enable(log_t &log);
363
364/** Persist the information that it is safe to restart server.
365@param[in,out] log redo log */
367
368/** Marks the redo log files as belonging to the initialized data directory
369with initialized set of redo log files. Flushes the log_flags without the
370flag LOG_HEADER_FLAG_NOT_INITIALIZED to the newest redo log file.
371@param[in,out] log redo log */
373
374/** Asserts that the log is not marked as crash-unsafe.
375@param[in,out] log redo log */
377
378/** @} */
379
380#endif /* !UNIV_HOTBACKUP */
381
382#endif /* !log0log_h */
dberr_t
Definition: db0err.h:39
static Bigint * diff(Bigint *a, Bigint *b, Stack_alloc *alloc)
Definition: dtoa.cc:1076
constexpr sn_t SN_LOCKED
The sn bit to express locked state.
Definition: log0constants.h:162
constexpr lsn_t LOG_START_LSN
The counting of lsn's starts from this value: this must be non-zero.
Definition: log0constants.h:153
constexpr uint32_t LOG_BLOCK_HDR_SIZE
Size of the log block's header in bytes.
Definition: log0constants.h:297
constexpr uint32_t LOG_BLOCK_DATA_SIZE
Size of log block's data fragment (where actual data is stored).
Definition: log0constants.h:312
constexpr uint32_t LOG_BLOCK_TRL_SIZE
Size of the log block footer (trailer) in bytes.
Definition: log0constants.h:306
Redo log management of capacity.
In-memory dictionary of log files (keeps their meta data).
Redo log management of log files.
The log0files_io.
void log_update_exported_variables(const log_t &log)
Definition: log0log.cc:1197
void log_position_collect_lsn_info(const log_t &log, lsn_t *current_lsn, lsn_t *checkpoint_lsn)
Collect coordinates in the locked redo log.
Definition: log0log.cc:1445
sn_t log_translate_lsn_to_sn(lsn_t lsn)
Calculates sn value for given lsn value.
Definition: log0log.h:94
dberr_t log_start(log_t &log, lsn_t checkpoint_lsn, lsn_t start_lsn, bool allow_checkpoints=true)
Starts the initialized redo log system using a provided checkpoint_lsn and current lsn.
Definition: log0log.cc:698
void log_persist_crash_safe(log_t &log)
Persist the information that it is safe to restart server.
Definition: log0log.cc:1507
void log_background_threads_inactive_validate()
Validates that all the log background threads are inactive.
Definition: log0log.cc:889
void log_persist_enable(log_t &log)
Enable redo logging and persist the information.
Definition: log0log.cc:1493
void log_crash_safe_validate(log_t &log)
Asserts that the log is not marked as crash-unsafe.
Definition: log0log.cc:1522
void log_make_empty_and_stop_background_threads(log_t &log)
Function similar to.
Definition: log0log.cc:1007
void log_wait_for_space(log_t &log, sn_t end_sn)
Waits until there is free space for range of sn values ending at the provided sn, in both the log buf...
bool log_is_data_lsn(lsn_t lsn)
Validates a given lsn value.
Definition: log0log.h:127
void log_write_ahead_resize(log_t &log, size_t new_size)
Resizes the write ahead buffer in the redo log.
Definition: log0log.cc:1288
void log_background_threads_active_validate(const log_t &log)
Validates that all the log background threads are active.
Definition: log0log.cc:880
void log_position_lock(log_t &log)
Lock redo log.
Definition: log0log.cc:1433
void log_stop_background_threads(log_t &log)
Stops all the log background threads.
Definition: log0log.cc:945
void log_position_unlock(log_t &log)
Unlock the locked redo log.
Definition: log0log.cc:1439
void log_print(const log_t &log, FILE *file)
Prints information about important lsn values used in the redo log, and some statistics about speed o...
Definition: log0log.cc:1122
lsn_t log_get_lsn(const log_t &log)
Gets the current lsn value.
Definition: log0log.h:168
void log_persist_disable(log_t &log)
Disable redo logging and persist the information.
Definition: log0log.cc:1500
static sn_t log_get_sn(const log_t &log)
Definition: log0log.h:147
void log_wake_threads(log_t &log)
Wakes up all log threads which are alive.
Definition: log0log.cc:1023
void log_sys_close()
Close the log system and free all the related memory.
Definition: log0log.cc:1892
void log_persist_initialized(log_t &log)
Marks the redo log files as belonging to the initialized data directory with initialized set of redo ...
Definition: log0log.cc:1514
void log_start_background_threads(log_t &log)
Starts all the log background threads.
Definition: log0log.cc:898
dberr_t log_sys_init(bool expect_no_files, lsn_t flushed_lsn, lsn_t &new_files_lsn)
Initializes log_sys and finds existing redo log files, or creates a new set of redo log files.
Definition: log0log.cc:1640
constexpr lsn_t log_translate_sn_to_lsn(sn_t sn)
Calculates lsn value for given sn value.
Definition: log0log.h:85
void log_stop_background_threads_nowait(log_t &log)
Marks the flag which tells log threads to stop and wakes them.
Definition: log0log.cc:1000
void log_refresh_stats(log_t &log)
Refreshes the statistics used to print per-second averages in log_print().
Definition: log0log.cc:1192
Redo log - the log_sys.
Redo log basic types.
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
const std::string FILE("FILE")
Definition: os0file.h:89
constexpr uint32_t OS_FILE_LOG_BLOCK_SIZE
The next value should be smaller or equal to the smallest sector size used on any disk.
Definition: os0file.h:196
Redo log - single data structure with state of the redo log system.
Definition: log0sys.h:77
atomic_sn_t sn
Current sn value.
Definition: log0sys.h:103
atomic_sn_t sn_locked
Intended sn value while x-locked.
Definition: log0sys.h:106
static uint64_t lsn
Definition: xcom_base.cc:446