MySQL  8.0.19
Source Code Documentation
page0cur.h
Go to the documentation of this file.
1 /*****************************************************************************
2 
3 Copyright (c) 1994, 2018, 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/page0cur.h
28  The page cursor
29 
30  Created 10/4/1994 Heikki Tuuri
31  *************************************************************************/
32 
33 #ifndef page0cur_h
34 #define page0cur_h
35 
36 #include "univ.i"
37 
38 #include "buf0types.h"
39 #include "data0data.h"
40 #include "gis0type.h"
41 #include "mtr0mtr.h"
42 #include "page0page.h"
43 #include "rem0rec.h"
44 
45 #define PAGE_CUR_ADAPT
46 
47 #ifdef UNIV_DEBUG
48 /** Gets pointer to the page frame where the cursor is positioned.
49  @return page */
50 UNIV_INLINE
51 page_t *page_cur_get_page(page_cur_t *cur); /*!< in: page cursor */
52 /** Gets pointer to the buffer block where the cursor is positioned.
53  @return page */
54 UNIV_INLINE
55 buf_block_t *page_cur_get_block(page_cur_t *cur); /*!< in: page cursor */
56 /** Gets pointer to the page frame where the cursor is positioned.
57  @return page */
58 UNIV_INLINE
59 page_zip_des_t *page_cur_get_page_zip(page_cur_t *cur); /*!< in: page cursor */
60 /** Gets the record where the cursor is positioned.
61  @return record */
62 UNIV_INLINE
63 rec_t *page_cur_get_rec(page_cur_t *cur); /*!< in: page cursor */
64 #else /* UNIV_DEBUG */
65 #define page_cur_get_page(cur) page_align((cur)->rec)
66 #define page_cur_get_block(cur) (cur)->block
67 #define page_cur_get_page_zip(cur) buf_block_get_page_zip((cur)->block)
68 #define page_cur_get_rec(cur) (cur)->rec
69 #endif /* UNIV_DEBUG */
70 
71 /** Sets the cursor object to point before the first user record on the page.
72 @param[in] block index page
73 @param[in] cur cursor */
74 UNIV_INLINE
75 void page_cur_set_before_first(const buf_block_t *block, page_cur_t *cur);
76 
77 /** Sets the cursor object to point after the last user record on the page.
78 @param[in] block index page
79 @param[in] cur cursor */
80 UNIV_INLINE
81 void page_cur_set_after_last(const buf_block_t *block, page_cur_t *cur);
82 
83 /** Returns TRUE if the cursor is before first user record on page.
84  @return true if at start */
85 UNIV_INLINE
86 ibool page_cur_is_before_first(const page_cur_t *cur); /*!< in: cursor */
87 /** Returns TRUE if the cursor is after last user record.
88  @return true if at end */
89 UNIV_INLINE
90 ibool page_cur_is_after_last(const page_cur_t *cur); /*!< in: cursor */
91 
92 /** Positions the cursor on the given record.
93 @param[in] rec record on a page
94 @param[in] block buffer block containing the record
95 @param[out] cur page cursor */
96 UNIV_INLINE
97 void page_cur_position(const rec_t *rec, const buf_block_t *block,
98  page_cur_t *cur);
99 
100 /** Moves the cursor to the next record on page. */
101 UNIV_INLINE
103  page_cur_t *cur); /*!< in/out: cursor; must not be after last */
104 /** Moves the cursor to the previous record on page. */
105 UNIV_INLINE
107  page_cur_t *cur); /*!< in/out: cursor; not before first */
108 /** Inserts a record next to page cursor. Returns pointer to inserted record if
109  succeed, i.e., enough space available, NULL otherwise. The cursor stays at
110  the same logical position, but the physical position may change if it is
111  pointing to a compressed page that was reorganized.
112 
113  IMPORTANT: The caller will have to update IBUF_BITMAP_FREE
114  if this is a compressed leaf page in a secondary index.
115  This has to be done either within the same mini-transaction,
116  or by invoking ibuf_reset_free_bits() before mtr_commit().
117 
118  @return pointer to record if succeed, NULL otherwise */
119 UNIV_INLINE
121  page_cur_t *cursor, /*!< in/out: a page cursor */
122  const dtuple_t *tuple, /*!< in: pointer to a data tuple */
123  dict_index_t *index, /*!< in: record descriptor */
124  ulint **offsets, /*!< out: offsets on *rec */
125  mem_heap_t **heap, /*!< in/out: pointer to memory heap, or NULL */
126  ulint n_ext, /*!< in: number of externally stored columns */
127  mtr_t *mtr, /*!< in: mini-transaction handle, or NULL */
128  bool use_cache = false)
129  /*!< in: if true, then use record cache to
130  hold the tuple converted record. */
131  MY_ATTRIBUTE((warn_unused_result));
132 
133 /** Inserts a record next to page cursor. Returns pointer to inserted record
134 if succeed, i.e., enough space available, NULL otherwise. The cursor stays at
135 the same logical position, but the physical position may change if it is
136 pointing to a compressed page that was reorganized.
137 
138 IMPORTANT: The caller will have to update IBUF_BITMAP_FREE if this is a
139 compressed leaf page in a secondary index.
140 This has to be done either within the same mini-transaction, or by invoking
141 ibuf_reset_free_bits() before mtr_commit().
142 
143 @param[in,out] cursor a page cursor
144 @param[in] rec record to insert
145 @param[in] index record descriptor
146 @param[in,out] offsets rec_get_offsets(rec, index)
147 @param[in] mtr mini-transaction handle, or NULL
148 @return pointer to record if succeed, NULL otherwise */
149 UNIV_INLINE
150 rec_t *page_cur_rec_insert(page_cur_t *cursor, const rec_t *rec,
151  dict_index_t *index, ulint *offsets, mtr_t *mtr);
152 
153 /** Inserts a record next to page cursor on an uncompressed page.
154  Returns pointer to inserted record if succeed, i.e., enough
155  space available, NULL otherwise. The cursor stays at the same position.
156  @return pointer to record if succeed, NULL otherwise */
158  rec_t *current_rec, /*!< in: pointer to current record after
159  which the new record is inserted */
160  dict_index_t *index, /*!< in: record descriptor */
161  const rec_t *rec, /*!< in: pointer to a physical record */
162  ulint *offsets, /*!< in/out: rec_get_offsets(rec, index) */
163  mtr_t *mtr) /*!< in: mini-transaction handle, or NULL */
164  MY_ATTRIBUTE((warn_unused_result));
165 
166 /** Inserts a record next to page cursor on an uncompressed page.
167 @param[in] current_rec pointer to current record after which
168  the new record is inserted.
169 @param[in] index record descriptor
170 @param[in] tuple pointer to a data tuple
171 @param[in] n_ext number of externally stored columns
172 @param[in] mtr mini-transaction handle, or NULL
173 
174 @return pointer to record if succeed, NULL otherwise */
176  const dtuple_t *tuple, ulint n_ext,
177  mtr_t *mtr);
178 
179 /** Inserts a record next to page cursor on a compressed and uncompressed
180  page. Returns pointer to inserted record if succeed, i.e.,
181  enough space available, NULL otherwise.
182  The cursor stays at the same position.
183 
184  IMPORTANT: The caller will have to update IBUF_BITMAP_FREE
185  if this is a compressed leaf page in a secondary index.
186  This has to be done either within the same mini-transaction,
187  or by invoking ibuf_reset_free_bits() before mtr_commit().
188 
189  @return pointer to record if succeed, NULL otherwise */
191  page_cur_t *cursor, /*!< in/out: page cursor */
192  dict_index_t *index, /*!< in: record descriptor */
193  const rec_t *rec, /*!< in: pointer to a physical record */
194  ulint *offsets, /*!< in/out: rec_get_offsets(rec, index) */
195  mtr_t *mtr) /*!< in: mini-transaction handle, or NULL */
196  MY_ATTRIBUTE((warn_unused_result));
197 /** Copies records from page to a newly created page, from a given record
198  onward, including that record. Infimum and supremum records are not copied.
199 
200  IMPORTANT: The caller will have to update IBUF_BITMAP_FREE
201  if this is a compressed leaf page in a secondary index.
202  This has to be done either within the same mini-transaction,
203  or by invoking ibuf_reset_free_bits() before mtr_commit(). */
205  page_t *new_page, /*!< in/out: index page to copy to */
206  rec_t *rec, /*!< in: first record to copy */
207  dict_index_t *index, /*!< in: record descriptor */
208  mtr_t *mtr); /*!< in: mtr */
209 /** Deletes a record at the page cursor. The cursor is moved to the
210  next record after the deleted one. */
212  page_cur_t *cursor, /*!< in/out: a page cursor */
213  const dict_index_t *index, /*!< in: record descriptor */
214  const ulint *offsets, /*!< in: rec_get_offsets(
215  cursor->rec, index) */
216  mtr_t *mtr); /*!< in: mini-transaction handle */
217 /** Search the right position for a page cursor.
218 @param[in] block buffer block
219 @param[in] index index tree
220 @param[in] tuple data tuple
221 @param[in] mode PAGE_CUR_L, PAGE_CUR_LE, PAGE_CUR_G, or PAGE_CUR_GE
222 @param[out] cursor page cursor
223 @return number of matched fields on the left */
224 UNIV_INLINE
225 ulint page_cur_search(const buf_block_t *block, const dict_index_t *index,
226  const dtuple_t *tuple, page_cur_mode_t mode,
227  page_cur_t *cursor);
228 
229 /** Search the right position for a page cursor.
230 @param[in] block buffer block
231 @param[in] index index tree
232 @param[in] tuple data tuple
233 @param[out] cursor page cursor
234 @return number of matched fields on the left */
235 UNIV_INLINE
236 ulint page_cur_search(const buf_block_t *block, const dict_index_t *index,
237  const dtuple_t *tuple, page_cur_t *cursor);
238 
239 /** Searches the right position for a page cursor. */
241  const buf_block_t *block, /*!< in: buffer block */
242  const dict_index_t *index, /*!< in: record descriptor */
243  const dtuple_t *tuple, /*!< in: data tuple */
244  page_cur_mode_t mode, /*!< in: PAGE_CUR_L,
245  PAGE_CUR_LE, PAGE_CUR_G, or
246  PAGE_CUR_GE */
247  ulint *iup_matched_fields,
248  /*!< in/out: already matched
249  fields in upper limit record */
250  ulint *ilow_matched_fields,
251  /*!< in/out: already matched
252  fields in lower limit record */
253  page_cur_t *cursor, /*!< out: page cursor */
254  rtr_info_t *rtr_info); /*!< in/out: rtree search stack */
255 /** Search the right position for a page cursor.
256 @param[in] block buffer block
257 @param[in] index index tree
258 @param[in] tuple key to be searched for
259 @param[in] mode search mode
260 @param[in,out] iup_matched_fields already matched fields in the
261 upper limit record
262 @param[in,out] iup_matched_bytes already matched bytes in the
263 first partially matched field in the upper limit record
264 @param[in,out] ilow_matched_fields already matched fields in the
265 lower limit record
266 @param[in,out] ilow_matched_bytes already matched bytes in the
267 first partially matched field in the lower limit record
268 @param[out] cursor page cursor */
270  const buf_block_t *block, const dict_index_t *index, const dtuple_t *tuple,
271  page_cur_mode_t mode, ulint *iup_matched_fields, ulint *iup_matched_bytes,
272  ulint *ilow_matched_fields, ulint *ilow_matched_bytes, page_cur_t *cursor);
273 /** Positions a page cursor on a randomly chosen user record on a page. If there
274  are no user records, sets the cursor on the infimum record. */
275 void page_cur_open_on_rnd_user_rec(buf_block_t *block, /*!< in: page */
276  page_cur_t *cursor); /*!< out: page cursor */
277 /** Parses a log record of a record insert on a page.
278  @return end of log record or NULL */
280  ibool is_short, /*!< in: TRUE if short inserts */
281  const byte *ptr, /*!< in: buffer */
282  const byte *end_ptr, /*!< in: buffer end */
283  buf_block_t *block, /*!< in: page or NULL */
284  dict_index_t *index, /*!< in: record descriptor */
285  mtr_t *mtr); /*!< in: mtr or NULL */
286 /** Parses a log record of copying a record list end to a new created page.
287  @return end of log record or NULL */
289  byte *ptr, /*!< in: buffer */
290  byte *end_ptr, /*!< in: buffer end */
291  buf_block_t *block, /*!< in: page or NULL */
292  dict_index_t *index, /*!< in: record descriptor */
293  mtr_t *mtr); /*!< in: mtr or NULL */
294 /** Parses log record of a record delete on a page.
295  @return pointer to record end or NULL */
297  byte *ptr, /*!< in: buffer */
298  byte *end_ptr, /*!< in: buffer end */
299  buf_block_t *block, /*!< in: page or NULL */
300  dict_index_t *index, /*!< in: record descriptor */
301  mtr_t *mtr); /*!< in: mtr or NULL */
302 /** Removes the record from a leaf page. This function does not log
303  any changes. It is used by the IMPORT tablespace functions.
304  @return true if success, i.e., the page did not become too empty */
305 bool page_delete_rec(
306  const dict_index_t *index, /*!< in: The index that the record
307  belongs to */
308  page_cur_t *pcur, /*!< in/out: page cursor on record
309  to delete */
310  page_zip_des_t *page_zip, /*!< in: compressed page descriptor */
311  const ulint *offsets); /*!< in: offsets for record */
312 
313 /** Index page cursor */
314 
315 struct page_cur_t {
316  const dict_index_t *index{nullptr};
317  rec_t *rec{nullptr}; /*!< pointer to a record on page */
318  ulint *offsets{nullptr};
319  buf_block_t *block{nullptr}; /*!< pointer to the block containing rec */
320 };
321 
322 #include "page0cur.ic"
323 
324 #endif
page_cur_search_with_match
void page_cur_search_with_match(const buf_block_t *block, const dict_index_t *index, const dtuple_t *tuple, page_cur_mode_t mode, ulint *iup_matched_fields, ulint *ilow_matched_fields, page_cur_t *cursor, rtr_info_t *rtr_info)
Searches the right position for a page cursor.
Definition: page0cur.cc:363
page_cur_tuple_insert
UNIV_INLINE rec_t * page_cur_tuple_insert(page_cur_t *cursor, const dtuple_t *tuple, dict_index_t *index, ulint **offsets, mem_heap_t **heap, ulint n_ext, mtr_t *mtr, bool use_cache=false)
Inserts a record next to page cursor.
rtr_info
Vectors holding the matching internal pages/nodes and leaf records.
Definition: gis0type.h:108
page_cur_get_page
UNIV_INLINE page_t * page_cur_get_page(page_cur_t *cur)
Gets pointer to the page frame where the cursor is positioned.
dtuple_t
Structure for an SQL data tuple of fields (logical record)
Definition: data0data.h:716
page_t
byte page_t
Type of the index page.
Definition: page0types.h:133
gis0type.h
page_cur_get_rec
UNIV_INLINE rec_t * page_cur_get_rec(page_cur_t *cur)
Gets the record where the cursor is positioned.
page_parse_copy_rec_list_to_created_page
byte * page_parse_copy_rec_list_to_created_page(byte *ptr, byte *end_ptr, buf_block_t *block, dict_index_t *index, mtr_t *mtr)
Parses a log record of copying a record list end to a new created page.
Definition: page0cur.cc:2000
page_cur_mode_t
page_cur_mode_t
Definition: page0types.h:158
page_cur_is_after_last
UNIV_INLINE ibool page_cur_is_after_last(const page_cur_t *cur)
Returns TRUE if the cursor is after last user record.
dict_index_t
Data structure for an index.
Definition: dict0mem.h:869
mtr_t
Mini-transaction handle and buffer.
Definition: mtr0mtr.h:169
page_cur_t
Index page cursor.
Definition: page0cur.h:315
buf_block_t
The buffer control block structure.
Definition: buf0buf.h:1318
page_cur_parse_insert_rec
byte * page_cur_parse_insert_rec(ibool is_short, const byte *ptr, const byte *end_ptr, buf_block_t *block, dict_index_t *index, mtr_t *mtr)
Parses a log record of a record insert on a page.
Definition: page0cur.cc:1033
rec_t
byte rec_t
Definition: rem0types.h:39
mem_block_info_t
The info structure stored at the beginning of a heap block.
Definition: mem0mem.h:337
page_zip_des_t
Compressed page descriptor.
Definition: page0types.h:182
page_cur_direct_insert_rec_low
rec_t * page_cur_direct_insert_rec_low(rec_t *current_rec, dict_index_t *index, const dtuple_t *tuple, ulint n_ext, mtr_t *mtr)
Inserts a record next to page cursor on an uncompressed page.
Definition: page0cur.cc:1397
page_cur_open_on_rnd_user_rec
void page_cur_open_on_rnd_user_rec(buf_block_t *block, page_cur_t *cursor)
Positions a page cursor on a randomly chosen user record on a page.
Definition: page0cur.cc:832
rem0rec.h
page_cur_move_to_prev
UNIV_INLINE void page_cur_move_to_prev(page_cur_t *cur)
Moves the cursor to the previous record on page.
page_cur_rec_insert
UNIV_INLINE rec_t * page_cur_rec_insert(page_cur_t *cursor, const rec_t *rec, dict_index_t *index, ulint *offsets, mtr_t *mtr)
Inserts a record next to page cursor.
page_cur_get_block
UNIV_INLINE buf_block_t * page_cur_get_block(page_cur_t *cur)
Gets pointer to the buffer block where the cursor is positioned.
buf0types.h
page_cur_move_to_next
UNIV_INLINE void page_cur_move_to_next(page_cur_t *cur)
Moves the cursor to the next record on page.
page0page.h
page_cur_insert_rec_zip
rec_t * page_cur_insert_rec_zip(page_cur_t *cursor, dict_index_t *index, const rec_t *rec, ulint *offsets, mtr_t *mtr)
Inserts a record next to page cursor on a compressed and uncompressed page.
Definition: page0cur.cc:1580
page_cur_is_before_first
UNIV_INLINE ibool page_cur_is_before_first(const page_cur_t *cur)
Returns TRUE if the cursor is before first user record on page.
page_delete_rec
bool page_delete_rec(const dict_index_t *index, page_cur_t *pcur, page_zip_des_t *page_zip, const ulint *offsets)
Removes the record from a leaf page.
Definition: page0page.cc:2506
page_cur_position
UNIV_INLINE void page_cur_position(const rec_t *rec, const buf_block_t *block, page_cur_t *cur)
Positions the cursor on the given record.
page_cur_set_before_first
UNIV_INLINE void page_cur_set_before_first(const buf_block_t *block, page_cur_t *cur)
Sets the cursor object to point before the first user record on the page.
page_cur_search_with_match_bytes
void page_cur_search_with_match_bytes(const buf_block_t *block, const dict_index_t *index, const dtuple_t *tuple, page_cur_mode_t mode, ulint *iup_matched_fields, ulint *iup_matched_bytes, ulint *ilow_matched_fields, ulint *ilow_matched_bytes, page_cur_t *cursor)
Search the right position for a page cursor.
Definition: page0cur.cc:614
mtr0mtr.h
data0data.h
page_cur_search
UNIV_INLINE ulint page_cur_search(const buf_block_t *block, const dict_index_t *index, const dtuple_t *tuple, page_cur_mode_t mode, page_cur_t *cursor)
Search the right position for a page cursor.
page_cur_delete_rec
void page_cur_delete_rec(page_cur_t *cursor, const dict_index_t *index, const ulint *offsets, mtr_t *mtr)
Deletes a record at the page cursor.
Definition: page0cur.cc:2297
page_cur_insert_rec_low
rec_t * page_cur_insert_rec_low(rec_t *current_rec, dict_index_t *index, const rec_t *rec, ulint *offsets, mtr_t *mtr)
Inserts a record next to page cursor on an uncompressed page.
Definition: page0cur.cc:1199
page_copy_rec_list_end_to_created_page
void page_copy_rec_list_end_to_created_page(page_t *new_page, rec_t *rec, dict_index_t *index, mtr_t *mtr)
Copies records from page to a newly created page, from a given record onward, including that record.
Definition: page0cur.cc:2056
index
char * index(const char *, int c)
Definition: mysql.cc:2875
page_cur_parse_delete_rec
byte * page_cur_parse_delete_rec(byte *ptr, byte *end_ptr, buf_block_t *block, dict_index_t *index, mtr_t *mtr)
Parses log record of a record delete on a page.
Definition: page0cur.cc:2250
page_cur_get_page_zip
UNIV_INLINE page_zip_des_t * page_cur_get_page_zip(page_cur_t *cur)
Gets pointer to the page frame where the cursor is positioned.
page_cur_set_after_last
UNIV_INLINE void page_cur_set_after_last(const buf_block_t *block, page_cur_t *cur)
Sets the cursor object to point after the last user record on the page.