MySQL 8.3.0
Source Code Documentation
table_access_bits.h
Go to the documentation of this file.
1/* Copyright (c) 2020, 2023, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef COMPONENTS_SERVICES_TABLE_ACCESS_BITS_H
24#define COMPONENTS_SERVICES_TABLE_ACCESS_BITS_H
25
26#ifndef MYSQL_ABI_CHECK
27#include <stddef.h> /* size_t */
28#endif
29
32
33/**
34 @file mysql/components/services/bits/table_access_bits.h
35 Generic table access interface.
36
37 @defgroup group_table_access_services Table Access services
38 @ingroup group_components_services_inventory
39 @{
40*/
41
42/**
43 Table lock type.
44*/
46 /** Table is opened for read. */
48 /** Table is opened for write. */
50};
51
52/**
53 Types of columns supported by the table access service.
54*/
61};
62
63/**
64 Expected field definition.
65*/
67 /** Column ordinal position (0-based). */
68 size_t m_index;
69 /** Column name, in UTF8MB4. */
70 const char *m_name;
71 /** Column name length, in bytes. */
73 /** Column type. */
75 /** Nullable. */
77 /** Column length. */
78 size_t m_length;
79};
80
81/**
82 Expected index definition.
83*/
85 /** Column name, in UTF8MB4. */
86 const char *m_name;
87 /** Column name length, in bytes. */
89 /** Index order. */
91};
92
93/**
94 Table_access.
95 A table access session.
96*/
98
99/**
100 An opened table.
101*/
103
104/**
105 An index key.
106*/
108
109/**
110 Create a table access object.
111 @sa destroy_table_access_v1_t
112
113 @param thd The current session. Pass a null ptr if running from a non-MySQLd
114 thread
115 @param count The maximum number of tables to access.
116
117 @note The table access service will create a child session
118 to perform table read and writes.
119 The following properties from the current session are used
120 to initialize the child session:
121 - @c log_bin
122 - @c transaction_isolation
123 - @c skip_readonly_check
124
125 @warning The table access service will set the current THD thread attribute
126 to the temporary child THD it creates. The current THD will be reset back by
127 @ref destroy_table_access_v1_t. This means that the whole table access
128 routine should happen as fast as possible and without thread switching until
129 its completion and disposal of the thread access attribute.
130 The @ref Table_access handle should not be cached and reused.
131*/
133
134/**
135 Destroy a table access object.
136 @sa create_table_access_v1_t
137*/
139
140/**
141 Add a table to a table access session.
142 This method adds a table to a table access session.
143 It returns a ticket, to use with @ref get_table_v1_t.
144
145 @param ta Table access session
146 @param schema_name Schema name raw buffer, in UTF8MB4.
147 @param schema_name_length Length, in bytes, of schema_name
148 @param table_name Table name raw buffer, in UTF8MB4.
149 @param table_name_length Length, in bytes, of table_name
150 @param lock_type_arg Lock type to use (read or write)
151 @return ticket number for the table added
152*/
153typedef size_t (*add_table_v1_t)(Table_access ta, const char *schema_name,
154 size_t schema_name_length,
155 const char *table_name,
156 size_t table_name_length,
157 TA_lock_type lock_type_arg);
158
159#define TA_ERROR_GRL 1
160#define TA_ERROR_READONLY 2
161#define TA_ERROR_OPEN 3
162
163/**
164 Start a table access transaction.
165 Open all tables from the table access session, and lock them.
166
167 Locking all the tables at once is necessary to prevent
168 deadlocks on table metadata between different sessions.
169 The caller should not own the global read lock when opening
170 tables, as this would also create deadlocks.
171
172 @return An error status
173 @retval 0 success
174 @retval TA_ERROR_GRL Global read lock held by the caller
175 @retval TA_ERROR_OPEN Failed to open and lock tables.
176*/
177typedef int (*begin_v1_t)(Table_access ta);
178
179/**
180 Commit changes.
181*/
182typedef int (*commit_v1_t)(Table_access ta);
183
184/**
185 Rollback changes.
186*/
187typedef int (*rollback_v1_t)(Table_access ta);
188
189/**
190 Get an opened table.
191 Once tables are opened and locked,
192 this method returns the opened table that correspond to
193 the ticket returned by add tables.
194
195 @return An opened table.
196*/
197typedef TA_table (*get_table_v1_t)(Table_access ta, size_t ticket);
198
199/**
200 Check the actual table fields against expected fields.
201
202 @retval 0 success
203*/
205 const TA_table_field_def *fields,
206 size_t fields_count);
207
208/**
209 Open a table index.
210
211 An index is identified by name.
212 The caller lists the columns expected in the index.
213 If the index DDL matches the expected columns and count,
214 the index is opened.
215 Otherwise, an error is returned, and the index is not opened.
216
217 @note The list of columns must contain the ACTUAL columns in the index
218 rather than USER defined (used on SQL level). The actual list depends on
219 engine and current implementation. E.g. InnoDB may add columns to the user
220 defined set.
221
222 @param ta Table access
223 @param table Opened table
224 @param index_name Index name, in UTF8MB4, must match the table DDL.
225 @param index_name_length Length of index_name, in bytes.
226 @param fields Expected fields for the index
227 @param fields_count Expected number of fields for the index
228 @param [out] key Opened index.
229
230 @retval 0 Success
231
232 @sa index_end_v1_t
233*/
235 const char *index_name, size_t index_name_length,
236 const TA_index_field_def *fields,
237 size_t fields_count, TA_key *key);
238
239/**
240 Position a table index at a search key.
241
242 The search key is not passed explicitly in this call.
243 The search key is set by populating columns in the table current record,
244 before invoking this method.
245
246 @param ta Table access
247 @param table Opened table
248 @param num_parts Number of key parts populated in the current record.
249 @param key Opened index
250*/
252 size_t num_parts, TA_key key);
253
254/**
255 Position on index at the beginning.
256*/
258
259/**
260 Advance to the next record in the index.
261*/
263
264/**
265 Advance to the next record that matches the current search key.
266*/
268 TA_key key);
269
270/**
271 Close an index.
272*/
274
275/**
276 Start a full table scan.
277*/
279
280/**
281 Advance to the next record in a table scan.
282*/
284
285/**
286 End a full table scan.
287*/
289
290/**
291 Insert a new row in the table.
292*/
294
295/**
296 Update the current row.
297*/
299
300/**
301 Delete the current row.
302*/
304
305/**
306 Set a column to NULL.
307*/
309 size_t index);
310
311/**
312 Is a column NULL.
313*/
315 size_t index);
316
317/**
318 Can a column be NULL.
319*/
321 size_t index);
322
323/**
324 Write an INTEGER column value.
325*/
327 size_t index, long long v);
328
329/**
330 Read an INTEGER column value.
331*/
333 size_t index, long long *v);
334
335/**
336 Write a VARCHAR column value.
337*/
339 size_t index, my_h_string v);
340
341/**
342 Read a VARCHAR column value.
343*/
345 size_t index, my_h_string v);
346
347/**
348 Write any column value.
349 This is a generic interface.
350 The column value must be expressed in UTF8MB4_bin,
351 and is converted to the column type.
352*/
354 size_t index, my_h_string v);
355
356/**
357 Read any column value.
358 This is a generic interface.
359 The column value is converted to a string,
360 expressed in UTF8MB4_bin.
361*/
363 size_t index, my_h_string v);
364
365/** @} (end of group_table_access_services) */
366
367#endif /* COMPONENTS_SERVICES_TABLE_ACCESS_BITS_H */
#define MYSQL_THD
Definition: backup_page_tracker.h:37
int(* index_first_v1_t)(Table_access ta, TA_table table, TA_key key)
Position on index at the beginning.
Definition: table_access_bits.h:257
TA_table(* get_table_v1_t)(Table_access ta, size_t ticket)
Get an opened table.
Definition: table_access_bits.h:197
size_t(* add_table_v1_t)(Table_access ta, const char *schema_name, size_t schema_name_length, const char *table_name, size_t table_name_length, TA_lock_type lock_type_arg)
Add a table to a table access session.
Definition: table_access_bits.h:153
int(* delete_row_v1_t)(Table_access ta, TA_table table)
Delete the current row.
Definition: table_access_bits.h:303
int(* index_next_v1_t)(Table_access ta, TA_table table, TA_key key)
Advance to the next record in the index.
Definition: table_access_bits.h:262
int(* index_next_same_v1_t)(Table_access ta, TA_table table, TA_key key)
Advance to the next record that matches the current search key.
Definition: table_access_bits.h:267
int(* update_row_v1_t)(Table_access ta, TA_table table)
Update the current row.
Definition: table_access_bits.h:298
int(* rollback_v1_t)(Table_access ta)
Rollback changes.
Definition: table_access_bits.h:187
int(* rnd_next_v1_t)(Table_access ta, TA_table table)
Advance to the next record in a table scan.
Definition: table_access_bits.h:283
int(* index_end_v1_t)(Table_access ta, TA_table table, TA_key key)
Close an index.
Definition: table_access_bits.h:273
int(* commit_v1_t)(Table_access ta)
Commit changes.
Definition: table_access_bits.h:182
int(* index_init_v1_t)(Table_access ta, TA_table table, const char *index_name, size_t index_name_length, const TA_index_field_def *fields, size_t fields_count, TA_key *key)
Open a table index.
Definition: table_access_bits.h:234
int(* rnd_end_v1_t)(Table_access ta, TA_table table)
End a full table scan.
Definition: table_access_bits.h:288
int(* get_field_integer_value_v1_t)(Table_access ta, TA_table table, size_t index, long long *v)
Read an INTEGER column value.
Definition: table_access_bits.h:332
int(* write_row_v1_t)(Table_access ta, TA_table table)
Insert a new row in the table.
Definition: table_access_bits.h:293
void(* set_field_null_v1_t)(Table_access ta, TA_table table, size_t index)
Set a column to NULL.
Definition: table_access_bits.h:308
void(* destroy_table_access_v1_t)(Table_access ta)
Destroy a table access object.
Definition: table_access_bits.h:138
int(* rnd_init_v1_t)(Table_access ta, TA_table table)
Start a full table scan.
Definition: table_access_bits.h:278
TA_lock_type
Table lock type.
Definition: table_access_bits.h:45
int(* get_field_varchar_value_v1_t)(Table_access ta, TA_table table, size_t index, my_h_string v)
Read a VARCHAR column value.
Definition: table_access_bits.h:344
struct TA_key_imp * TA_key
An index key.
Definition: table_access_bits.h:107
struct Table_access_imp * Table_access
Table_access.
Definition: table_access_bits.h:97
bool(* is_field_null_v1_t)(Table_access ta, TA_table table, size_t index)
Is a column NULL.
Definition: table_access_bits.h:314
int(* check_table_fields_v1_t)(Table_access ta, TA_table table, const TA_table_field_def *fields, size_t fields_count)
Check the actual table fields against expected fields.
Definition: table_access_bits.h:204
Table_access(* create_table_access_v1_t)(MYSQL_THD thd, size_t count)
Create a table access object.
Definition: table_access_bits.h:132
int(* get_field_any_value_v1_t)(Table_access ta, TA_table table, size_t index, my_h_string v)
Read any column value.
Definition: table_access_bits.h:362
int(* set_field_any_value_v1_t)(Table_access ta, TA_table table, size_t index, my_h_string v)
Write any column value.
Definition: table_access_bits.h:353
bool(* maybe_field_null_v1_t)(Table_access ta, TA_table table, size_t index)
Can a column be NULL.
Definition: table_access_bits.h:320
int(* index_read_map_v1_t)(Table_access ta, TA_table table, size_t num_parts, TA_key key)
Position a table index at a search key.
Definition: table_access_bits.h:251
struct TA_table_imp * TA_table
An opened table.
Definition: table_access_bits.h:102
TA_field_type
Types of columns supported by the table access service.
Definition: table_access_bits.h:55
int(* set_field_varchar_value_v1_t)(Table_access ta, TA_table table, size_t index, my_h_string v)
Write a VARCHAR column value.
Definition: table_access_bits.h:338
int(* set_field_integer_value_v1_t)(Table_access ta, TA_table table, size_t index, long long v)
Write an INTEGER column value.
Definition: table_access_bits.h:326
int(* begin_v1_t)(Table_access ta)
Start a table access transaction.
Definition: table_access_bits.h:177
@ TA_READ
Table is opened for read.
Definition: table_access_bits.h:47
@ TA_WRITE
Table is opened for write.
Definition: table_access_bits.h:49
@ TA_TYPE_UNKNOWN
Definition: table_access_bits.h:56
@ TA_TYPE_INTEGER
Definition: table_access_bits.h:57
@ TA_TYPE_JSON
Definition: table_access_bits.h:59
@ TA_TYPE_VARCHAR
Definition: table_access_bits.h:58
@ TA_TYPE_ENUM
Definition: table_access_bits.h:60
static int count
Definition: myisam_ftdump.cc:44
static PFS_engine_table_share_proxy table
Definition: pfs.cc:60
const char * table_name
Definition: rules_table_service.cc:55
required string key
Definition: replication_asynchronous_connection_failover.proto:59
#define DEFINE_SERVICE_HANDLE(name)
Defines an object type that is meant for carrying handles to the implementation-specific objects used...
Definition: service.h:128
Expected index definition.
Definition: table_access_bits.h:84
const char * m_name
Column name, in UTF8MB4.
Definition: table_access_bits.h:86
bool m_ascending
Index order.
Definition: table_access_bits.h:90
size_t m_name_length
Column name length, in bytes.
Definition: table_access_bits.h:88
Expected field definition.
Definition: table_access_bits.h:66
TA_field_type m_type
Column type.
Definition: table_access_bits.h:74
const char * m_name
Column name, in UTF8MB4.
Definition: table_access_bits.h:70
bool m_nullable
Nullable.
Definition: table_access_bits.h:76
size_t m_length
Column length.
Definition: table_access_bits.h:78
size_t m_index
Column ordinal position (0-based).
Definition: table_access_bits.h:68
size_t m_name_length
Column name length, in bytes.
Definition: table_access_bits.h:72
Definition: mysql_string_service.cc:59