1 /***************************************************************************** 2 3 Copyright (c) 1995, 2019, Oracle and/or its affiliates. All Rights Reserved. 4 5 This program is free software; you can redistribute it and/or modify it under 6 the terms of the GNU General Public License, version 2.0, as published by the 7 Free Software Foundation. 8 9 This program is also distributed with certain software (including but not 10 limited to OpenSSL) that is licensed under separate terms, as designated in a 11 particular file or component or in included license documentation. The authors 12 of MySQL hereby grant you an additional permission to link the program and 13 your derivative works with the separately licensed software that they have 14 included with MySQL. 15 16 This program is distributed in the hope that it will be useful, but WITHOUT 17 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 18 FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0, 19 for more details. 20 21 You should have received a copy of the GNU General Public License along with 22 this program; if not, write to the Free Software Foundation, Inc., 23 51 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 40 buffer buf_pool if it is not already there, in which case does nothing. 41 Sets the io_fix flag and sets an exclusive lock on the buffer frame. The 42 flag 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 54 buf_pool, or if the page is in the doublewrite buffer blocks in which case it 55 is never read into the pool, or if the tablespace does not exist or is being 56 dropped */ 57 ulint buf_read_page_low(dberr_t *err, bool sync, ulint type, ulint mode, 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 62 buffer buf_pool if it is not already there. Sets the io_fix flag and sets 63 an exclusive lock on the buffer frame. The flag is cleared and the x-lock 64 released 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 */ 68 bool 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 71 buffer buf_pool if it is not already there. Sets the io_fix flag and sets 72 an exclusive lock on the buffer frame. The flag is cleared and the x-lock 73 released 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 */ 78 bool 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 82 value of accessed pages from the random read-ahead area. Does not read any 83 page, not even the one at the position (space, offset), if the read-ahead 84 mechanism is not activated. NOTE 1: the calling thread may own latches on 85 pages: to avoid deadlocks this function must be written such that it cannot 86 end up waiting for these latches! NOTE 2: the calling thread must want 87 access to the page given: this rule is set to prevent unintended read-aheads 88 performed by ibuf routines, a situation which could result in a deadlock if 89 the OS does not support asynchronous i/o. 90 @param[in] page_id page id of a page which the current thread 91 wants 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 95 pages, it may happen that the page at the given page number does not 96 get read even if we return a positive value! */ 97 ulint buf_read_ahead_random(const page_id_t &page_id, 98 const page_size_t &page_size, bool inside_ibuf); 99 100 /** Unconditionally reads the next N pages from the the starting page. 101 @param[in] page_id Start reading from this page. 102 @param[in] page_size Tablespace page size 103 @param[in] n_pages Number of pages to read ahead. 104 @return number of page read requests issued */ 105 size_t buf_phy_read_ahead(const page_id_t &page_id, 106 const page_size_t &page_size, size_t n_pages); 107 108 /** Applies linear read-ahead if in the buf_pool the page is a border page of 109 a linear read-ahead area and all the pages in the area have been accessed. 110 Does not read any page if the read-ahead mechanism is not activated. Note 111 that the algorithm looks at the 'natural' adjacent successor and 112 predecessor of the page, which on the leaf level of a B-tree are the next 113 and previous page in the chain of leaves. To know these, the page specified 114 in (space, offset) must already be present in the buf_pool. Thus, the 115 natural way to use this function is to call it when a page in the buf_pool 116 is accessed the first time, calling this function just after it has been 117 bufferfixed. 118 NOTE 1: as this function looks at the natural predecessor and successor 119 fields on the page, what happens, if these are not initialized to any 120 sensible value? No problem, before applying read-ahead we check that the 121 area to read is within the span of the space, if not, read-ahead is not 122 applied. An uninitialized value may result in a useless read operation, but 123 only very improbably. 124 NOTE 2: the calling thread may own latches on pages: to avoid deadlocks this 125 function must be written such that it cannot end up waiting for these 126 latches! 127 NOTE 3: the calling thread must want access to the page given: this rule is 128 set to prevent unintended read-aheads performed by ibuf routines, a situation 129 which could result in a deadlock if the OS does not support asynchronous io. 130 @param[in] page_id page id; see NOTE 3 above 131 @param[in] page_size page size 132 @param[in] inside_ibuf TRUE if we are inside ibuf routine 133 @return number of page read requests issued */ 134 ulint buf_read_ahead_linear(const page_id_t &page_id, 135 const page_size_t &page_size, bool inside_ibuf); 136 137 /** Issues read requests for pages which the ibuf module wants to read in, in 138 order to contract the insert buffer tree. Technically, this function is like 139 a read-ahead function. 140 @param[in] sync true if the caller wants this function to wait 141 for the highest address page to get read in, 142 before this function returns. 143 @param[in] space_ids Array of space ids. 144 @param[in] page_nos Array of page numbers to read, with the highest 145 page number the last in the array. 146 @param[in] n_stored number of elements in the arrays. */ 147 void buf_read_ibuf_merge_pages(bool sync, const space_id_t *space_ids, 148 const page_no_t *page_nos, ulint n_stored); 149 150 /** Issues read requests for pages which recovery wants to read in. 151 @param[in] sync true if the caller wants this function to wait 152 for the highest address page to get read in, before this function returns 153 @param[in] space_id tablespace id 154 @param[in] page_nos array of page numbers to read, with the 155 highest page number the last in the array 156 @param[in] n_stored number of page numbers in the array */ 157 158 void buf_read_recv_pages(bool sync, space_id_t space_id, 159 const page_no_t *page_nos, ulint n_stored); 160 161 /** The size in pages of the area which the read-ahead algorithms read if 162 invoked */ 163 #define BUF_READ_AHEAD_AREA(b) ((b)->read_ahead_area) 164 165 /** @name Modes used in read-ahead @{ */ 166 /** read only pages belonging to the insert buffer tree */ 167 #define BUF_READ_IBUF_PAGES_ONLY 131 168 /** read any page */ 169 #define BUF_READ_ANY_PAGE 132 170 /* @} */ 171 172 #endif 173