1/*****************************************************************************
2
3Copyright (c) 1995, 2015, Oracle and/or its affiliates. All Rights Reserved.
4Copyright (c) 2015, 2017, MariaDB Corporation.
5
6This program is free software; you can redistribute it and/or modify it under
7the terms of the GNU General Public License as published by the Free Software
8Foundation; version 2 of the License.
9
10This program is distributed in the hope that it will be useful, but WITHOUT
11ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
13
14You should have received a copy of the GNU General Public License along with
15this program; if not, write to the Free Software Foundation, Inc.,
1651 Franklin Street, Suite 500, Boston, MA 02110-1335 USA
17
18*****************************************************************************/
19
20/**************************************************//**
21@file include/buf0rea.h
22The database buffer read
23
24Created 11/5/1995 Heikki Tuuri
25*******************************************************/
26
27#ifndef buf0rea_h
28#define buf0rea_h
29
30#include "univ.i"
31#include "buf0buf.h"
32#include "buf0types.h"
33
34/** High-level function which reads a page asynchronously from a file to the
35buffer buf_pool if it is not already there. Sets the io_fix flag and sets
36an exclusive lock on the buffer frame. The flag is cleared and the x-lock
37released by the i/o-handler thread.
38@param[in] page_id page id
39@param[in] page_size page size
40@retval DB_SUCCESS if the page was read and is not corrupted,
41@retval DB_PAGE_CORRUPTED if page based on checksum check is corrupted,
42@retval DB_DECRYPTION_FAILED if page post encryption checksum matches but
43after decryption normal page checksum does not match.
44@retval DB_TABLESPACE_DELETED if tablespace .ibd file is missing */
45dberr_t
46buf_read_page(
47 const page_id_t& page_id,
48 const page_size_t& page_size);
49
50/********************************************************************//**
51High-level function which reads a page asynchronously from a file to the
52buffer buf_pool if it is not already there. Sets the io_fix flag and sets
53an exclusive lock on the buffer frame. The flag is cleared and the x-lock
54released by the i/o-handler thread.
55@param[in] page_id page id
56@param[in] page_size page size
57@param[in] sync true if synchronous aio is desired */
58void
59buf_read_page_background(
60 const page_id_t& page_id,
61 const page_size_t& page_size,
62 bool sync);
63
64/** Applies a random read-ahead in buf_pool if there are at least a threshold
65value of accessed pages from the random read-ahead area. Does not read any
66page, not even the one at the position (space, offset), if the read-ahead
67mechanism is not activated. NOTE 1: the calling thread may own latches on
68pages: to avoid deadlocks this function must be written such that it cannot
69end up waiting for these latches! NOTE 2: the calling thread must want
70access to the page given: this rule is set to prevent unintended read-aheads
71performed by ibuf routines, a situation which could result in a deadlock if
72the OS does not support asynchronous i/o.
73@param[in] page_id page id of a page which the current thread
74wants to access
75@param[in] page_size page size
76@param[in] inside_ibuf TRUE if we are inside ibuf routine
77@return number of page read requests issued; NOTE that if we read ibuf
78pages, it may happen that the page at the given page number does not
79get read even if we return a positive value! */
80ulint
81buf_read_ahead_random(
82 const page_id_t& page_id,
83 const page_size_t& page_size,
84 ibool inside_ibuf);
85
86/** Applies linear read-ahead if in the buf_pool the page is a border page of
87a linear read-ahead area and all the pages in the area have been accessed.
88Does not read any page if the read-ahead mechanism is not activated. Note
89that the algorithm looks at the 'natural' adjacent successor and
90predecessor of the page, which on the leaf level of a B-tree are the next
91and previous page in the chain of leaves. To know these, the page specified
92in (space, offset) must already be present in the buf_pool. Thus, the
93natural way to use this function is to call it when a page in the buf_pool
94is accessed the first time, calling this function just after it has been
95bufferfixed.
96NOTE 1: as this function looks at the natural predecessor and successor
97fields on the page, what happens, if these are not initialized to any
98sensible value? No problem, before applying read-ahead we check that the
99area to read is within the span of the space, if not, read-ahead is not
100applied. An uninitialized value may result in a useless read operation, but
101only very improbably.
102NOTE 2: the calling thread may own latches on pages: to avoid deadlocks this
103function must be written such that it cannot end up waiting for these
104latches!
105NOTE 3: the calling thread must want access to the page given: this rule is
106set to prevent unintended read-aheads performed by ibuf routines, a situation
107which could result in a deadlock if the OS does not support asynchronous io.
108@param[in] page_id page id; see NOTE 3 above
109@param[in] page_size page size
110@param[in] inside_ibuf TRUE if we are inside ibuf routine
111@return number of page read requests issued */
112ulint
113buf_read_ahead_linear(
114 const page_id_t& page_id,
115 const page_size_t& page_size,
116 ibool inside_ibuf);
117
118/********************************************************************//**
119Issues read requests for pages which the ibuf module wants to read in, in
120order to contract the insert buffer tree. Technically, this function is like
121a read-ahead function. */
122void
123buf_read_ibuf_merge_pages(
124/*======================*/
125 bool sync, /*!< in: true if the caller
126 wants this function to wait
127 for the highest address page
128 to get read in, before this
129 function returns */
130 const ulint* space_ids, /*!< in: array of space ids */
131 const ulint* page_nos, /*!< in: array of page numbers
132 to read, with the highest page
133 number the last in the
134 array */
135 ulint n_stored); /*!< in: number of elements
136 in the arrays */
137
138/** Issues read requests for pages which recovery wants to read in.
139@param[in] sync true if the caller wants this function to wait
140for the highest address page to get read in, before this function returns
141@param[in] space_id tablespace id
142@param[in] page_nos array of page numbers to read, with the
143highest page number the last in the array
144@param[in] n_stored number of page numbers in the array */
145
146void
147buf_read_recv_pages(
148 bool sync,
149 ulint space_id,
150 const ulint* page_nos,
151 ulint n_stored);
152
153/** The size in pages of the area which the read-ahead algorithms read if
154invoked */
155#define BUF_READ_AHEAD_AREA(b) ((b)->read_ahead_area)
156
157/** @name Modes used in read-ahead @{ */
158/** read only pages belonging to the insert buffer tree */
159#define BUF_READ_IBUF_PAGES_ONLY 131
160/** read any page */
161#define BUF_READ_ANY_PAGE 132
162/* @} */
163
164#endif
165