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