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