MySQL  8.0.18
Source Code Documentation
record_buffer.h
Go to the documentation of this file.
1 #ifndef RECORD_BUFFER_INCLUDED
2 #define RECORD_BUFFER_INCLUDED
3 
4 /*
5  Copyright (c) 2016, 2017, Oracle and/or its affiliates. All rights reserved.
6 
7  This program is free software; you can redistribute it and/or modify
8  it under the terms of the GNU General Public License, version 2.0,
9  as published by the Free Software Foundation.
10 
11  This program is also distributed with certain software (including
12  but not limited to OpenSSL) that is licensed under separate terms,
13  as designated in a particular file or component or in included license
14  documentation. The authors of MySQL hereby grant you an additional
15  permission to link the program and your derivative works with the
16  separately licensed software that they have included with MySQL.
17 
18  This program is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  GNU General Public License, version 2.0, for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
26 */
27 
28 #include "my_base.h" // ha_rows
29 #include "my_dbug.h"
30 
31 /**
32  This class represents a buffer that can be used for multi-row reads. It is
33  allocated by the executor and given to the storage engine through the
34  handler, using handler::ha_set_record_buffer(), so that the storage engine
35  can fill the buffer with multiple rows in a single read call.
36 
37  For now, the record buffer is only used internally by the storage engine as
38  a prefetch cache. The storage engine fills the record buffer when the
39  executor requests the first record, but it returns a single record only to
40  the executor. If the executor wants to access the records in the buffer, it
41  has to call a handler function such as handler::ha_index_next() or
42  handler::ha_rnd_next(). Then the storage engine will copy the next record
43  from the record buffer to the memory area specified in the arguments of the
44  handler function, typically TABLE::record[0].
45 */
47  /// The maximum number of records that can be stored in the buffer.
49  /// The number of bytes available for each record.
50  size_t m_record_size;
51  /// The number of records currently stored in the buffer.
53  /// The @c uchar buffer that holds the records.
55  /// Tells if end-of-range was found while filling the buffer.
56  bool m_out_of_range = false;
57 
58  public:
59  /**
60  Create a new record buffer with the specified size.
61 
62  @param records the number of records that can be stored in the buffer
63  @param record_size the size of each record
64  @param buffer the @c uchar buffer that will hold the records (its
65  size should be at least
66  `Record_buffer::buffer_size(records, record_size)`)
67  */
70 
71  /**
72  This function calculates how big the @c uchar buffer provided to
73  Record_buffer's constructor must be, given a number of records and
74  the record size.
75 
76  @param records the maximum number of records in the buffer
77  @param record_size the size of each record
78  @return the total number of bytes needed for all the records
79  */
80  static constexpr size_t buffer_size(ha_rows records, size_t record_size) {
81  return static_cast<size_t>(records * record_size);
82  }
83 
84  /**
85  Get the number of records that can be stored in the buffer.
86  @return the maximum number of records in the buffer
87  */
88  ha_rows max_records() const { return m_max_records; }
89 
90  /**
91  Get the amount of space allocated for each record in the buffer.
92  @return the record size
93  */
94  size_t record_size() const { return m_record_size; }
95 
96  /**
97  Get the number of records currently stored in the buffer.
98  @return the number of records stored in the buffer
99  */
100  ha_rows records() const { return m_count; }
101 
102  /**
103  Get the buffer that holds the record on position @a pos.
104  @param pos the record number (must be smaller than records())
105  @return the @c uchar buffer that holds the specified record
106  */
109  return m_buffer + m_record_size * pos;
110  }
111 
112  /**
113  Add a new record at the end of the buffer.
114  @return the @c uchar buffer of the added record
115  */
118  return record(m_count++);
119  }
120 
121  /**
122  Remove the record that was last added to the buffer.
123  */
124  void remove_last() {
125  DBUG_ASSERT(m_count > 0);
126  --m_count;
127  }
128 
129  /**
130  Clear the buffer. Remove all the records. The end-of-range flag is
131  preserved.
132  */
133  void clear() { m_count = 0; }
134 
135  /**
136  Reset the buffer. Remove all records and clear the end-of-range flag.
137  */
138  void reset() {
139  m_count = 0;
140  set_out_of_range(false);
141  }
142 
143  /**
144  Set whether the end of the range was reached while filling the buffer.
145  @param val true if end of range was reached, false if still within range
146  */
147  void set_out_of_range(bool val) { m_out_of_range = val; }
148 
149  /**
150  Check if the end of the range was reached while filling the buffer.
151  @retval true if the end range was reached
152  @retval false if the scan is still within the range
153  */
154  bool is_out_of_range() const { return m_out_of_range; }
155 };
156 
157 #endif /* RECORD_BUFFER_INCLUDED */
ha_rows m_count
The number of records currently stored in the buffer.
Definition: record_buffer.h:52
size_t record_size() const
Get the amount of space allocated for each record in the buffer.
Definition: record_buffer.h:94
unsigned char uchar
Definition: my_inttypes.h:51
uchar * add_record()
Add a new record at the end of the buffer.
Definition: record_buffer.h:116
void clear()
Clear the buffer.
Definition: record_buffer.h:133
char buffer[STRING_BUFFER]
Definition: test_sql_9_sessions.cc:57
static constexpr size_t buffer_size(ha_rows records, size_t record_size)
This function calculates how big the uchar buffer provided to Record_buffer&#39;s constructor must be...
Definition: record_buffer.h:80
This class represents a buffer that can be used for multi-row reads.
Definition: record_buffer.h:46
bool is_out_of_range() const
Check if the end of the range was reached while filling the buffer.
Definition: record_buffer.h:154
uchar * record(ha_rows pos) const
Get the buffer that holds the record on position pos.
Definition: record_buffer.h:107
uchar * m_buffer
The uchar buffer that holds the records.
Definition: record_buffer.h:54
This file includes constants used by all storage engines.
Record_buffer(ha_rows records, size_t record_size, uchar *buffer)
Create a new record buffer with the specified size.
Definition: record_buffer.h:68
#define DBUG_ASSERT(A)
Definition: my_dbug.h:197
ha_rows records() const
Get the number of records currently stored in the buffer.
Definition: record_buffer.h:100
char * pos
Definition: do_ctype.cc:76
void reset()
Reset the buffer.
Definition: record_buffer.h:138
void remove_last()
Remove the record that was last added to the buffer.
Definition: record_buffer.h:124
void set_out_of_range(bool val)
Set whether the end of the range was reached while filling the buffer.
Definition: record_buffer.h:147
ha_rows m_max_records
The maximum number of records that can be stored in the buffer.
Definition: record_buffer.h:48
size_t m_record_size
The number of bytes available for each record.
Definition: record_buffer.h:50
ha_rows max_records() const
Get the number of records that can be stored in the buffer.
Definition: record_buffer.h:88
bool m_out_of_range
Tells if end-of-range was found while filling the buffer.
Definition: record_buffer.h:56
my_off_t ha_rows
Definition: my_base.h:1130