MySQL 8.4.0
Source Code Documentation
buf0rea.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/** @file include/buf0rea.h
29 The database buffer read
30
31 Created 11/5/1995 Heikki Tuuri
32 *******************************************************/
33
34#ifndef buf0rea_h
35#define buf0rea_h
36
37#include "buf0buf.h"
38#include "buf0types.h"
39
40/** Low-level function which reads a page asynchronously from a file to the
41buffer buf_pool if it is not already there, in which case does nothing.
42Sets the io_fix flag and sets an exclusive lock on the buffer frame. The
43flag is cleared and the x-lock released by an i/o-handler thread.
44@param[out] err DB_SUCCESS or DB_TABLESPACE_DELETED
45 if we are trying to read from a non-existent
46 tablespace or a tablespace which is just now
47 being dropped
48@param[in] sync whether synchronous aio is desired
49@param[in] type Request type
50@param[in] mode BUF_READ_IBUF_PAGES_ONLY, ...
51@param[in] page_id page id
52@param[in] page_size page size
53@param[in] unzip true=request uncompressed page
54@return 1 if a read request was queued, 0 if the page already resided in
55buf_pool, or if the page is in the doublewrite buffer blocks in which case it
56is never read into the pool, or if the tablespace does not exist or is being
57dropped */
59 const page_id_t &page_id, const page_size_t &page_size,
60 bool unzip);
61
62/** High-level function which reads a page asynchronously from a file to the
63buffer buf_pool if it is not already there. Sets the io_fix flag and sets
64an exclusive lock on the buffer frame. The flag is cleared and the x-lock
65released by the i/o-handler thread.
66@param[in] page_id page id
67@param[in] page_size page size
68@return true if page has been read in, false in case of failure */
69bool buf_read_page(const page_id_t &page_id, const page_size_t &page_size);
70
71/** High-level function which reads a page asynchronously from a file to the
72buffer buf_pool if it is not already there. Sets the io_fix flag and sets
73an exclusive lock on the buffer frame. The flag is cleared and the x-lock
74released by the i/o-handler thread.
75@param[in] page_id page id
76@param[in] page_size page size
77@param[in] sync true if synchronous aio is desired
78@return true if page has been read in, false in case of failure */
79bool buf_read_page_background(const page_id_t &page_id,
80 const page_size_t &page_size, bool sync);
81
82/** Applies a random read-ahead in buf_pool if there are at least a threshold
83value of accessed pages from the random read-ahead area. Does not read any
84page, not even the one at the position (space, offset), if the read-ahead
85mechanism is not activated. NOTE 1: the calling thread may own latches on
86pages: to avoid deadlocks this function must be written such that it cannot
87end up waiting for these latches! NOTE 2: the calling thread must want
88access to the page given: this rule is set to prevent unintended read-aheads
89performed by ibuf routines, a situation which could result in a deadlock if
90the OS does not support asynchronous i/o.
91@param[in] page_id page id of a page which the current thread
92wants to access
93@param[in] page_size page size
94@param[in] inside_ibuf true if we are inside ibuf routine
95@return number of page read requests issued; NOTE that if we read ibuf
96pages, it may happen that the page at the given page number does not
97get read even if we return a positive value! */
99 const page_size_t &page_size, bool inside_ibuf);
100
101/** Applies linear read-ahead if in the buf_pool the page is a border page of
102a linear read-ahead area and all the pages in the area have been accessed.
103Does not read any page if the read-ahead mechanism is not activated. Note
104that the algorithm looks at the 'natural' adjacent successor and
105predecessor of the page, which on the leaf level of a B-tree are the next
106and previous page in the chain of leaves. To know these, the page specified
107in (space, offset) must already be present in the buf_pool. Thus, the
108natural way to use this function is to call it when a page in the buf_pool
109is accessed the first time, calling this function just after it has been
110bufferfixed.
111NOTE 1: as this function looks at the natural predecessor and successor
112fields on the page, what happens, if these are not initialized to any
113sensible value? No problem, before applying read-ahead we check that the
114area to read is within the span of the space, if not, read-ahead is not
115applied. An uninitialized value may result in a useless read operation, but
116only very improbably.
117NOTE 2: the calling thread may own latches on pages: to avoid deadlocks this
118function must be written such that it cannot end up waiting for these
119latches!
120NOTE 3: the calling thread must want access to the page given: this rule is
121set to prevent unintended read-aheads performed by ibuf routines, a situation
122which could result in a deadlock if the OS does not support asynchronous io.
123@param[in] page_id page id; see NOTE 3 above
124@param[in] page_size page size
125@param[in] inside_ibuf true if we are inside ibuf routine
126@return number of page read requests issued */
128 const page_size_t &page_size, bool inside_ibuf);
129
130/** Issues read requests for pages which the ibuf module wants to read in, in
131order to contract the insert buffer tree. Technically, this function is like
132a read-ahead function.
133@param[in] sync true if the caller wants this function to wait
134 for the highest address page to get read in,
135 before this function returns.
136@param[in] space_ids Array of space ids.
137@param[in] page_nos Array of page numbers to read, with the highest
138 page number the last in the array.
139@param[in] n_stored number of elements in the arrays. */
140void buf_read_ibuf_merge_pages(bool sync, const space_id_t *space_ids,
141 const page_no_t *page_nos, ulint n_stored);
142
143/** Issues asynchronous read requests for pages which recovery wants to read in.
144@param[in] space_id tablespace id
145@param[in] page_nos array of page numbers to read, with the
146highest page number the last in the array
147@param[in] n_stored number of page numbers in the array */
148
149void buf_read_recv_pages(space_id_t space_id, const page_no_t *page_nos,
150 ulint n_stored);
151
152/** @name Modes used in read-ahead
153@{ */
154/** read only pages belonging to the insert buffer tree */
155constexpr uint32_t BUF_READ_IBUF_PAGES_ONLY = 131;
156/** read any page */
157constexpr uint32_t BUF_READ_ANY_PAGE = 132;
158/** @} */
159
160#endif
uint32_t space_id_t
Tablespace identifier.
Definition: api0api.h:47
uint32_t page_no_t
Page number.
Definition: api0api.h:45
The database buffer pool high-level routines.
void buf_read_recv_pages(space_id_t space_id, const page_no_t *page_nos, ulint n_stored)
Issues asynchronous read requests for pages which recovery wants to read in.
Definition: buf0rea.cc:657
bool buf_read_page_background(const page_id_t &page_id, const page_size_t &page_size, bool sync)
High-level function which reads a page asynchronously from a file to the buffer buf_pool if it is not...
Definition: buf0rea.cc:308
ulint buf_read_ahead_linear(const page_id_t &page_id, const page_size_t &page_size, bool inside_ibuf)
Applies linear read-ahead if in the buf_pool the page is a border page of a linear read-ahead area an...
Definition: buf0rea.cc:329
ulint buf_read_page_low(dberr_t *err, bool sync, ulint type, ulint mode, const page_id_t &page_id, const page_size_t &page_size, bool unzip)
Low-level function which reads a page asynchronously from a file to the buffer buf_pool if it is not ...
Definition: buf0rea.cc:66
constexpr uint32_t BUF_READ_IBUF_PAGES_ONLY
read only pages belonging to the insert buffer tree
Definition: buf0rea.h:155
constexpr uint32_t BUF_READ_ANY_PAGE
read any page
Definition: buf0rea.h:157
bool buf_read_page(const page_id_t &page_id, const page_size_t &page_size)
High-level function which reads a page asynchronously from a file to the buffer buf_pool if it is not...
Definition: buf0rea.cc:288
void buf_read_ibuf_merge_pages(bool sync, const space_id_t *space_ids, const page_no_t *page_nos, ulint n_stored)
Issues read requests for pages which the ibuf module wants to read in, in order to contract the inser...
Definition: buf0rea.cc:588
ulint buf_read_ahead_random(const page_id_t &page_id, const page_size_t &page_size, bool inside_ibuf)
Applies a random read-ahead in buf_pool if there are at least a threshold value of accessed pages fro...
Definition: buf0rea.cc:153
The database buffer pool global types for the directory.
Page identifier.
Definition: buf0types.h:207
Page size descriptor.
Definition: page0size.h:50
dberr_t
Definition: db0err.h:39
static Value err()
Create a Value object that represents an error condition.
Definition: json_binary.cc:927
mode
Definition: file_handle.h:61
required string type
Definition: replication_group_member_actions.proto:34
unsigned long int ulint
Definition: univ.i:406