MySQL  8.0.16
Source Code Documentation
handler.h
Go to the documentation of this file.
1 #ifndef HANDLER_INCLUDED
2 #define HANDLER_INCLUDED
3 
4 /*
5  Copyright (c) 2000, 2019, 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 /* Definitions for parameters to do with handler-routines */
29 
30 #include <fcntl.h>
31 #include <float.h>
32 #include <string.h>
33 #include <sys/types.h>
34 #include <time.h>
35 #include <algorithm>
36 #include <bitset>
37 #include <functional>
38 #include <map>
39 #include <random> // std::mt19937
40 #include <set>
41 #include <string>
42 
44 #include "ft_global.h" // ft_hints
45 #include "lex_string.h"
46 #include "m_ctype.h"
47 #include "map_helpers.h"
48 #include "my_alloc.h"
49 #include "my_base.h"
50 #include "my_bitmap.h"
51 #include "my_compiler.h"
52 #include "my_dbug.h"
53 #include "my_double2ulonglong.h"
54 #include "my_inttypes.h"
55 #include "my_io.h"
56 #include "my_sys.h"
57 #include "my_thread_local.h" // my_errno
59 #include "sql/dd/object_id.h" // dd::Object_id
60 #include "sql/dd/string_type.h"
61 #include "sql/dd/types/object_table.h" // dd::Object_table
62 #include "sql/discrete_interval.h" // Discrete_interval
63 #include "sql/key.h"
64 #include "sql/sql_const.h" // SHOW_COMP_OPTION
65 #include "sql/sql_list.h" // SQL_I_List
66 #include "sql/sql_plugin_ref.h" // plugin_ref
67 #include "thr_lock.h" // thr_lock_type
68 #include "typelib.h"
69 
70 class Alter_info;
72 class Create_field;
73 class Field;
74 class Item;
75 class JOIN;
76 class Json_dom;
77 class Partition_handler;
78 class Plugin_table;
79 class Plugin_tablespace;
80 class Record_buffer;
81 class SE_cost_constants; // see opt_costconstants.h
82 class String;
83 class THD;
84 class handler;
85 class partition_info;
86 struct System_status_var;
87 
88 namespace dd {
89 class Properties;
90 } // namespace dd
91 struct FOREIGN_KEY_INFO;
92 struct KEY_CACHE;
93 struct LEX;
94 struct MY_BITMAP;
95 struct SAVEPOINT;
96 struct TABLE;
97 struct TABLE_LIST;
98 struct TABLE_SHARE;
99 struct Tablespace_options;
100 struct handlerton;
101 
102 typedef struct xid_t XID;
104 struct MDL_key;
105 
106 namespace dd {
107 enum class enum_column_types;
108 class Table;
109 class Tablespace;
110 struct sdi_key;
111 struct sdi_vector;
112 
113 typedef sdi_key sdi_key_t;
115 } // namespace dd
116 
117 typedef bool (*qc_engine_callback)(THD *thd, const char *table_key,
118  uint key_length, ulonglong *engine_data);
119 
120 typedef bool(stat_print_fn)(THD *thd, const char *type, size_t type_len,
121  const char *file, size_t file_len,
122  const char *status, size_t status_len);
123 
124 class ha_statistics;
126 
127 namespace AQP {
128 class Join_plan;
129 }
130 
132 
133 /// Maps from slot to plugin. May return NULL if plugin has been unloaded.
135 /// Returns the size of the array holding pointers to plugins.
136 size_t num_hton2plugins();
137 
138 /**
139  For unit testing.
140  Insert plugin into arbitrary slot in array.
141  Remove plugin from arbitrary slot in array.
142 */
145 
146 extern const char *ha_row_type[];
147 extern const char *tx_isolation_names[];
148 extern const char *binlog_format_names[];
150 extern ulong total_ha_2pc;
151 
152 // the following is for checking tables
153 
154 #define HA_ADMIN_ALREADY_DONE 1
155 #define HA_ADMIN_OK 0
156 #define HA_ADMIN_NOT_IMPLEMENTED -1
157 #define HA_ADMIN_FAILED -2
158 #define HA_ADMIN_CORRUPT -3
159 #define HA_ADMIN_INTERNAL_ERROR -4
160 #define HA_ADMIN_INVALID -5
161 #define HA_ADMIN_REJECT -6
162 #define HA_ADMIN_TRY_ALTER -7
163 #define HA_ADMIN_WRONG_CHECKSUM -8
164 #define HA_ADMIN_NOT_BASE_TABLE -9
165 #define HA_ADMIN_NEEDS_UPGRADE -10
166 #define HA_ADMIN_NEEDS_ALTER -11
167 #define HA_ADMIN_NEEDS_CHECK -12
168 #define HA_ADMIN_STATS_UPD_ERR -13
169 /** User needs to dump and re-create table to fix pre 5.0 decimal types */
170 #define HA_ADMIN_NEEDS_DUMP_UPGRADE -14
171 
172 /**
173  Return values for check_if_supported_inplace_alter().
174 
175  @see check_if_supported_inplace_alter() for description of
176  the individual values.
177 */
187 };
188 
189 /* Bits in table_flags() to show what database can do */
190 
191 #define HA_NO_TRANSACTIONS (1 << 0) /* Doesn't support transactions */
192 #define HA_PARTIAL_COLUMN_READ (1 << 1) /* read may not return all columns */
193 /*
194  Used to avoid scanning full tables on an index. If this flag is set then
195  the handler always has a primary key (hidden if not defined) and this
196  index is used for scanning rather than a full table scan in all
197  situations. No separate data/index file.
198 */
199 #define HA_TABLE_SCAN_ON_INDEX (1 << 2)
200 
201 /// Not in use.
202 #define HA_UNUSED3 (1 << 3)
203 
204 /*
205  Can the storage engine handle spatial data.
206  Used to check that no spatial attributes are declared unless
207  the storage engine is capable of handling it.
208 */
209 #define HA_CAN_GEOMETRY (1 << 4)
210 /*
211  Reading keys in random order is as fast as reading keys in sort order
212  (Used in records.cc to decide if we should use a record cache and by
213  filesort to decide if we should sort key + data or key + pointer-to-row.
214  For further explanation see intro to init_read_record.
215 */
216 #define HA_FAST_KEY_READ (1 << 5)
217 /*
218  Set the following flag if we on delete should force all key to be read
219  and on update read all keys that changes
220 */
221 #define HA_REQUIRES_KEY_COLUMNS_FOR_DELETE (1 << 6)
222 /*
223  Is NULL values allowed in indexes.
224  If this is not allowed then it is not possible to use an index on a
225  NULLable field.
226 */
227 #define HA_NULL_IN_KEY (1 << 7)
228 /*
229  Tells that we can the position for the conflicting duplicate key
230  record is stored in table->file->dupp_ref. (insert uses rnd_pos() on
231  this to find the duplicated row)
232 */
233 #define HA_DUPLICATE_POS (1 << 8)
234 #define HA_NO_BLOBS (1 << 9) /* Doesn't support blobs */
235 /*
236  Is the storage engine capable of defining an index of a prefix on
237  a BLOB attribute.
238 */
239 #define HA_CAN_INDEX_BLOBS (1 << 10)
240 /*
241  Auto increment fields can be part of a multi-part key. For second part
242  auto-increment keys, the auto_incrementing is done in handler.cc
243 */
244 #define HA_AUTO_PART_KEY (1 << 11)
245 /*
246  Can't define a table without primary key (and cannot handle a table
247  with hidden primary key)
248 */
249 #define HA_REQUIRE_PRIMARY_KEY (1 << 12)
250 /*
251  Does the counter of records after the info call specify an exact
252  value or not. If it does this flag is set.
253 */
254 #define HA_STATS_RECORDS_IS_EXACT (1 << 13)
255 /// Not in use.
256 #define HA_UNUSED14 (1 << 14)
257 /*
258  This parameter is set when the handler will also return the primary key
259  when doing read-only-key on another index, i.e., if we get the primary
260  key columns for free when we do an index read (usually, it also implies
261  that HA_PRIMARY_KEY_REQUIRED_FOR_POSITION flag is set).
262 */
263 #define HA_PRIMARY_KEY_IN_READ_INDEX (1 << 15)
264 /*
265  If HA_PRIMARY_KEY_REQUIRED_FOR_POSITION is set, it means that to position()
266  uses a primary key given by the record argument.
267  Without primary key, we can't call position().
268  If not set, the position is returned as the current rows position
269  regardless of what argument is given.
270 */
271 #define HA_PRIMARY_KEY_REQUIRED_FOR_POSITION (1 << 16)
272 #define HA_CAN_RTREEKEYS (1 << 17)
273 /*
274  Seems to be an old MyISAM feature that is no longer used. No handler
275  has it defined but it is checked in init_read_record. Further investigation
276  needed.
277 */
278 #define HA_NOT_DELETE_WITH_CACHE (1 << 18)
279 /*
280  The following is we need to a primary key to delete (and update) a row.
281  If there is no primary key, all columns needs to be read on update and delete
282 */
283 #define HA_PRIMARY_KEY_REQUIRED_FOR_DELETE (1 << 19)
284 /*
285  Indexes on prefixes of character fields are not allowed.
286 */
287 #define HA_NO_PREFIX_CHAR_KEYS (1 << 20)
288 /*
289  Does the storage engine support fulltext indexes.
290 */
291 #define HA_CAN_FULLTEXT (1 << 21)
292 /*
293  Can the HANDLER interface in the MySQL API be used towards this
294  storage engine.
295 */
296 #define HA_CAN_SQL_HANDLER (1 << 22)
297 /*
298  Set if the storage engine does not support auto increment fields.
299 */
300 #define HA_NO_AUTO_INCREMENT (1 << 23)
301 /*
302  Supports CHECKSUM option in CREATE TABLE (MyISAM feature).
303 */
304 #define HA_HAS_CHECKSUM (1 << 24)
305 /*
306  Table data are stored in separate files (for lower_case_table_names).
307  Should file names always be in lower case (used by engines that map
308  table names to file names.
309 */
310 #define HA_FILE_BASED (1 << 26)
311 #define HA_NO_VARCHAR (1 << 27)
312 /*
313  Is the storage engine capable of handling bit fields.
314 */
315 #define HA_CAN_BIT_FIELD (1 << 28)
316 #define HA_ANY_INDEX_MAY_BE_UNIQUE (1 << 30)
317 #define HA_NO_COPY_ON_ALTER (1LL << 31)
318 #define HA_COUNT_ROWS_INSTANT (1LL << 32) /* records() gives exact count*/
319 /* Has it's own method of binlog logging */
320 #define HA_HAS_OWN_BINLOGGING (1LL << 33)
321 /*
322  Engine is capable of row-format and statement-format logging,
323  respectively
324 */
325 #define HA_BINLOG_ROW_CAPABLE (1LL << 34)
326 #define HA_BINLOG_STMT_CAPABLE (1LL << 35)
327 /*
328  When a multiple key conflict happens in a REPLACE command mysql
329  expects the conflicts to be reported in the ascending order of
330  key names.
331 
332  For e.g.
333 
334  CREATE TABLE t1 (a INT, UNIQUE (a), b INT NOT NULL, UNIQUE (b), c INT NOT
335  NULL, INDEX(c));
336 
337  REPLACE INTO t1 VALUES (1,1,1),(2,2,2),(2,1,3);
338 
339  MySQL expects the conflict with 'a' to be reported before the conflict with
340  'b'.
341 
342  If the underlying storage engine does not report the conflicting keys in
343  ascending order, it causes unexpected errors when the REPLACE command is
344  executed.
345 
346  This flag helps the underlying SE to inform the server that the keys are not
347  ordered.
348 */
349 #define HA_DUPLICATE_KEY_NOT_IN_ORDER (1LL << 36)
350 /*
351  Engine supports REPAIR TABLE. Used by CHECK TABLE FOR UPGRADE if an
352  incompatible table is detected. If this flag is set, CHECK TABLE FOR UPGRADE
353  will report ER_TABLE_NEEDS_UPGRADE, otherwise ER_TABLE_NEED_REBUILD.
354 */
355 #define HA_CAN_REPAIR (1LL << 37)
356 
357 /*
358  Set of all binlog flags. Currently only contain the capabilities
359  flags.
360  */
361 #define HA_BINLOG_FLAGS (HA_BINLOG_ROW_CAPABLE | HA_BINLOG_STMT_CAPABLE)
362 
363 /**
364  The handler supports read before write removal optimization
365 
366  Read before write removal may be used for storage engines which support
367  write without previous read of the row to be updated. Handler returning
368  this flag must implement start_read_removal() and end_read_removal().
369  The handler may return "fake" rows constructed from the key of the row
370  asked for. This is used to optimize UPDATE and DELETE by reducing the
371  number of round-trips between handler and storage engine.
372 
373  Example:
374  UPDATE a=1 WHERE pk IN (@<keys@>)
375 
376  @verbatim
377  mysql_update()
378  {
379  if (<conditions for starting read removal>)
380  start_read_removal()
381  -> handler returns true if read removal supported for this table/query
382 
383  while(read_record("pk=<key>"))
384  -> handler returns fake row with column "pk" set to <key>
385 
386  ha_update_row()
387  -> handler sends write "a=1" for row with "pk=<key>"
388 
389  end_read_removal()
390  -> handler returns the number of rows actually written
391  }
392  @endverbatim
393 
394  @note This optimization in combination with batching may be used to
395  remove even more round-trips.
396 */
397 #define HA_READ_BEFORE_WRITE_REMOVAL (1LL << 38)
398 
399 /*
400  Engine supports extended fulltext API
401  */
402 #define HA_CAN_FULLTEXT_EXT (1LL << 39)
403 
404 /*
405  Storage engine doesn't synchronize result set with expected table contents.
406  Used by replication slave to check if it is possible to retrieve rows from
407  the table when deciding whether to do a full table scan, index scan or hash
408  scan while applying a row event.
409  */
410 #define HA_READ_OUT_OF_SYNC (1LL << 40)
411 
412 /*
413  Storage engine supports table export using the
414  FLUSH TABLE <table_list> FOR EXPORT statement.
415  */
416 #define HA_CAN_EXPORT (1LL << 41)
417 
418 /*
419  The handler don't want accesses to this table to
420  be const-table optimized
421 */
422 #define HA_BLOCK_CONST_TABLE (1LL << 42)
423 
424 /*
425  Handler supports FULLTEXT hints
426 */
427 #define HA_CAN_FULLTEXT_HINTS (1LL << 43)
428 
429 /**
430  Storage engine doesn't support LOCK TABLE ... READ LOCAL locks
431  but doesn't want to use handler::store_lock() API for upgrading
432  them to LOCK TABLE ... READ locks, for example, because it doesn't
433  use THR_LOCK locks at all.
434 */
435 #define HA_NO_READ_LOCAL_LOCK (1LL << 44)
436 
437 /**
438  A storage engine is compatible with the attachable transaction requirements
439  means that
440 
441  - either SE detects the fact that THD::ha_data was reset and starts a new
442  attachable transaction, closes attachable transaction on close_connection
443  and resumes regular (outer) transaction when THD::ha_data is restored;
444 
445  - or SE completely ignores THD::ha_data and close_connection like MyISAM
446  does.
447 */
448 #define HA_ATTACHABLE_TRX_COMPATIBLE (1LL << 45)
449 
450 /**
451  Handler supports Generated Columns
452 */
453 #define HA_GENERATED_COLUMNS (1LL << 46)
454 
455 /**
456  Supports index on virtual generated column
457 */
458 #define HA_CAN_INDEX_VIRTUAL_GENERATED_COLUMN (1LL << 47)
459 
460 /**
461  Supports descending indexes
462 */
463 #define HA_DESCENDING_INDEX (1LL << 48)
464 
465 /**
466  Supports partial update of BLOB columns.
467 */
468 #define HA_BLOB_PARTIAL_UPDATE (1LL << 49)
469 
470 /**
471  If this isn't defined, only columns/indexes with Cartesian coordinate systems
472  (projected SRS or SRID 0) is supported. Columns/indexes without SRID
473  restriction is also supported if this isn't defined.
474 */
475 #define HA_SUPPORTS_GEOGRAPHIC_GEOMETRY_COLUMN (1LL << 50)
476 
477 /**
478  Handler supports expressions as DEFAULT for a column.
479 */
480 #define HA_SUPPORTS_DEFAULT_EXPRESSION (1LL << 51)
481 
482 /**
483  Handlers with this flag set do not support UPDATE operations.
484 */
485 #define HA_UPDATE_NOT_SUPPORTED (1LL << 52)
486 
487 /**
488  Handlers with this flag set do not support DELETE operations.
489 */
490 #define HA_DELETE_NOT_SUPPORTED (1LL << 53)
491 
492 /**
493  The storage engine does not support using indexes for access. Indexes can only
494  be used for estimating cost.
495 */
496 #define HA_NO_INDEX_ACCESS (1LL << 54)
497 
498 /*
499  Bits in index_flags(index_number) for what you can do with index.
500  If you do not implement indexes, just return zero here.
501 */
502 /*
503  Does the index support read next, this is assumed in the server
504  code and never checked so all indexes must support this.
505  Note that the handler can be used even if it doesn't have any index.
506 */
507 #define HA_READ_NEXT 1 /* TODO really use this flag */
508 /*
509  Can the index be used to scan backwards (supports ::index_prev).
510 */
511 #define HA_READ_PREV 2
512 /*
513  Can the index deliver its record in index order. Typically true for
514  all ordered indexes and not true for hash indexes. Used to set keymap
515  part_of_sortkey.
516  This keymap is only used to find indexes usable for resolving an ORDER BY
517  in the query. Thus in most cases index_read will work just fine without
518  order in result production. When this flag is set it is however safe to
519  order all output started by index_read since most engines do this. With
520  read_multi_range calls there is a specific flag setting order or not
521  order so in those cases ordering of index output can be avoided.
522 */
523 #define HA_READ_ORDER 4
524 /*
525  Specify whether index can handle ranges, typically true for all
526  ordered indexes and not true for hash indexes.
527  Used by optimiser to check if ranges (as key >= 5) can be optimised
528  by index.
529 */
530 #define HA_READ_RANGE 8
531 /*
532  Can't use part key searches. This is typically true for hash indexes
533  and typically not true for ordered indexes.
534 */
535 #define HA_ONLY_WHOLE_INDEX 16
536 /*
537  Does the storage engine support index-only scans on this index.
538  Enables use of HA_EXTRA_KEYREAD and HA_EXTRA_NO_KEYREAD
539  Used to set Key_map keys_for_keyread and to check in optimiser for
540  index-only scans. When doing a read under HA_EXTRA_KEYREAD the handler
541  only have to fill in the columns the key covers. If
542  HA_PRIMARY_KEY_IN_READ_INDEX is set then also the PRIMARY KEY columns
543  must be updated in the row.
544 */
545 #define HA_KEYREAD_ONLY 64
546 /*
547  Index scan will not return records in rowid order. Not guaranteed to be
548  set for unordered (e.g. HASH) indexes.
549 */
550 #define HA_KEY_SCAN_NOT_ROR 128
551 #define HA_DO_INDEX_COND_PUSHDOWN 256 /* Supports Index Condition Pushdown */
552 
553 /* operations for disable/enable indexes */
554 #define HA_KEY_SWITCH_NONUNIQ 0
555 #define HA_KEY_SWITCH_ALL 1
556 #define HA_KEY_SWITCH_NONUNIQ_SAVE 2
557 #define HA_KEY_SWITCH_ALL_SAVE 3
558 
559 /*
560  Use this instead of 0 as the initial value for the slot number of
561  handlerton, so that we can distinguish uninitialized slot number
562  from slot 0.
563 */
564 #define HA_SLOT_UNDEF ((uint)-1)
565 
566 /*
567  Parameters for open() (in register form->filestat)
568  HA_GET_INFO does an implicit HA_ABORT_IF_LOCKED
569 */
570 
571 #define HA_OPEN_KEYFILE 1
572 #define HA_OPEN_RNDFILE 2
573 #define HA_GET_INDEX 4
574 #define HA_GET_INFO 8 /* do a handler::info() after open */
575 #define HA_READ_ONLY 16 /* File opened as readonly */
576 /* Try readonly if can't open with read and write */
577 #define HA_TRY_READ_ONLY 32
578 #define HA_WAIT_IF_LOCKED 64 /* Wait if locked on open */
579 #define HA_ABORT_IF_LOCKED 128 /* skip if locked on open.*/
580 #define HA_BLOCK_LOCK 256 /* unlock when reading some records */
581 #define HA_OPEN_TEMPORARY 512
582 
583 /* Some key definitions */
584 #define HA_KEY_NULL_LENGTH 1
585 #define HA_KEY_BLOB_LENGTH 2
586 
587 #define HA_LEX_CREATE_TMP_TABLE 1
588 #define HA_LEX_CREATE_IF_NOT_EXISTS 2
589 #define HA_LEX_CREATE_TABLE_LIKE 4
590 #define HA_LEX_CREATE_INTERNAL_TMP_TABLE 8
591 #define HA_MAX_REC_LENGTH 65535U
592 
593 /**
594  Options for the START TRANSACTION statement.
595 
596  Note that READ ONLY and READ WRITE are logically mutually exclusive.
597  This is enforced by the parser and depended upon by trans_begin().
598 
599  We need two flags instead of one in order to differentiate between
600  situation when no READ WRITE/ONLY clause were given and thus transaction
601  is implicitly READ WRITE and the case when READ WRITE clause was used
602  explicitly.
603 */
604 
605 // WITH CONSISTENT SNAPSHOT option
607 // READ ONLY option
609 // READ WRITE option
611 // HIGH PRIORITY option
613 
635  DB_TYPE_PARTITION_DB, // No longer used.
643  /** Performance schema engine. */
647  DB_TYPE_DEFAULT = 127 // Must be last
648 };
649 
650 enum row_type : int {
658  /** Unused. Reserved for future versions. */
660 };
661 
668 };
669 
679 };
680 
682 
683 /* Bits in used_fields */
684 #define HA_CREATE_USED_AUTO (1L << 0)
685 #define HA_CREATE_USED_RAID (1L << 1) // RAID is no longer availble
686 #define HA_CREATE_USED_UNION (1L << 2)
687 #define HA_CREATE_USED_INSERT_METHOD (1L << 3)
688 #define HA_CREATE_USED_MIN_ROWS (1L << 4)
689 #define HA_CREATE_USED_MAX_ROWS (1L << 5)
690 #define HA_CREATE_USED_AVG_ROW_LENGTH (1L << 6)
691 #define HA_CREATE_USED_PACK_KEYS (1L << 7)
692 #define HA_CREATE_USED_CHARSET (1L << 8)
693 #define HA_CREATE_USED_DEFAULT_CHARSET (1L << 9)
694 #define HA_CREATE_USED_DATADIR (1L << 10)
695 #define HA_CREATE_USED_INDEXDIR (1L << 11)
696 #define HA_CREATE_USED_ENGINE (1L << 12)
697 #define HA_CREATE_USED_CHECKSUM (1L << 13)
698 #define HA_CREATE_USED_DELAY_KEY_WRITE (1L << 14)
699 #define HA_CREATE_USED_ROW_FORMAT (1L << 15)
700 #define HA_CREATE_USED_COMMENT (1L << 16)
701 #define HA_CREATE_USED_PASSWORD (1L << 17)
702 #define HA_CREATE_USED_CONNECTION (1L << 18)
703 #define HA_CREATE_USED_KEY_BLOCK_SIZE (1L << 19)
704 /** Unused. Reserved for future versions. */
705 #define HA_CREATE_USED_TRANSACTIONAL (1L << 20)
706 /** Unused. Reserved for future versions. */
707 #define HA_CREATE_USED_PAGE_CHECKSUM (1L << 21)
708 /** This is set whenever STATS_PERSISTENT=0|1|default has been
709 specified in CREATE/ALTER TABLE. See also HA_OPTION_STATS_PERSISTENT in
710 include/my_base.h. It is possible to distinguish whether
711 STATS_PERSISTENT=default has been specified or no STATS_PERSISTENT= is
712 given at all. */
713 #define HA_CREATE_USED_STATS_PERSISTENT (1L << 22)
714 /**
715  This is set whenever STATS_AUTO_RECALC=0|1|default has been
716  specified in CREATE/ALTER TABLE. See enum_stats_auto_recalc.
717  It is possible to distinguish whether STATS_AUTO_RECALC=default
718  has been specified or no STATS_AUTO_RECALC= is given at all.
719 */
720 #define HA_CREATE_USED_STATS_AUTO_RECALC (1L << 23)
721 /**
722  This is set whenever STATS_SAMPLE_PAGES=N|default has been
723  specified in CREATE/ALTER TABLE. It is possible to distinguish whether
724  STATS_SAMPLE_PAGES=default has been specified or no STATS_SAMPLE_PAGES= is
725  given at all.
726 */
727 #define HA_CREATE_USED_STATS_SAMPLE_PAGES (1L << 24)
728 
729 /**
730  This is set whenever a 'TABLESPACE=...' phrase is used on CREATE TABLE
731 */
732 #define HA_CREATE_USED_TABLESPACE (1L << 25)
733 
734 /** COMPRESSION="zlib|lz4|none" used during table create. */
735 #define HA_CREATE_USED_COMPRESS (1L << 26)
736 
737 /** ENCRYPTION="Y" used during table create. */
738 #define HA_CREATE_USED_ENCRYPT (1L << 27)
739 
740 /**
741  CREATE|ALTER SCHEMA|DATABASE|TABLE has an explicit COLLATE clause.
742 
743  Implies HA_CREATE_USED_DEFAULT_CHARSET.
744 */
745 #define HA_CREATE_USED_DEFAULT_COLLATE (1L << 28)
746 
747 /** SECONDARY_ENGINE used during table create. */
748 #define HA_CREATE_USED_SECONDARY_ENGINE (1L << 29)
749 
750 /**
751  CREATE|ALTER SCHEMA|DATABASE has an explicit ENCRYPTION clause.
752 
753  Implies HA_CREATE_USED_DEFAULT_ENCRYPTION.
754 */
755 #define HA_CREATE_USED_DEFAULT_ENCRYPTION (1L << 30)
756 /*
757  End of bits used in used_fields
758 */
759 
760 /*
761  Structure to hold list of database_name.table_name.
762  This is used at both mysqld and storage engine layer.
763 */
765  const char *db;
766  const char *tablename;
767 };
768 
769 #define MAXGTRIDSIZE 64
770 #define MAXBQUALSIZE 64
771 
772 #define COMPATIBLE_DATA_YES 0
773 #define COMPATIBLE_DATA_NO 1
774 
775 /*
776  These structures are used to pass information from a set of SQL commands
777  on add/drop/change tablespace definitions to the proper hton.
778 */
779 #define UNDEF_NODEGROUP 65535
780 
781 // FUTURE: Combine these two enums into one enum class
795 };
796 
805 };
806 
807 /**
808  Legacy struct for passing tablespace information to SEs.
809 
810  FUTURE: Pass all info through dd objects
811  */
813  public:
814  const char *tablespace_name = nullptr;
815  const char *logfile_group_name = nullptr;
819  const char *data_file_name = nullptr;
820  const char *undo_file_name = nullptr;
821  ulonglong extent_size = 1024 * 1024; // Default 1 MByte
822  ulonglong undo_buffer_size = 8 * 1024 * 1024; // Default 8 MByte
823  ulonglong redo_buffer_size = 8 * 1024 * 1024; // Default 8 MByte
824  ulonglong initial_size = 128 * 1024 * 1024; // Default 128 MByte
825  ulonglong autoextend_size = 0; // No autoextension as default
826  ulonglong max_size = 0; // Max size == initial size => no extension
827  ulonglong file_block_size = 0; // 0=default or must be a valid Page Size
829  bool wait_until_completed = true;
830  const char *ts_comment = nullptr;
831 
833  return ts_cmd_type == CREATE_TABLESPACE ||
837  }
838 
839  /**
840  Proper constructor even for all-public class simplifies initialization and
841  allows members to be const.
842 
843  FUTURE: With constructor all members can be made const, and do not need
844  default initializers.
845 
846  @param tablespace name of tabelspace (nullptr for logfile group statements)
847  @param logfile_group name of logfile group or nullptr
848  @param cmd main statement type
849  @param alter_tablespace_cmd subcommand type for ALTER TABLESPACE
850  @param datafile tablespace file for CREATE and ALTER ... ADD ...
851  @param undofile only applies to logfile group statements. nullptr otherwise.
852  @param opts options provided by parser
853  */
854  st_alter_tablespace(const char *tablespace, const char *logfile_group,
856  enum ts_alter_tablespace_type alter_tablespace_cmd,
857  const char *datafile, const char *undofile,
858  const Tablespace_options &opts);
859 };
860 
861 /*
862  Make sure that the order of schema_tables and enum_schema_tables are the same.
863 */
864 enum enum_schema_tables : int {
880 };
881 
884 
885 /** Clone start operation mode */
887  /** Start a new clone operation */
889 
890  /** Re-start a clone operation after failure */
892 
893  /** Add a new task to a running clone operation */
895 
896  /** Get version for transfer data format */
898 
899  /** Max value for clone mode */
901 };
902 
903 /** Clone operation types. */
904 enum Ha_clone_type : size_t {
905  /** Caller must block all write operation to the SE. */
907 
908  /** For transactional SE, archive redo to support concurrent dml */
910 
911  /** For transactional SE, track page changes to support concurrent dml */
913 
914  /** For transactional SE, use both page tracking and redo to optimize
915  clone with concurrent dml. Currently supported by Innodb. */
917 
918  /** SE supports multiple threads for clone */
920 
921  /** SE supports restarting clone after network failure */
923 
924  /** Maximum value of clone type */
926 };
927 
928 using Ha_clone_flagset = std::bitset<HA_CLONE_TYPE_MAX>;
929 
930 /** File reference for clone */
932  /** File reference type */
933  enum {
934  /** File handle */
936 
937  /** File descriptor */
939 
940  } type;
941 
942  /** File reference */
943  union {
944  /** File descriptor */
946 
947  /** File handle for windows */
948  void *file_handle;
949  };
950 };
951 
952 /* Abstract callback interface to stream data back to the caller. */
954  protected:
955  /** Constructor to initialize members. */
957  : m_hton(),
958  m_loc_idx(),
960  m_data_desc(),
961  m_desc_len(),
962  m_src_name(),
963  m_dest_name(),
964  m_flag() {}
965 
966  public:
967  /** Callback providing data from current position of a
968  file descriptor of specific length.
969  @param[in] from_file source file to read from
970  @param[in] len data length
971  @return error code */
972  virtual int file_cbk(Ha_clone_file from_file, uint len) = 0;
973 
974  /** Callback providing data in buffer of specific length.
975  @param[in] from_buffer source buffer to read from
976  @param[in] len data length
977  @return error code */
978  virtual int buffer_cbk(uchar *from_buffer, uint len) = 0;
979 
980  /** Callback providing a file descriptor to write data starting
981  from current position.
982  @param[in] to_file destination file to write data
983  @return error code */
984  virtual int apply_file_cbk(Ha_clone_file to_file) = 0;
985 
986  /** virtual destructor. */
987  virtual ~Ha_clone_cbk() {}
988 
989  /** Set current storage engine handlerton.
990  @param[in] hton SE handlerton */
991  void set_hton(handlerton *hton) { m_hton = hton; }
992 
993  /** Get current storage engine handlerton.
994  @return SE handlerton */
995  handlerton *get_hton() { return (m_hton); }
996 
997  /** Set caller's transfer buffer size. SE can adjust the data chunk size
998  based on this parameter.
999  @param[in] size buffer size in bytes */
1001 
1002  /** Get caller's transfer buffer size.
1003  @return buffer size in bytes */
1005 
1006  /** Set current SE index.
1007  @param[in] idx SE index in locator array */
1008  void set_loc_index(uint idx) { m_loc_idx = idx; }
1009 
1010  /** Get current SE index.
1011  @return SE index in locator array */
1012  uint get_loc_index() { return (m_loc_idx); }
1013 
1014  /** Set data descriptor. SE specific descriptor for the
1015  data transferred by the callbacks.
1016  @param[in] desc serialized data descriptor
1017  @param[in] len length of the descriptor byte stream */
1018  void set_data_desc(const uchar *desc, uint len) {
1019  m_data_desc = desc;
1020  m_desc_len = len;
1021  }
1022 
1023  /** Get data descriptor. SE specific descriptor for the
1024  data transferred by the callbacks.
1025  @param[out] lenp length of the descriptor byte stream
1026  @return pointer to the serialized data descriptor */
1027  const uchar *get_data_desc(uint *lenp) {
1028  if (lenp != nullptr) {
1029  *lenp = m_desc_len;
1030  }
1031 
1032  return (m_data_desc);
1033  }
1034 
1035  /** Get SE source file name. Used for debug printing and error message.
1036  @return null terminated string for source file name */
1037  const char *get_source_name() { return (m_src_name); }
1038 
1039  /** Set SE source file name.
1040  @param[in] name null terminated string for source file name */
1041  void set_source_name(const char *name) { m_src_name = name; }
1042 
1043  /** Get SE destination file name. Used for debug printing and error message.
1044  @return null terminated string for destination file name */
1045  const char *get_dest_name() { return (m_dest_name); }
1046 
1047  /** Set SE destination file name.
1048  @param[in] name null terminated string for destination file name */
1049  void set_dest_name(const char *name) { m_dest_name = name; }
1050 
1051  /** Clear all flags set by SE */
1052  void clear_flags() { m_flag = 0; }
1053 
1054  /** Mark that ACK is needed for the data transfer before returning
1055  from callback. Set by SE. */
1056  void set_ack() { m_flag |= HA_CLONE_ACK; }
1057 
1058  /** Check if ACK is needed for the data transfer
1059  @return true if ACK is needed */
1060  bool is_ack_needed() { return (m_flag & HA_CLONE_ACK); }
1061 
1062  /** Mark that the file descriptor is opened for read/write
1063  with OS buffer cache. For O_DIRECT, the flag is not set. */
1065 
1066  /** Check if the file descriptor is opened for read/write with OS
1067  buffer cache. Currently clone avoids using zero copy (sendfile on linux),
1068  if SE is using O_DIRECT. This improves data copy performance.
1069  @return true if O_DIRECT is not used */
1071 
1072  /** Mark that the file can be transferred with zero copy. */
1074 
1075  /** Check if zero copy optimization is suggested. */
1076  bool is_zero_copy() { return (m_flag & HA_CLONE_ZERO_COPY); }
1077 
1078  private:
1079  /** Handlerton for the SE */
1081 
1082  /** SE index in caller's locator array */
1084 
1085  /** Caller's transfer buffer size. */
1087 
1088  /** SE's Serialized data descriptor */
1091 
1092  /** Current source file name */
1093  const char *m_src_name;
1094 
1095  /** Current destination file name */
1096  const char *m_dest_name;
1097 
1098  /** Flag storing data related options */
1099  int m_flag;
1100 
1101  /** Acknowledgement is needed for the data transfer. */
1102  const int HA_CLONE_ACK = 0x01;
1103 
1104  /** Data file is opened for read/write with OS buffer cache. */
1105  const int HA_CLONE_FILE_CACHE = 0x02;
1106 
1107  /** Data file can be transferred with zero copy. */
1108  const int HA_CLONE_ZERO_COPY = 0x04;
1109 };
1110 
1111 /**
1112  Column type description for foreign key columns compatibility check.
1113 
1114  Contains subset of information from dd::Column class. It is inconvenient
1115  to use dd::Column class directly for such checks because it requires valid
1116  dd::Table object and in some cases we want to produce Ha_fk_column_type
1117  right from column description in Create_field format.
1118 */
1121  /*
1122  Note that both dd::Column::char_length() and length here are really
1123  in bytes.
1124  */
1125  size_t char_length;
1130 };
1131 
1132 /* handlerton methods */
1133 
1134 /**
1135  close_connection is only called if
1136  thd->ha_data[xxx_hton.slot] is non-zero, so even if you don't need
1137  this storage area - set it to something, so that MySQL would know
1138  this storage engine was accessed in this connection
1139 */
1140 typedef int (*close_connection_t)(handlerton *hton, THD *thd);
1141 
1142 /** Terminate connection/statement notification. */
1143 typedef void (*kill_connection_t)(handlerton *hton, THD *thd);
1144 
1145 /**
1146  Shut down all storage engine background tasks that might access
1147  the data dictionary, before the main shutdown.
1148 */
1149 typedef void (*pre_dd_shutdown_t)(handlerton *hton);
1150 
1151 /**
1152  sv points to a storage area, that was earlier passed
1153  to the savepoint_set call
1154 */
1155 typedef int (*savepoint_rollback_t)(handlerton *hton, THD *thd, void *sv);
1156 
1157 /**
1158  sv points to an uninitialized storage area of requested size
1159  (see savepoint_offset description)
1160 */
1161 typedef int (*savepoint_set_t)(handlerton *hton, THD *thd, void *sv);
1162 
1163 /**
1164  Check if storage engine allows to release metadata locks which were
1165  acquired after the savepoint if rollback to savepoint is done.
1166  @return true - If it is safe to release MDL locks.
1167  false - If it is not.
1168 */
1170  THD *thd);
1171 
1172 typedef int (*savepoint_release_t)(handlerton *hton, THD *thd, void *sv);
1173 
1174 /**
1175  'all' is true if it's a real commit, that makes persistent changes
1176  'all' is false if it's not in fact a commit but an end of the
1177  statement that is part of the transaction.
1178  NOTE 'all' is also false in auto-commit mode where 'end of statement'
1179  and 'real commit' mean the same event.
1180 */
1181 typedef int (*commit_t)(handlerton *hton, THD *thd, bool all);
1182 
1183 typedef int (*rollback_t)(handlerton *hton, THD *thd, bool all);
1184 
1185 typedef int (*prepare_t)(handlerton *hton, THD *thd, bool all);
1186 
1187 typedef int (*recover_t)(handlerton *hton, XA_recover_txn *xid_list, uint len,
1188  MEM_ROOT *mem_root);
1189 
1190 /** X/Open XA distributed transaction status codes */
1192  /**
1193  normal execution
1194  */
1195  XA_OK = 0,
1196 
1197  /**
1198  asynchronous operation already outstanding
1199  */
1201 
1202  /**
1203  a resource manager error occurred in the transaction branch
1204  */
1206 
1207  /**
1208  the XID is not valid
1209  */
1211 
1212  /**
1213  invalid arguments were given
1214  */
1216 
1217  /**
1218  routine invoked in an improper context
1219  */
1221 
1222  /**
1223  resource manager unavailable
1224  */
1226 
1227  /**
1228  the XID already exists
1229  */
1231 
1232  /**
1233  resource manager doing work outside transaction
1234  */
1236 };
1237 
1239 
1241 
1242 /**
1243  Create handler object for the table in the storage engine.
1244 
1245  @param hton Handlerton object for the storage engine.
1246  @param table TABLE_SHARE for the table, can be NULL if caller
1247  didn't perform full-blown open of table definition.
1248  @param partitioned Indicates whether table is partitioned.
1249  @param mem_root Memory root to be used for allocating handler
1250  object.
1251 */
1252 typedef handler *(*create_t)(handlerton *hton, TABLE_SHARE *table,
1253  bool partitioned, MEM_ROOT *mem_root);
1254 
1255 typedef void (*drop_database_t)(handlerton *hton, char *path);
1256 
1257 typedef int (*panic_t)(handlerton *hton, enum ha_panic_function flag);
1258 
1259 typedef int (*start_consistent_snapshot_t)(handlerton *hton, THD *thd);
1260 
1261 /**
1262  Flush the log(s) of storage engine(s).
1263 
1264  @param hton Handlerton of storage engine.
1265  @param binlog_group_flush true if we got invoked by binlog group
1266  commit during flush stage, false in other cases.
1267  @retval false Succeed
1268  @retval true Error
1269 */
1270 typedef bool (*flush_logs_t)(handlerton *hton, bool binlog_group_flush);
1271 
1273  enum ha_stat_type stat);
1274 
1275 /**
1276  The flag values are defined in sql_partition.h.
1277  If this function is set, then it implies that the handler supports
1278  partitioned tables.
1279  If this function exists, then handler::get_partition_handler must also be
1280  implemented.
1281 */
1283 
1284 /**
1285  SE specific validation of the tablespace name.
1286 
1287  This function will ask the relevant SE whether the submitted tablespace
1288  name is valid.
1289 
1290  @param ts_cmd Purpose of usage - is this tablespace DDL?
1291  @param tablespace_name Name of the tablespace.
1292 
1293  @return Tablespace name validity.
1294  @retval == false: The tablespace name is invalid.
1295  @retval == true: The tablespace name is valid.
1296 */
1298  const char *tablespace_name);
1299 
1300 /**
1301  Get the tablespace name from the SE for the given schema and table.
1302 
1303  @param thd Thread context.
1304  @param db_name Name of the relevant schema.
1305  @param table_name Name of the relevant table.
1306  @param [out] tablespace_name Name of the tablespace containing the table.
1307 
1308  @return Operation status.
1309  @retval == 0 Success.
1310  @retval != 0 Error (handler error code returned).
1311 */
1314  LEX_CSTRING *tablespace_name);
1315 
1316 /**
1317  Create/drop or alter tablespace in the storage engine.
1318 
1319  @param hton Hadlerton of the SE.
1320  @param thd Thread context.
1321  @param ts_info Description of tablespace and specific
1322  operation on it.
1323  @param old_ts_def dd::Tablespace object describing old version
1324  of tablespace.
1325  @param [in,out] new_ts_def dd::Tablespace object describing new version
1326  of tablespace. Engines which support atomic DDL
1327  can adjust this object. The updated information
1328  will be saved to the data-dictionary.
1329 
1330  @return Operation status.
1331  @retval == 0 Success.
1332  @retval != 0 Error (handler error code returned).
1333 */
1334 typedef int (*alter_tablespace_t)(handlerton *hton, THD *thd,
1335  st_alter_tablespace *ts_info,
1336  const dd::Tablespace *old_ts_def,
1337  dd::Tablespace *new_ts_def);
1338 
1339 /**
1340  SE interface for getting tablespace extension.
1341  @return Extension of tablespace datafile name.
1342 */
1343 typedef const char *(*get_tablespace_filename_ext_t)();
1344 
1345 /**
1346  Get the tablespace data from SE and insert it into Data dictionary
1347 
1348  @param thd Thread context
1349 
1350  @return Operation status.
1351  @retval == 0 Success.
1352  @retval != 0 Error (handler error code returned)
1353 */
1354 typedef int (*upgrade_tablespace_t)(THD *thd);
1355 
1356 /**
1357  Get the tablespace data from SE and insert it into Data dictionary
1358 
1359  @param[in] tablespace tablespace object
1360 
1361  @return Operation status.
1362  @retval == 0 Success.
1363  @retval != 0 Error (handler error code returned)
1364 */
1366 
1367 /**
1368  Finish upgrade process inside storage engines.
1369  This includes resetting flags to indicate upgrade process
1370  and cleanup after upgrade.
1371 
1372  @param thd Thread context
1373 
1374  @return Operation status.
1375  @retval == 0 Success.
1376  @retval != 0 Error (handler error code returned)
1377 */
1378 typedef int (*finish_upgrade_t)(THD *thd, bool failed_upgrade);
1379 
1380 /**
1381  Upgrade logs after the checkpoint from where upgrade
1382  process can only roll forward.
1383 
1384  @param thd Thread context
1385 
1386  @return Operation status.
1387  @retval == 0 Success.
1388  @retval != 0 Error (handler error code returned)
1389 */
1390 typedef int (*upgrade_logs_t)(THD *thd);
1391 
1392 enum class Tablespace_type {
1399 };
1400 
1401 /**
1402  Get the tablespace type from the SE.
1403 
1404  @param[in] space tablespace object
1405  @param[out] space_type type of space
1406 
1407  @return Operation status.
1408  @retval false on success and true for failure.
1409 */
1411  Tablespace_type *space_type);
1412 
1413 /**
1414  Get the tablespace type given the name, from the SE.
1415 
1416  @param[in] tablespace_name tablespace name
1417  @param[out] space_type type of space
1418 
1419  @return Operation status.
1420  @retval false on success and true for failure.
1421 */
1422 typedef bool (*get_tablespace_type_by_name_t)(const char *tablespace_name,
1423  Tablespace_type *space_type);
1424 
1425 typedef int (*fill_is_table_t)(handlerton *hton, THD *thd, TABLE_LIST *tables,
1426  class Item *cond, enum enum_schema_tables);
1427 
1428 typedef int (*binlog_func_t)(handlerton *hton, THD *thd, enum_binlog_func fn,
1429  void *arg);
1430 
1431 typedef void (*binlog_log_query_t)(handlerton *hton, THD *thd,
1432  enum_binlog_command binlog_command,
1433  const char *query, uint query_length,
1434  const char *db, const char *table_name);
1435 
1436 typedef int (*discover_t)(handlerton *hton, THD *thd, const char *db,
1437  const char *name, uchar **frmblob, size_t *frmlen);
1438 
1439 typedef int (*find_files_t)(handlerton *hton, THD *thd, const char *db,
1440  const char *path, const char *wild, bool dir,
1442 
1443 typedef int (*table_exists_in_engine_t)(handlerton *hton, THD *thd,
1444  const char *db, const char *name);
1445 
1446 typedef int (*make_pushed_join_t)(handlerton *hton, THD *thd,
1447  const AQP::Join_plan *plan);
1448 
1449 /**
1450  Check if the given db.tablename is a system table for this SE.
1451 
1452  @param db Database name to check.
1453  @param table_name table name to check.
1454  @param is_sql_layer_system_table if the supplied db.table_name is a SQL
1455  layer system table.
1456 
1457  @see example_is_supported_system_table in ha_example.cc
1458 
1459  is_sql_layer_system_table is supplied to make more efficient
1460  checks possible for SEs that support all SQL layer tables.
1461 
1462  This interface is optional, so every SE need not implement it.
1463 */
1464 typedef bool (*is_supported_system_table_t)(const char *db,
1465  const char *table_name,
1466  bool is_sql_layer_system_table);
1467 
1468 /**
1469  Create SDI in a tablespace. This API should be used when upgrading
1470  a tablespace with no SDI or after invoking sdi_drop().
1471  @param[in] tablespace tablespace object
1472  @retval false success
1473  @retval true failure
1474 */
1475 typedef bool (*sdi_create_t)(dd::Tablespace *tablespace);
1476 
1477 /**
1478  Drop SDI in a tablespace. This API should be used only when
1479  SDI is corrupted.
1480  @param[in] tablespace tablespace object
1481  @retval false success
1482  @retval true failure
1483 */
1484 typedef bool (*sdi_drop_t)(dd::Tablespace *tablespace);
1485 
1486 /**
1487  Get the SDI keys in a tablespace into vector.
1488  @param[in] tablespace tablespace object
1489  @param[in,out] vector vector of SDI Keys
1490  @retval false success
1491  @retval true failure
1492 */
1493 typedef bool (*sdi_get_keys_t)(const dd::Tablespace &tablespace,
1494  dd::sdi_vector_t &vector);
1495 
1496 /**
1497  Retrieve SDI for a given SDI key.
1498 
1499  Since the caller of this api will not know the SDI length, SDI retrieval
1500  should be done in the following way.
1501 
1502  i. Allocate initial memory of some size (Lets say 64KB)
1503  ii. Pass the allocated memory to the below api.
1504  iii. If passed buffer is sufficient, sdi_get_by_id() copies the sdi
1505  to the buffer passed and returns success, else sdi_len is modified
1506  with the actual length of the SDI (and returns false on failure).
1507  For genuine errors, sdi_len is returned as UINT64_MAX
1508  iv. If sdi_len != UINT64_MAX, retry the call after allocating the memory
1509  of sdi_len
1510  v. Free the memory after using SDI (responsibility of caller)
1511 
1512  @param[in] tablespace tablespace object
1513  @param[in] sdi_key SDI key to uniquely identify SDI obj
1514  @param[in,out] sdi SDI retrieved from tablespace
1515  A non-null pointer must be passed in
1516  @param[in,out] sdi_len in: length of the memory allocated
1517  out: actual length of SDI
1518  @retval false success
1519  @retval true failure
1520 */
1521 typedef bool (*sdi_get_t)(const dd::Tablespace &tablespace,
1522  const dd::sdi_key_t *sdi_key, void *sdi,
1523  uint64 *sdi_len);
1524 
1525 /**
1526  Insert/Update SDI for a given SDI key.
1527  @param[in] hton handlerton object
1528  @param[in] tablespace tablespace object
1529  @param[in] sdi_key SDI key to uniquely identify SDI obj
1530  @param[in] sdi SDI to write into the tablespace
1531  @param[in] sdi_len length of SDI BLOB returned
1532  @retval false success
1533  @retval true failure, my_error() should be called
1534  by SE
1535 */
1536 typedef bool (*sdi_set_t)(handlerton *hton, const dd::Tablespace &tablespace,
1537  const dd::Table *table, const dd::sdi_key_t *sdi_key,
1538  const void *sdi, uint64 sdi_len);
1539 
1540 /**
1541  Delete SDI for a given SDI key.
1542  @param[in] tablespace tablespace object
1543  @param[in] sdi_key SDI key to uniquely identify SDI obj
1544  @retval false success
1545  @retval true failure, my_error() should be called
1546  by SE
1547 */
1548 typedef bool (*sdi_delete_t)(const dd::Tablespace &tablespace,
1549  const dd::Table *table,
1550  const dd::sdi_key_t *sdi_key);
1551 
1552 /**
1553  Check if the DDSE is started in a way that leaves thd DD being read only.
1554 
1555  @retval true The data dictionary can only be read.
1556  @retval false The data dictionary can be read and written.
1557  */
1559 
1560 /**
1561  Drop all temporary tables which have been left from previous server
1562  run belonging to this SE. Used on server start-up.
1563 
1564  @param[in] hton Handlerton for storage engine.
1565  @param[in] thd Thread context.
1566  @param[in,out] files List of files in directories for temporary files
1567  which match tmp_file_prefix and thus can belong to
1568  temporary tables (but not necessarily in this SE).
1569  It is recommended to remove file from the list if
1570  SE recognizes it as belonging to temporary table
1571  in this SE and deletes it.
1572 */
1573 typedef bool (*rm_tmp_tables_t)(handlerton *hton, THD *thd,
1575 
1576 /**
1577  Retrieve cost constants to be used for this storage engine.
1578 
1579  A storage engine that wants to provide its own cost constants to
1580  be used in the optimizer cost model, should implement this function.
1581  The server will call this function to get a cost constant object
1582  that will be used for tables stored in this storage engine instead
1583  of using the default cost constants.
1584 
1585  Life cycle for the cost constant object: The storage engine must
1586  allocate the cost constant object on the heap. After the function
1587  returns, the server takes over the ownership of this object.
1588  The server will eventually delete the object by calling delete.
1589 
1590  @note In the initial version the storage_category parameter will
1591  not be used. The only valid value this will have is DEFAULT_STORAGE_CLASS
1592  (see declaration in opt_costconstants.h).
1593 
1594  @param storage_category the storage type that the cost constants will
1595  be used for
1596 
1597  @return a pointer to the cost constant object, if NULL is returned
1598  the default cost constants will be used
1599 */
1600 typedef SE_cost_constants *(*get_cost_constants_t)(uint storage_category);
1601 
1602 /**
1603  @param[in,out] thd pointer to THD
1604  @param[in] new_trx_arg pointer to replacement transaction
1605  @param[out] ptr_trx_arg double pointer to being replaced transaction
1606 
1607  Associated with THD engine's native transaction is replaced
1608  with @c new_trx_arg. The old value is returned through a buffer if non-null
1609  pointer is provided with @c ptr_trx_arg.
1610  The method is adapted by XA start and XA prepare handlers to
1611  handle XA transaction that is logged as two parts by slave applier.
1612 
1613  This interface concerns engines that are aware of XA transaction.
1614 */
1615 typedef void (*replace_native_transaction_in_thd_t)(THD *thd, void *new_trx_arg,
1616  void **ptr_trx_arg);
1617 
1618 /** Mode for initializing the data dictionary. */
1620  DICT_INIT_CREATE_FILES, ///< Create all required SE files
1621  DICT_INIT_CHECK_FILES, ///< Verify existence of expected files
1622  DICT_INIT_UPGRADE_57_FILES, ///< Used for upgrade from mysql-5.7
1623  DICT_INIT_IGNORE_FILES ///< Don't care about files at all
1624 };
1625 
1626 /**
1627  Initialize the SE for being used to store the DD tables. Create
1628  the required files according to the dict_init_mode. Create strings
1629  representing the required DDSE tables, i.e., tables that the DDSE
1630  expects to exist in the DD, and add them to the appropriate out
1631  parameter.
1632 
1633  @note There are two variants of this function type, one is to be
1634  used by the DDSE, and has a different type of output parameters
1635  because the SQL layer needs more information about the DDSE tables
1636  in order to support upgrade.
1637 
1638  @param dict_init_mode How to initialize files
1639  @param version Target DD version if a new
1640  server is being installed.
1641  0 if restarting an existing
1642  server.
1643  @param [out] DDSE_tables List of SQL DDL statements
1644  for creating DD tables that
1645  are needed by the DDSE.
1646  @param [out] DDSE_tablespaces List of meta data for predefined
1647  tablespaces created by the DDSE.
1648 
1649  @retval true An error occurred.
1650  @retval false Success - no errors.
1651  */
1652 
1653 typedef bool (*dict_init_t)(dict_init_mode_t dict_init_mode, uint version,
1654  List<const Plugin_table> *DDSE_tables,
1655  List<const Plugin_tablespace> *DDSE_tablespaces);
1656 
1658  dict_init_mode_t dict_init_mode, uint version,
1659  List<const dd::Object_table> *DDSE_tables,
1660  List<const Plugin_tablespace> *DDSE_tablespaces);
1661 
1662 /**
1663  Initialize the set of hard coded DD table ids.
1664 */
1665 typedef void (*dict_register_dd_table_id_t)(dd::Object_id hard_coded_tables);
1666 
1667 /**
1668  Invalidate an entry in the local dictionary cache.
1669 
1670  Needed during bootstrap to make sure the contents in the DDSE
1671  dictionary cache is in sync with the global DD.
1672 
1673  @param schema_name Schema name.
1674  @param table_name Table name.
1675  */
1676 
1677 typedef void (*dict_cache_reset_t)(const char *schema_name,
1678  const char *table_name);
1679 
1680 /**
1681  Invalidate all table and tablespace entries in the local dictionary cache.
1682 
1683  Needed for recovery during server restart.
1684  */
1685 
1687 
1688 /** Mode for data dictionary recovery. */
1690  DICT_RECOVERY_INITIALIZE_SERVER, ///< First start of a new server
1691  DICT_RECOVERY_INITIALIZE_TABLESPACES, ///< First start, create tablespaces
1692  DICT_RECOVERY_RESTART_SERVER ///< Restart of an existing server
1693 };
1694 
1695 /**
1696  Do recovery in the DDSE as part of initializing the data dictionary.
1697  The dict_recovery_mode indicates what kind of recovery should be
1698  done.
1699 
1700  @param dict_recovery_mode How to do recovery
1701  @param version Target DD version if a new
1702  server is being installed.
1703  Actual DD version if restarting
1704  an existing server.
1705 
1706  @retval true An error occurred.
1707  @retval false Success - no errors.
1708  */
1709 
1710 typedef bool (*dict_recover_t)(dict_recovery_mode_t dict_recovery_mode,
1711  uint version);
1712 
1713 /**
1714  Get the server version id stored in the header of the
1715  dictionary tablespace.
1716 
1717  @param [out] version Version number from the DD
1718  tablespace header.
1719 
1720  @retval Operation outcome, false if no error, otherwise true.
1721 */
1723 
1724 /**
1725  Store the current server version number into the
1726  header of the dictionary tablespace.
1727 
1728  @retval Operation outcome, false if no error, otherwise true.
1729 */
1731 
1732 /**
1733  Notify/get permission from storage engine before acquisition or after
1734  release of exclusive metadata lock on object represented by key.
1735 
1736  @param thd Thread context.
1737  @param mdl_key MDL key identifying object on which exclusive
1738  lock is to be acquired/was released.
1739  @param notification_type Indicates whether this is pre-acquire or
1740  post-release notification.
1741  @param victimized 'true' if locking failed as we were selected
1742  as a victim in order to avoid possible deadlocks.
1743 
1744  @note Notification is done only for objects from TABLESPACE, SCHEMA,
1745  TABLE, FUNCTION, PROCEDURE, TRIGGER and EVENT namespaces.
1746 
1747  @note Problems during notification are to be reported as warnings, MDL
1748  subsystem will report generic error if pre-acquire notification
1749  fails/SE refuses lock acquisition.
1750  @note Return value is ignored/error is not reported in case of
1751  post-release notification.
1752 
1753  @note In some cases post-release notification might happen even if
1754  there were no prior pre-acquire notification. For example,
1755  when SE was loaded after exclusive lock acquisition, or when
1756  we need notify SEs which permitted lock acquisition that it
1757  didn't happen because one of SEs didn't allow it (in such case
1758  we will do post-release notification for all SEs for simplicity).
1759 
1760  @return False - if notification was successful/lock can be acquired,
1761  True - if it has failed/lock should not be acquired.
1762 */
1763 typedef bool (*notify_exclusive_mdl_t)(THD *thd, const MDL_key *mdl_key,
1764  ha_notification_type notification_type,
1765  bool *victimized);
1766 
1767 /**
1768  Notify/get permission from storage engine before or after execution of
1769  ALTER TABLE operation on the table identified by the MDL key.
1770 
1771  @param thd Thread context.
1772  @param mdl_key MDL key identifying table which is going to be
1773  or was ALTERed.
1774  @param notification_type Indicates whether this is pre-ALTER TABLE or
1775  post-ALTER TABLE notification.
1776 
1777  @note This hook is necessary because for ALTER TABLE upgrade to X
1778  metadata lock happens fairly late during the execution process,
1779  so it can be expensive to abort ALTER TABLE operation at this
1780  stage by returning failure from notify_exclusive_mdl() hook.
1781 
1782  @note This hook follows the same error reporting convention as
1783  @see notify_exclusive_mdl().
1784 
1785  @note Similarly to notify_exclusive_mdl() in some cases post-ALTER
1786  notification might happen even if there were no prior pre-ALTER
1787  notification.
1788 
1789  @note Post-ALTER notification can happen before post-release notification
1790  for exclusive metadata lock acquired by this ALTER TABLE.
1791 
1792  @return False - if notification was successful/ALTER TABLE can proceed.
1793  True - if it has failed/ALTER TABLE should be aborted.
1794 */
1795 typedef bool (*notify_alter_table_t)(THD *thd, const MDL_key *mdl_key,
1796  ha_notification_type notification_type);
1797 
1798 /**
1799  @brief
1800  Initiate master key rotation
1801 
1802  @returns false on success,
1803  true on failure
1804 */
1806 
1807 /**
1808  @brief
1809  Retrieve ha_statistics from SE.
1810 
1811  @param db_name Name of schema
1812  @param table_name Name of table
1813  @param se_private_id SE private id of the table.
1814  @param ts_se_private_data Tablespace SE private data.
1815  @param tbl_se_private_data Table SE private data.
1816  @param flags Type of statistics to retrieve.
1817  @param[out] stats Contains statistics read from SE.
1818 
1819  @note Handlers that implement this callback/API should adhere
1820  to servers expectation that, the implementation would invoke
1821  my_error() before returning 'true'/failure from this function.
1822 
1823  @returns false on success,
1824  true on failure
1825 */
1827  const char *db_name, const char *table_name, dd::Object_id se_private_id,
1828  const dd::Properties &ts_se_private_data,
1829  const dd::Properties &tbl_se_private_data, uint flags,
1830  ha_statistics *stats);
1831 
1832 /**
1833  @brief
1834  Retrieve index column cardinality from SE.
1835 
1836  @param db_name Name of schema
1837  @param table_name Name of table
1838  @param index_name Name of index
1839  @param index_ordinal_position Position of index.
1840  @param column_ordinal_position Position of column in index.
1841  @param se_private_id SE private id of the table.
1842  @param[out] cardinality cardinality being returned by SE.
1843 
1844  @note Handlers that implement this callback/API should adhere
1845  to servers expectation that, the implementation would invoke
1846  my_error() before returning 'true'/failure from this function.
1847 
1848  @returns false on success,
1849  true on failure
1850 */
1852  const char *db_name, const char *table_name, const char *index_name,
1853  uint index_ordinal_position, uint column_ordinal_position,
1854  dd::Object_id se_private_id, ulonglong *cardinality);
1855 
1856 /**
1857  Retrieve ha_tablespace_statistics from SE.
1858 
1859  @param tablespace_name Tablespace_name
1860  @param ts_se_private_data Tablespace SE private data.
1861  @param tbl_se_private_data Table SE private data.
1862  @param[out] stats Contains tablespace
1863  statistics read from SE.
1864 
1865  @note Handlers that implement this callback/API should adhere
1866  to servers expectation that, the implementation would invoke
1867  my_error() before returning 'true'/failure from this function.
1868 
1869  @returns false on success, true on failure
1870 */
1872  const char *tablespace_name, const char *file_name,
1873  const dd::Properties &ts_se_private_data, ha_tablespace_statistics *stats);
1874 
1875 /* Database physical clone interfaces */
1876 
1877 /** Get capability flags for clone operation
1878 @param[out] flags capability flag */
1880 
1881 /** Begin copy from source database
1882 @param[in] hton handlerton for SE
1883 @param[in] thd server thread handle
1884 @param[in,out] loc locator
1885 @param[in,out] loc_len locator length
1886 @param[out] task_id task identifier
1887 @param[in] type clone type
1888 @param[in] mode mode for starting clone
1889 @return error code */
1890 using Clone_begin_t = int (*)(handlerton *hton, THD *thd, const uchar *&loc,
1891  uint &loc_len, uint &task_id, Ha_clone_type type,
1893 
1894 /** Copy data from source database in chunks via callback
1895 @param[in] hton handlerton for SE
1896 @param[in] thd server thread handle
1897 @param[in] loc locator
1898 @param[in] loc_len locator length in bytes
1899 @param[in] task_id task identifier
1900 @param[in] cbk callback interface for sending data
1901 @return error code */
1902 using Clone_copy_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
1903  uint loc_len, uint task_id, Ha_clone_cbk *cbk);
1904 
1905 /** Acknowledge data transfer to source database
1906 @param[in] hton handlerton for SE
1907 @param[in] thd server thread handle
1908 @param[in] loc locator
1909 @param[in] loc_len locator length in bytes
1910 @param[in] task_id task identifier
1911 @param[in] in_err inform any error occurred
1912 @param[in] cbk callback interface
1913 @return error code */
1914 using Clone_ack_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
1915  uint loc_len, uint task_id, int in_err,
1917 
1918 /** End copy from source database
1919 @param[in] hton handlerton for SE
1920 @param[in] thd server thread handle
1921 @param[in] loc locator
1922 @param[in] loc_len locator length in bytes
1923 @param[in] task_id task identifier
1924 @param[in] in_err error code when ending after error
1925 @return error code */
1926 using Clone_end_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
1927  uint loc_len, uint task_id, int in_err);
1928 
1929 /** Begin apply to destination database
1930 @param[in] hton handlerton for SE
1931 @param[in] thd server thread handle
1932 @param[in,out] loc locator
1933 @param[in,out] loc_len locator length
1934 @param[in] task_id task identifier
1935 @param[in] mode mode for starting clone
1936 @param[in] data_dir target data directory
1937 @return error code */
1938 using Clone_apply_begin_t = int (*)(handlerton *hton, THD *thd,
1939  const uchar *&loc, uint &loc_len,
1940  uint &task_id, Ha_clone_mode mode,
1941  const char *data_dir);
1942 
1943 /** Apply data to destination database in chunks via callback
1944 @param[in] hton handlerton for SE
1945 @param[in] thd server thread handle
1946 @param[in] loc locator
1947 @param[in] loc_len locator length in bytes
1948 @param[in] task_id task identifier
1949 @param[in] in_err inform any error occurred
1950 @param[in] cbk callback interface for receiving data
1951 @return error code */
1952 using Clone_apply_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
1953  uint loc_len, uint task_id, int in_err,
1955 
1956 /** End apply to destination database
1957 @param[in] hton handlerton for SE
1958 @param[in] thd server thread handle
1959 @param[in] loc locator
1960 @param[in] loc_len locator length in bytes
1961 @param[in] task_id task identifier
1962 @param[in] in_err error code when ending after error
1963 @return error code */
1964 using Clone_apply_end_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
1965  uint loc_len, uint task_id, int in_err);
1966 
1968  /* Get clone capabilities of an SE */
1970 
1971  /* Interfaces to copy data. */
1976 
1977  /* Interfaces to apply data. */
1981 };
1982 
1983 /**
1984  Perform post-commit/rollback cleanup after DDL statement (e.g. in
1985  case of DROP TABLES really remove table files from disk).
1986 
1987  @note This hook will be invoked after DDL commit or rollback only
1988  for storage engines supporting atomic DDL.
1989 
1990  @note Problems during execution of this method should be reported to
1991  error log and as warnings/notes to user. Since this method is
1992  called after successful commit of the statement we can't fail
1993  statement with error.
1994 */
1995 typedef void (*post_ddl_t)(THD *thd);
1996 
1997 /**
1998  Perform SE-specific cleanup after recovery of transactions.
1999 
2000  @note Particularly SEs supporting atomic DDL can use this call
2001  to perform post-DDL actions for DDL statements which were
2002  committed or rolled back during recovery stage.
2003 */
2004 typedef void (*post_recover_t)(void);
2005 
2006 /**
2007  Lock a handlerton (resource) log to collect log information.
2008 */
2009 
2010 typedef bool (*lock_hton_log_t)(handlerton *hton);
2011 
2012 /**
2013  Unlock a handlerton (resource) log after collecting log information.
2014 */
2015 
2017 
2018 /**
2019  Collect a handlerton (resource) log information.
2020 */
2021 
2023 
2024 /**
2025  Check SE considers types of child and parent columns in foreign key
2026  to be compatible.
2027 
2028  @param child_column_type Child column type description.
2029  @param parent_column_type Parent column type description.
2030  @param check_charsets Indicates whether we need to check
2031  that charsets of string columns
2032  match. Which is true in most cases.
2033 
2034  @returns True if types are compatible, False if not.
2035 */
2036 
2038  const Ha_fk_column_type *child_column_type,
2039  const Ha_fk_column_type *parent_column_type, bool check_charsets);
2040 
2041 typedef bool (*is_reserved_db_name_t)(handlerton *hton, const char *name);
2042 
2043 /**
2044  Prepare the secondary engine for executing a statement. This function is
2045  called right after the secondary engine TABLE objects have been opened by
2046  open_secondary_engine_tables(), before the statement is optimized and
2047  executed. Secondary engines will typically create a context object in this
2048  function, which they can use to store state that is needed during the
2049  optimization and execution phases.
2050 
2051  @param thd thread context
2052  @param lex the statement to execute
2053  @return true on error, false on success
2054 */
2055 using prepare_secondary_engine_t = bool (*)(THD *thd, LEX *lex);
2056 
2057 /**
2058  Optimize a statement for execution on a secondary storage engine. This
2059  function is called when the optimization of a statement has completed, just
2060  before the statement is executed. Secondary engines can use this function to
2061  apply engine-specific optimizations to the execution plan. They can also
2062  reject executing the query by raising an error, in which case the query will
2063  be reprepared and executed by the primary storage engine.
2064 
2065  @param thd thread context
2066  @param lex the statement being optimized
2067  @return true on error, false on success
2068 */
2069 using optimize_secondary_engine_t = bool (*)(THD *thd, LEX *lex);
2070 
2071 /**
2072  Compares the cost of two join plans in the secondary storage engine. The cost
2073  of the current candidate is compared with the cost of the best plan seen so
2074  far.
2075 
2076  @param thd thread context
2077  @param join the JOIN to evaluate
2078  @param table_order the ordering of the tables in the candidate plan
2079  @param optimizer_cost the cost estimate calculated by the optimizer
2080  @param[out] cheaper true if the candidate is the best plan seen so far for
2081  this JOIN (must be true if it is the first plan seen),
2082  false otherwise
2083  @param[out] secondary_engine_cost the cost estimated by the secondary engine
2084 
2085  @return false on success, or true if an error has been raised
2086 */
2088  THD *thd, const JOIN &join, const Candidate_table_order &table_order,
2089  double optimizer_cost, bool *cheaper, double *secondary_engine_cost);
2090 
2091 // FIXME: Temporary workaround to enable storage engine plugins to use the
2092 // before_commit hook. Remove after WL#11320 has been completed.
2093 typedef void (*se_before_commit_t)(void *arg);
2094 
2095 // FIXME: Temporary workaround to enable storage engine plugins to use the
2096 // after_commit hook. Remove after WL#11320 has been completed.
2097 typedef void (*se_after_commit_t)(void *arg);
2098 
2099 // FIXME: Temporary workaround to enable storage engine plugins to use the
2100 // before_rollback hook. Remove after WL#11320 has been completed.
2101 typedef void (*se_before_rollback_t)(void *arg);
2102 
2103 /*
2104  Page Tracking : interfaces to handlerton functions which starts/stops page
2105  tracking, and purges/fetches page tracking information.
2106 */
2107 
2108 /**
2109  Start page tracking.
2110 
2111  @param[out] start_id SE specific sequence number [LSN for InnoDB]
2112  indicating when the tracking was started
2113 
2114  @return Operation status.
2115  @retval 0 Success
2116  @retval other ER_* mysql error. Get error details from THD.
2117 */
2118 using page_track_start_t = int (*)(uint64_t *start_id);
2119 
2120 /**
2121  Stop page tracking.
2122 
2123  @param[out] stop_id SE specific sequence number [LSN for InnoDB]
2124  indicating when the tracking was stopped
2125 
2126  @return Operation status.
2127  @retval 0 Success
2128  @retval other ER_* mysql error. Get error details from THD.
2129 */
2130 using page_track_stop_t = int (*)(uint64_t *stop_id);
2131 
2132 /**
2133  Purge page tracking data.
2134 
2135  @param[in,out] purge_id SE specific sequence number [LSN for InnoDB]
2136  initially indicating till where the data needs to be purged and finally
2137  updated to until where it was actually purged
2138 
2139  @return Operation status.
2140  @retval 0 Success
2141  @retval other ER_* mysql error. Get error details from THD.
2142 */
2143 using page_track_purge_t = int (*)(uint64_t *purge_id);
2144 
2145 /**
2146  Fetch tracked pages.
2147 
2148  @param[in] cbk_func callback function return page IDs
2149  @param[in] cbk_ctx caller's context for callback
2150  @param[in,out] start_id SE specific sequence number [LSN for InnoDB] from
2151  where the pages tracked would be returned.
2152  @note The range might get expanded and the actual start_id used for the
2153  querying will be updated.
2154  @param[in,out] stop_id SE specific sequence number [LSN for InnoDB]
2155  until where the pages tracked would be returned.
2156  @note The range might get expanded and the actual stop_id used for the
2157  querying will be updated.
2158  @param[out] buffer allocated buffer to copy page IDs
2159  @param[in] buffer_len length of buffer in bytes
2160 
2161  @return Operation status.
2162  @retval 0 Success
2163  @retval other ER_* mysql error. Get error details from THD.
2164 */
2165 using page_track_get_page_ids_t = int (*)(Page_Track_Callback cbk_func,
2166  void *cbk_ctx, uint64_t *start_id,
2167  uint64_t *stop_id,
2168  unsigned char *buffer,
2169  size_t buffer_len);
2170 
2171 /**
2172  Fetch approximate number of tracked pages in the given range.
2173 
2174  @param[in,out] start_id SE specific sequence number [LSN for InnoDB] from
2175  where the pages tracked would be returned.
2176  @note the range might get expanded and the actual start_id used for the
2177  querying will be updated.
2178  @param[in,out] stop_id SE specific sequence number [LSN for InnoDB]
2179  until where the pages tracked would be returned.
2180  @note the range might get expanded and the actual stop_id used for the
2181  querying will be updated.
2182  @param[out] num_pages number of pages tracked
2183 
2184  @return Operation status.
2185  @retval 0 Success
2186  @retval other ER_* mysql error. Get error details from THD.
2187 */
2188 using page_track_get_num_page_ids_t = int (*)(uint64_t *start_id,
2189  uint64_t *stop_id,
2190  uint64_t *num_pages);
2191 
2192 /** Fetch the status of the page tracking system.
2193 @param[out] status vector of a pair of (ID, bool) where ID is the
2194 start/stop point and bool is true if the ID is a start point else false */
2196  void (*)(std::vector<std::pair<uint64_t, bool>> &status);
2197 
2198 /** Page track interface */
2206 };
2207 
2208 /**
2209  handlerton is a singleton structure - one instance per storage engine -
2210  to provide access to storage engine functionality that works on the
2211  "global" level (unlike handler class that works on a per-table basis).
2212 
2213  usually handlerton instance is defined statically in ha_xxx.cc as
2214 
2215  static handlerton { ... } xxx_hton;
2216 
2217  savepoint_*, prepare, recover, and *_by_xid pointers can be 0.
2218 */
2219 struct handlerton {
2220  /**
2221  Historical marker for if the engine is available or not.
2222  */
2224 
2225  /**
2226  Historical number used for frm file to determine the correct storage engine.
2227  This is going away and new engines will just use "name" for this.
2228  */
2230  /**
2231  Each storage engine has it's own memory area (actually a pointer)
2232  in the thd, for storing per-connection information.
2233  It is accessed as
2234 
2235  thd->ha_data[xxx_hton.slot]
2236 
2237  slot number is initialized by MySQL after xxx_init() is called.
2238  */
2240  /**
2241  To store per-savepoint data storage engine is provided with an area
2242  of a requested size (0 is ok here).
2243  savepoint_offset must be initialized statically to the size of
2244  the needed memory to store per-savepoint information.
2245  After xxx_init it is changed to be an offset to savepoint storage
2246  area and need not be used by storage engine.
2247  see binlog_hton and binlog_savepoint_set/rollback for an example.
2248  */
2250 
2251  /* handlerton methods */
2252 
2294 
2295  /** Global handler flags. */
2296  uint32 flags;
2297 
2298  /*
2299  Those handlerton functions below are properly initialized at handler
2300  init.
2301  */
2302 
2310 
2311  /*
2312  APIs for retrieving Serialized Dictionary Information by tablespace id
2313  */
2314 
2321 
2322  /**
2323  Null-ended array of file extentions that exist for the storage engine.
2324  Used by frm_error() and the default handler::rename_table and delete_table
2325  methods in handler.cc.
2326 
2327  For engines that have two file name extentions (separate meta/index file
2328  and data file), the order of elements is relevant. First element of engine
2329  file name extentions array should be meta/index file extention. Second
2330  element - data file extention. This order is assumed by
2331  prepare_for_repair() when REPAIR TABLE ... USE_FRM is issued.
2332 
2333  For engines that don't have files, file_extensions is NULL.
2334 
2335  Currently, the following alternatives are used:
2336  - file_extensions == NULL;
2337  - file_extensions[0] != NULL, file_extensions[1] == NULL;
2338  - file_extensions[0] != NULL, file_extensions[1] != NULL,
2339  file_extensions[2] == NULL;
2340  */
2341  const char **file_extensions;
2342 
2350 
2354 
2357 
2358  /** Clone data transfer interfaces */
2360 
2361  /** Flag for Engine License. */
2362  uint32 license;
2363  /** Location for engines to keep personal structures. */
2364  void *data;
2365 
2366  /*
2367  Log_resource functions that must be supported by storage engines
2368  with relevant log information to be collected.
2369  */
2373 
2374  /** Flags describing details of foreign key support by storage engine. */
2376 
2378 
2379  /**
2380  Pointer to a function that prepares a secondary engine for executing a
2381  statement.
2382 
2383  @see prepare_secondary_engine_t for function signature.
2384  */
2386 
2387  /**
2388  Pointer to a function that optimizes the current statement for
2389  execution on the secondary storage engine represented by this
2390  handlerton.
2391 
2392  @see optimize_secondary_engine_t for function signature.
2393  */
2395 
2396  /**
2397  Pointer to a function that estimates the cost of executing a join in a
2398  secondary storage engine.
2399 
2400  @see compare_secondary_engine_cost_t for function signature.
2401  */
2403 
2407 
2408  /** Page tracking interface */
2410 };
2411 
2412 /* Possible flags of a handlerton (there can be 32 of them) */
2413 #define HTON_NO_FLAGS 0
2414 #define HTON_CLOSE_CURSORS_AT_COMMIT (1 << 0)
2415 #define HTON_ALTER_NOT_SUPPORTED (1 << 1) // Engine does not support alter
2416 #define HTON_CAN_RECREATE (1 << 2) // Delete all is used fro truncate
2417 #define HTON_HIDDEN (1 << 3) // Engine does not appear in lists
2418 /*
2419  Bit 4 was occupied by BDB-specific HTON_FLUSH_AFTER_RENAME flag and is no
2420  longer used.
2421 */
2422 #define HTON_NOT_USER_SELECTABLE (1 << 5)
2423 #define HTON_TEMPORARY_NOT_SUPPORTED \
2424  (1 << 6) // Having temporary tables not supported
2425 #define HTON_SUPPORT_LOG_TABLES (1 << 7) // Engine supports log tables
2426 #define HTON_NO_PARTITION (1 << 8) // You can not partition these tables
2427 
2428 /*
2429  This flag should be set when deciding that the engine does not allow row based
2430  binary logging (RBL) optimizations.
2431 
2432  Currently, setting this flag, means that table's read/write_set will be left
2433  untouched when logging changes to tables in this engine. In practice this
2434  means that the server will not mess around with table->write_set and/or
2435  table->read_set when using RBL and deciding whether to log full or minimal
2436  rows.
2437 
2438  It's valuable for instance for virtual tables, eg: Performance Schema which
2439  have no meaning for replication.
2440 */
2441 #define HTON_NO_BINLOG_ROW_OPT (1 << 9)
2442 
2443 /**
2444  Engine supports extended keys. The flag allows to
2445  use 'extended key' feature if the engine is able to
2446  do it (has primary key values in the secondary key).
2447  Note that handler flag HA_PRIMARY_KEY_IN_READ_INDEX is
2448  actually partial case of HTON_SUPPORTS_EXTENDED_KEYS.
2449 */
2450 
2451 #define HTON_SUPPORTS_EXTENDED_KEYS (1 << 10)
2452 
2453 // Engine support foreign key constraint.
2454 
2455 #define HTON_SUPPORTS_FOREIGN_KEYS (1 << 11)
2456 
2457 /**
2458  Engine supports atomic DDL. That is rollback of transaction for DDL
2459  statement will also rollback all changes in SE, commit of transaction
2460  of DDL statement will make it durable.
2461 */
2462 
2463 #define HTON_SUPPORTS_ATOMIC_DDL (1 << 12)
2464 
2465 /* Engine supports packed keys. */
2466 #define HTON_SUPPORTS_PACKED_KEYS (1 << 13)
2467 
2468 /** Engine is a secondary storage engine. */
2469 #define HTON_IS_SECONDARY_ENGINE (1 << 14)
2470 
2471 /** Engine supports secondary storage engines. */
2472 #define HTON_SUPPORTS_SECONDARY_ENGINE (1 << 15)
2473 
2474 /** Engine supports table or tablespace encryption . */
2475 #define HTON_SUPPORTS_TABLE_ENCRYPTION (1 << 16)
2476 
2477 inline bool ddl_is_atomic(const handlerton *hton) {
2478  return (hton->flags & HTON_SUPPORTS_ATOMIC_DDL) != 0;
2479 }
2480 
2481 /* Bits for handlerton::foreign_keys_flags bitmap. */
2482 
2483 /**
2484  Engine supports both unique and non-unique parent keys for
2485  foreign keys which contain full foreign key as its prefix.
2486 
2487  Storage engines which support foreign keys but do not have
2488  this flag set are assumed to support only parent keys which
2489  are primary/unique and contain exactly the same columns as
2490  the foreign key, possibly, in different order.
2491 */
2492 
2493 static const uint32 HTON_FKS_WITH_PREFIX_PARENT_KEYS = (1 << 0);
2494 
2495 /**
2496  Storage engine supports hash keys as supporting keys for foreign
2497  keys. Hash key should contain all foreign key columns and only
2498  them (altough in any order).
2499 
2500  Storage engines which support foreign keys but do not have this
2501  flag set are assumed to not allow hash keys as supporting keys.
2502 */
2503 
2504 static const uint32 HTON_FKS_WITH_SUPPORTING_HASH_KEYS = (1 << 1);
2505 
2506 /**
2507  Storage engine supports non-hash keys which have common prefix
2508  with the foreign key as supporting keys for it. If there are
2509  several such keys, one which shares biggest prefix with FK is
2510  chosen.
2511 
2512  Storage engines which support foreign keys but do not have this
2513  flag set are assumed to require that supporting key contains full
2514  foreign key as its prefix.
2515 */
2516 
2517 static const uint32 HTON_FKS_WITH_ANY_PREFIX_SUPPORTING_KEYS = (1 << 2);
2518 
2519 /**
2520  Storage engine does not support using the same key for both parent
2521  and supporting key, but requires the two to be different.
2522 */
2523 
2525  (1 << 3);
2526 
2527 enum enum_tx_isolation : int {
2532 };
2533 
2538 };
2539 
2540 /* struct to hold information about the table that should be created */
2542  const CHARSET_INFO *table_charset{nullptr};
2545  const char *password{nullptr};
2546  const char *tablespace{nullptr};
2547  LEX_STRING comment{nullptr, 0};
2548 
2549  /**
2550  Algorithm (and possible options) to be used for InnoDB's transparent
2551  page compression. If this attribute is set then it is hint to the
2552  storage engine to try and compress the data using the specified algorithm
2553  where possible. Note: this value is interpreted by the storage engine only.
2554  and ignored by the Server layer. */
2555 
2556  LEX_STRING compress{nullptr, 0};
2557 
2558  /**
2559  This attibute is used for InnoDB's transparent page encryption.
2560  If this attribute is set then it is hint to the storage engine to encrypt
2561  the data. Note: this value is interpreted by the storage engine only.
2562  and ignored by the Server layer. */
2563 
2565 
2566  /**
2567  * Secondary engine of the table.
2568  * Is nullptr if no secondary engine defined.
2569  */
2571 
2572  const char *data_file_name{nullptr};
2573  const char *index_file_name{nullptr};
2574  const char *alias{nullptr};
2582  uint stats_sample_pages{0}; /* number of pages to sample during
2583  stats estimation, if used, otherwise 0. */
2586  handlerton *db_type{nullptr};
2587  /**
2588  Row type of the table definition.
2589 
2590  Defaults to ROW_TYPE_DEFAULT for all non-ALTER statements.
2591  For ALTER TABLE defaults to ROW_TYPE_NOT_USED (means "keep the current").
2592 
2593  Can be changed either explicitly by the parser.
2594  If nothing specified inherits the value of the original table (if present).
2595  */
2597  uint null_bits{0}; /* NULL bits at start of record */
2598  uint options{0}; /* OR of HA_CREATE_ options */
2600  ha_storage_media storage_media{HA_SM_DEFAULT}; /* DEFAULT, DISK or MEMORY */
2601 
2602  /*
2603  A flag to indicate if this table should be marked as a hidden table in
2604  the data dictionary. One use case is to mark the temporary tables
2605  created by ALTER to be marked as hidden.
2606  */
2607  bool m_hidden{false};
2608 
2609  /**
2610  Fill HA_CREATE_INFO to be used by ALTER as well as upgrade code.
2611  This function separates code from mysql_prepare_alter_table() to be
2612  used by upgrade code as well to reduce code duplication.
2613  For ALTER code path, this lets new create options override the old
2614  ones.
2615 
2616  @param[in] share TABLE_SHARE object
2617  @param[in] used_fields If a given create option is not flagged, old
2618  value be copied from the TABLE_SHARE.
2619  */
2620 
2621  void init_create_options_from_share(const TABLE_SHARE *share,
2622  uint used_fields);
2623 };
2624 
2625 /**
2626  Structure describing changes to an index to be caused by ALTER TABLE.
2627 */
2628 
2629 struct KEY_PAIR {
2630  /**
2631  Pointer to KEY object describing old version of index in
2632  TABLE::key_info array for TABLE instance representing old
2633  version of table.
2634  */
2636  /**
2637  Pointer to KEY object describing new version of index in
2638  Alter_inplace_info::key_info_buffer array.
2639  */
2641 };
2642 
2643 /**
2644  In-place alter handler context.
2645 
2646  This is a superclass intended to be subclassed by individual handlers
2647  in order to store handler unique context between in-place alter API calls.
2648 
2649  The handler is responsible for creating the object. This can be done
2650  as early as during check_if_supported_inplace_alter().
2651 
2652  The SQL layer is responsible for destroying the object.
2653 
2654  @see Alter_inplace_info
2655 */
2656 
2658  public:
2660 
2661  virtual void set_shared_data(
2662  const inplace_alter_handler_ctx *ctx MY_ATTRIBUTE((unused))) {}
2664 };
2665 
2666 /**
2667  Class describing changes to be done by ALTER TABLE.
2668  Instance of this class is passed to storage engine in order
2669  to determine if this ALTER TABLE can be done using in-place
2670  algorithm. It is also used for executing the ALTER TABLE
2671  using in-place algorithm.
2672 */
2673 
2675  public:
2676  /**
2677  Bits to show in detail what operations the storage engine is
2678  to execute.
2679 
2680  All these operations are supported as in-place operations by the
2681  SQL layer. This means that operations that by their nature must
2682  be performed by copying the table to a temporary table, will not
2683  have their own flags here (e.g. ALTER TABLE FORCE, ALTER TABLE
2684  ENGINE).
2685 
2686  We generally try to specify handler flags only if there are real
2687  changes. But in cases when it is cumbersome to determine if some
2688  attribute has really changed we might choose to set flag
2689  pessimistically, for example, relying on parser output only.
2690  */
2692 
2693  // Add non-unique, non-primary index
2694  static const HA_ALTER_FLAGS ADD_INDEX = 1ULL << 0;
2695 
2696  // Drop non-unique, non-primary index
2697  static const HA_ALTER_FLAGS DROP_INDEX = 1ULL << 1;
2698 
2699  // Add unique, non-primary index
2700  static const HA_ALTER_FLAGS ADD_UNIQUE_INDEX = 1ULL << 2;
2701 
2702  // Drop unique, non-primary index
2703  static const HA_ALTER_FLAGS DROP_UNIQUE_INDEX = 1ULL << 3;
2704 
2705  // Add primary index
2706  static const HA_ALTER_FLAGS ADD_PK_INDEX = 1ULL << 4;
2707 
2708  // Drop primary index
2709  static const HA_ALTER_FLAGS DROP_PK_INDEX = 1ULL << 5;
2710 
2711  // Add column
2712 
2713  // Virtual generated column
2714  static const HA_ALTER_FLAGS ADD_VIRTUAL_COLUMN = 1ULL << 6;
2715  // Stored base (non-generated) column
2716  static const HA_ALTER_FLAGS ADD_STORED_BASE_COLUMN = 1ULL << 7;
2717  // Stored generated column
2719  // Add generic column (convience constant).
2722 
2723  // Drop column
2724  static const HA_ALTER_FLAGS DROP_VIRTUAL_COLUMN = 1ULL << 9;
2725  static const HA_ALTER_FLAGS DROP_STORED_COLUMN = 1ULL << 10;
2728 
2729  // Rename column
2730  static const HA_ALTER_FLAGS ALTER_COLUMN_NAME = 1ULL << 11;
2731 
2732  // Change column datatype
2733  static const HA_ALTER_FLAGS ALTER_VIRTUAL_COLUMN_TYPE = 1ULL << 12;
2734  static const HA_ALTER_FLAGS ALTER_STORED_COLUMN_TYPE = 1ULL << 13;
2735 
2736  /**
2737  Change column datatype in such way that new type has compatible
2738  packed representation with old type, so it is theoretically
2739  possible to perform change by only updating data dictionary
2740  without changing table rows.
2741  */
2743 
2744  /// A virtual column has changed its position
2745  static const HA_ALTER_FLAGS ALTER_VIRTUAL_COLUMN_ORDER = 1ULL << 15;
2746 
2747  /// A stored column has changed its position (disregarding virtual columns)
2748  static const HA_ALTER_FLAGS ALTER_STORED_COLUMN_ORDER = 1ULL << 16;
2749 
2750  // Change column from NOT NULL to NULL
2751  static const HA_ALTER_FLAGS ALTER_COLUMN_NULLABLE = 1ULL << 17;
2752 
2753  // Change column from NULL to NOT NULL
2754  static const HA_ALTER_FLAGS ALTER_COLUMN_NOT_NULLABLE = 1ULL << 18;
2755 
2756  // Set or remove default column value
2757  static const HA_ALTER_FLAGS ALTER_COLUMN_DEFAULT = 1ULL << 19;
2758 
2759  // Change column generation expression
2760  static const HA_ALTER_FLAGS ALTER_VIRTUAL_GCOL_EXPR = 1ULL << 20;
2761  static const HA_ALTER_FLAGS ALTER_STORED_GCOL_EXPR = 1ULL << 21;
2762 
2763  // Add foreign key
2764  static const HA_ALTER_FLAGS ADD_FOREIGN_KEY = 1ULL << 22;
2765 
2766  // Drop foreign key
2767  static const HA_ALTER_FLAGS DROP_FOREIGN_KEY = 1ULL << 23;
2768 
2769  // table_options changed, see HA_CREATE_INFO::used_fields for details.
2770  static const HA_ALTER_FLAGS CHANGE_CREATE_OPTION = 1ULL << 24;
2771 
2772  // Table is renamed
2773  static const HA_ALTER_FLAGS ALTER_RENAME = 1ULL << 25;
2774 
2775  // Change the storage type of column
2776  static const HA_ALTER_FLAGS ALTER_COLUMN_STORAGE_TYPE = 1ULL << 26;
2777 
2778  // Change the column format of column
2779  static const HA_ALTER_FLAGS ALTER_COLUMN_COLUMN_FORMAT = 1ULL << 27;
2780 
2781  // Add partition
2782  static const HA_ALTER_FLAGS ADD_PARTITION = 1ULL << 28;
2783 
2784  // Drop partition
2785  static const HA_ALTER_FLAGS DROP_PARTITION = 1ULL << 29;
2786 
2787  // Changing partition options
2788  static const HA_ALTER_FLAGS ALTER_PARTITION = 1ULL << 30;
2789 
2790  // Coalesce partition
2791  static const HA_ALTER_FLAGS COALESCE_PARTITION = 1ULL << 31;
2792 
2793  // Reorganize partition ... into
2794  static const HA_ALTER_FLAGS REORGANIZE_PARTITION = 1ULL << 32;
2795 
2796  // Reorganize partition
2797  static const HA_ALTER_FLAGS ALTER_TABLE_REORG = 1ULL << 33;
2798 
2799  // Remove partitioning
2800  static const HA_ALTER_FLAGS ALTER_REMOVE_PARTITIONING = 1ULL << 34;
2801 
2802  // Partition operation with ALL keyword
2803  static const HA_ALTER_FLAGS ALTER_ALL_PARTITION = 1ULL << 35;
2804 
2805  /**
2806  Rename index. Note that we set this flag only if there are no other
2807  changes to the index being renamed. Also for simplicity we don't
2808  detect renaming of indexes which is done by dropping index and then
2809  re-creating index with identical definition under different name.
2810  */
2811  static const HA_ALTER_FLAGS RENAME_INDEX = 1ULL << 36;
2812 
2813  /**
2814  Recreate the table for ALTER TABLE FORCE, ALTER TABLE ENGINE
2815  and OPTIMIZE TABLE operations.
2816  */
2817  static const HA_ALTER_FLAGS RECREATE_TABLE = 1ULL << 37;
2818 
2819  // Add spatial index
2820  static const HA_ALTER_FLAGS ADD_SPATIAL_INDEX = 1ULL << 38;
2821 
2822  // Alter index comment
2823  static const HA_ALTER_FLAGS ALTER_INDEX_COMMENT = 1ULL << 39;
2824 
2825  // New/changed virtual generated column require validation
2826  static const HA_ALTER_FLAGS VALIDATE_VIRTUAL_COLUMN = 1ULL << 40;
2827 
2828  /**
2829  Change index option in a way which is likely not to require index
2830  recreation. For example, change COMMENT or KEY::is_algorithm_explicit
2831  flag (without change of index algorithm itself).
2832  */
2833  static const HA_ALTER_FLAGS CHANGE_INDEX_OPTION = 1LL << 41;
2834 
2835  // Rebuild partition
2836  static const HA_ALTER_FLAGS ALTER_REBUILD_PARTITION = 1ULL << 42;
2837 
2838  /**
2839  Change in index length such that it does not require index rebuild.
2840  For example, change in index length due to column expansion like
2841  varchar(X) changed to varchar(X + N).
2842  */
2843  static const HA_ALTER_FLAGS ALTER_COLUMN_INDEX_LENGTH = 1ULL << 43;
2844 
2845  /**
2846  Change to one of columns on which virtual generated column depends,
2847  so its values require re-evaluation.
2848  */
2849  static const HA_ALTER_FLAGS VIRTUAL_GCOL_REEVAL = 1ULL << 44;
2850 
2851  /**
2852  Change to one of columns on which stored generated column depends,
2853  so its values require re-evaluation.
2854  */
2855  static const HA_ALTER_FLAGS STORED_GCOL_REEVAL = 1ULL << 45;
2856 
2857  // Add check constraint.
2858  static const HA_ALTER_FLAGS ADD_CHECK_CONSTRAINT = 1ULL << 46;
2859 
2860  // Drop check constraint.
2861  static const HA_ALTER_FLAGS DROP_CHECK_CONSTRAINT = 1ULL << 47;
2862 
2863  // Suspend check constraint.
2864  static const HA_ALTER_FLAGS SUSPEND_CHECK_CONSTRAINT = 1ULL << 48;
2865 
2866  /**
2867  Create options (like MAX_ROWS) for the new version of table.
2868 
2869  @note The referenced instance of HA_CREATE_INFO object was already
2870  used to create new .FRM file for table being altered. So it
2871  has been processed by mysql_prepare_create_table() already.
2872  For example, this means that it has HA_OPTION_PACK_RECORD
2873  flag in HA_CREATE_INFO::table_options member correctly set.
2874  */
2876 
2877  /**
2878  Alter options, fields and keys for the new version of table.
2879 
2880  @note The referenced instance of Alter_info object was already
2881  used to create new .FRM file for table being altered. So it
2882  has been processed by mysql_prepare_create_table() already.
2883  In particular, this means that in Create_field objects for
2884  fields which were present in some form in the old version
2885  of table, Create_field::field member points to corresponding
2886  Field instance for old version of table.
2887  */
2889 
2890  /**
2891  Indicates whether operation should fail if table is non-empty.
2892  Storage engines should not suggest/allow execution of such operations
2893  using INSTANT algorithm since check whether table is empty done from
2894  SQL-layer is not "instant". Also SEs might choose different algorithm for
2895  ALTER TABLE execution knowing that it will be allowed to proceed only if
2896  table is empty.
2897 
2898  Unlike for Alter_table_ctx::error_if_not_empty, we use bool for this flag
2899  and not bitmap, since SEs are really interested in the fact that ALTER
2900  will fail if table is not empty and not in exact reason behind this fact,
2901  and because we want to avoid extra dependency between Alter_table_ctx and
2902  Alter_inplace_info.
2903  */
2905 
2906  /**
2907  Array of KEYs for new version of table - including KEYs to be added.
2908 
2909  @note Currently this array is produced as result of
2910  mysql_prepare_create_table() call.
2911  This means that it follows different convention for
2912  KEY_PART_INFO::fieldnr values than objects in TABLE::key_info
2913  array.
2914 
2915  @todo This is mainly due to the fact that we need to keep compatibility
2916  with removed handler::add_index() call. We plan to switch to
2917  TABLE::key_info numbering later.
2918 
2919  KEYs are sorted - see sort_keys().
2920  */
2922 
2923  /** Size of key_info_buffer array. */
2925 
2926  /** Size of index_drop_buffer array. */
2928 
2929  /**
2930  Array of pointers to KEYs to be dropped belonging to the TABLE instance
2931  for the old version of the table.
2932  */
2934 
2935  /** Size of index_add_buffer array. */
2937 
2938  /**
2939  Array of indexes into key_info_buffer for KEYs to be added,
2940  sorted in increasing order.
2941  */
2943 
2944  /** Size of index_rename_buffer array. */
2946 
2947  /** Size of index_rename_buffer array. */
2949 
2950  /**
2951  Array of KEY_PAIR objects describing indexes being renamed.
2952  For each index renamed it contains object with KEY_PAIR::old_key
2953  pointing to KEY object belonging to the TABLE instance for old
2954  version of table representing old version of index and with
2955  KEY_PAIR::new_key pointing to KEY object for new version of
2956  index in key_info_buffer member.
2957  */
2960 
2961  /**
2962  Context information to allow handlers to keep context between in-place
2963  alter API calls.
2964 
2965  @see inplace_alter_handler_ctx for information about object lifecycle.
2966  */
2968 
2969  /**
2970  If the table uses several handlers, like ha_partition uses one handler
2971  per partition, this contains a Null terminated array of ctx pointers
2972  that should all be committed together.
2973  Or NULL if only handler_ctx should be committed.
2974  Set to NULL if the low level handler::commit_inplace_alter_table uses it,
2975  to signal to the main handler that everything was committed as atomically.
2976 
2977  @see inplace_alter_handler_ctx for information about object lifecycle.
2978  */
2980 
2981  /**
2982  Flags describing in detail which operations the storage engine is to
2983  execute.
2984  */
2986 
2987  /**
2988  Partition_info taking into account the partition changes to be performed.
2989  Contains all partitions which are present in the old version of the table
2990  with partitions to be dropped or changed marked as such + all partitions
2991  to be added in the new version of table marked as such.
2992  */
2994 
2995  /** true for online operation (LOCK=NONE) */
2996  bool online;
2997 
2998  /**
2999  Can be set by handler along with handler_ctx. The difference is that
3000  this flag can be used to store SE-specific in-place ALTER context in cases
3001  when constructing full-blown inplace_alter_handler_ctx descendant is
3002  inconvenient.
3003  */
3005 
3006  /**
3007  Can be set by handler to describe why a given operation cannot be done
3008  in-place (HA_ALTER_INPLACE_NOT_SUPPORTED) or why it cannot be done
3009  online (HA_ALTER_INPLACE_NO_LOCK or HA_ALTER_INPLACE_NO_LOCK_AFTER_PREPARE)
3010  If set, it will be used with ER_ALTER_OPERATION_NOT_SUPPORTED_REASON if
3011  results from handler::check_if_supported_inplace_alter() doesn't match
3012  requirements set by user. If not set, the more generic
3013  ER_ALTER_OPERATION_NOT_SUPPORTED will be used.
3014 
3015  Please set to a properly localized string, for example using
3016  my_get_err_msg(), so that the error message as a whole is localized.
3017  */
3018  const char *unsupported_reason;
3019 
3021  Alter_info *alter_info_arg, bool error_if_not_empty_arg,
3022  KEY *key_info_arg, uint key_count_arg,
3023  partition_info *modified_part_info_arg)
3024  : create_info(create_info_arg),
3025  alter_info(alter_info_arg),
3026  error_if_not_empty(error_if_not_empty_arg),
3027  key_info_buffer(key_info_arg),
3028  key_count(key_count_arg),
3029  index_drop_count(0),
3031  index_add_count(0),
3033  index_rename_count(0),
3036  handler_ctx(NULL),
3038  handler_flags(0),
3039  modified_part_info(modified_part_info_arg),
3040  online(false),
3043 
3045 
3046  /**
3047  Used after check_if_supported_inplace_alter() to report
3048  error if the result does not match the LOCK/ALGORITHM
3049  requirements set by the user.
3050 
3051  @param not_supported Part of statement that was not supported.
3052  @param try_instead Suggestion as to what the user should
3053  replace not_supported with.
3054  */
3055  void report_unsupported_error(const char *not_supported,
3056  const char *try_instead);
3057 
3058  /** Add old and new version of key to array of indexes to be renamed. */
3059  void add_renamed_key(KEY *old_key, KEY *new_key) {
3061  key_pair->old_key = old_key;
3062  key_pair->new_key = new_key;
3063  DBUG_PRINT("info",
3064  ("index renamed: '%s' to '%s'", old_key->name, new_key->name));
3065  }
3066 
3067  void add_altered_index_visibility(KEY *old_key, KEY *new_key) {
3068  KEY_PAIR *key_pair =
3070  key_pair->old_key = old_key;
3071  key_pair->new_key = new_key;
3072  DBUG_PRINT("info", ("index had visibility altered: %i to %i",
3073  old_key->is_visible, new_key->is_visible));
3074  }
3075 
3076  /**
3077  Add old and new version of modified key to arrays of indexes to
3078  be dropped and added (correspondingly).
3079  */
3080  void add_modified_key(KEY *old_key, KEY *new_key) {
3081  index_drop_buffer[index_drop_count++] = old_key;
3083  DBUG_PRINT("info", ("index changed: '%s'", old_key->name));
3084  }
3085 
3086  /** Drop key to array of indexes to be dropped. */
3087  void add_dropped_key(KEY *old_key) {
3088  index_drop_buffer[index_drop_count++] = old_key;
3089  DBUG_PRINT("info", ("index dropped: '%s'", old_key->name));
3090  }
3091 
3092  /** Add key to array of indexes to be added. */
3093  void add_added_key(KEY *new_key) {
3095  DBUG_PRINT("info", ("index added: '%s'", new_key->name));
3096  }
3097 };
3098 
3100  HA_CHECK_OPT() {} /* Remove gcc warning */
3101  uint flags; /* isam layer flags (e.g. for myisamchk) */
3102  uint sql_flags; /* sql layer flags - for something myisamchk cannot do */
3103  KEY_CACHE *key_cache; /* new key cache when changing key cache */
3104  void init();
3105 };
3106 
3107 /*
3108  This is a buffer area that the handler can use to store rows.
3109  'end_of_used_area' should be kept updated after calls to
3110  read-functions so that other parts of the code can use the
3111  remaining area (until next read calls is issued).
3112 */
3113 
3115  uchar *buffer; /* Buffer one can start using */
3116  uchar *buffer_end; /* End of buffer */
3117  uchar *end_of_used_area; /* End of area that was used by handler */
3118 };
3119 
3120 typedef void *range_seq_t;
3121 
3123  /*
3124  Initialize the traversal of range sequence
3125 
3126  SYNOPSIS
3127  init()
3128  init_params The seq_init_param parameter
3129  n_ranges The number of ranges obtained
3130  flags A combination of HA_MRR_SINGLE_POINT, HA_MRR_FIXED_KEY
3131 
3132  RETURN
3133  An opaque value to be used as RANGE_SEQ_IF::next() parameter
3134  */
3135  range_seq_t (*init)(void *init_params, uint n_ranges, uint flags);
3136 
3137  /*
3138  Get the next range in the range sequence
3139 
3140  SYNOPSIS
3141  next()
3142  seq The value returned by RANGE_SEQ_IF::init()
3143  range OUT Information about the next range
3144 
3145  RETURN
3146  0 - Ok, the range structure filled with info about the next range
3147  1 - No more ranges
3148  */
3150 
3151  /*
3152  Check whether range_info orders to skip the next record
3153 
3154  SYNOPSIS
3155  skip_record()
3156  seq The value returned by RANGE_SEQ_IF::init()
3157  range_info Information about the next range
3158  (Ignored if MRR_NO_ASSOCIATION is set)
3159  rowid Rowid of the record to be checked (ignored if set to 0)
3160 
3161  RETURN
3162  1 - Record with this range_info and/or this rowid shall be filtered
3163  out from the stream of records returned by ha_multi_range_read_next()
3164  0 - The record shall be left in the stream
3165  */
3166  bool (*skip_record)(range_seq_t seq, char *range_info, uchar *rowid);
3167 
3168  /*
3169  Check if the record combination matches the index condition
3170  SYNOPSIS
3171  skip_index_tuple()
3172  seq The value returned by RANGE_SEQ_IF::init()
3173  range_info Information about the next range
3174 
3175  RETURN
3176  0 - The record combination satisfies the index condition
3177  1 - Otherwise
3178  */
3179  bool (*skip_index_tuple)(range_seq_t seq, char *range_info);
3180 };
3181 
3182 /**
3183  Used to store optimizer cost estimates.
3184 
3185  The class consists of PODs only: default operator=, copy constructor
3186  and destructor are used.
3187  */
3189  private:
3190  double io_cost; ///< cost of I/O operations
3191  double cpu_cost; ///< cost of CPU operations
3192  double import_cost; ///< cost of remote operations
3193  double mem_cost; ///< memory used (bytes)
3194 
3195  public:
3197 
3198  /// Returns sum of time-consuming costs, i.e., not counting memory cost
3199  double total_cost() const { return io_cost + cpu_cost + import_cost; }
3200  double get_io_cost() const { return io_cost; }
3201  double get_cpu_cost() const { return cpu_cost; }
3202  double get_import_cost() const { return import_cost; }
3203  double get_mem_cost() const { return mem_cost; }
3204 
3205  /**
3206  Whether or not all costs in the object are zero
3207 
3208  @return true if all costs are zero, false otherwise
3209  */
3210  bool is_zero() const {
3211  return !(io_cost || cpu_cost || import_cost || mem_cost);
3212  }
3213  /**
3214  Whether or not the total cost is the maximal double
3215 
3216  @return true if total cost is the maximal double, false otherwise
3217  */
3218  bool is_max_cost() const { return io_cost == DBL_MAX; }
3219  /// Reset all costs to zero
3221  /// Set current cost to the maximal double
3222  void set_max_cost() {
3223  reset();
3224  io_cost = DBL_MAX;
3225  }
3226 
3227  /// Multiply io, cpu and import costs by parameter
3228  void multiply(double m) {
3230 
3231  io_cost *= m;
3232  cpu_cost *= m;
3233  import_cost *= m;
3234  /* Don't multiply mem_cost */
3235  }
3236 
3238  DBUG_ASSERT(!is_max_cost() && !other.is_max_cost());
3239 
3240  io_cost += other.io_cost;
3241  cpu_cost += other.cpu_cost;
3242  import_cost += other.import_cost;
3243  mem_cost += other.mem_cost;
3244 
3245  return *this;
3246  }
3247 
3249  Cost_estimate result = *this;
3250  result += other;
3251 
3252  return result;
3253  }
3254 
3256  Cost_estimate result;
3257 
3258  DBUG_ASSERT(!other.is_max_cost());
3259 
3260  result.io_cost = io_cost - other.io_cost;
3261  result.cpu_cost = cpu_cost - other.cpu_cost;
3262  result.import_cost = import_cost - other.import_cost;
3263  result.mem_cost = mem_cost - other.mem_cost;
3264  return result;
3265  }
3266 
3267  bool operator>(const Cost_estimate &other) const {
3268  return total_cost() > other.total_cost() ? true : false;
3269  }
3270 
3271  bool operator<(const Cost_estimate &other) const {
3272  return other > *this ? true : false;
3273  }
3274 
3275  /// Add to IO cost
3276  void add_io(double add_io_cost) {
3278  io_cost += add_io_cost;
3279  }
3280 
3281  /// Add to CPU cost
3282  void add_cpu(double add_cpu_cost) {
3284  cpu_cost += add_cpu_cost;
3285  }
3286 
3287  /// Add to import cost
3288  void add_import(double add_import_cost) {
3290  import_cost += add_import_cost;
3291  }
3292 
3293  /// Add to memory cost
3294  void add_mem(double add_mem_cost) {
3296  mem_cost += add_mem_cost;
3297  }
3298 };
3299 
3300 void get_sweep_read_cost(TABLE *table, ha_rows nrows, bool interrupted,
3301  Cost_estimate *cost);
3302 
3303 /*
3304  The below two are not used (and not handled) in this milestone of this WL
3305  entry because there seems to be no use for them at this stage of
3306  implementation.
3307 */
3308 #define HA_MRR_SINGLE_POINT 1
3309 #define HA_MRR_FIXED_KEY 2
3310 
3311 /*
3312  Indicates that RANGE_SEQ_IF::next(&range) doesn't need to fill in the
3313  'range' parameter.
3314 */
3315 #define HA_MRR_NO_ASSOCIATION 4
3316 
3317 /*
3318  The MRR user will provide ranges in key order, and MRR implementation
3319  must return rows in key order.
3320  Passing this flag to multi_read_range_init() may cause the
3321  default MRR handler to be used even if HA_MRR_USE_DEFAULT_IMPL
3322  was not specified.
3323  (If the native MRR impl. can not provide SORTED result)
3324 */
3325 #define HA_MRR_SORTED 8
3326 
3327 /* MRR implementation doesn't have to retrieve full records */
3328 #define HA_MRR_INDEX_ONLY 16
3329 
3330 /*
3331  The passed memory buffer is of maximum possible size, the caller can't
3332  assume larger buffer.
3333 */
3334 #define HA_MRR_LIMITS 32
3335 
3336 /*
3337  Flag set <=> default MRR implementation is used
3338  (The choice is made by **_info[_const]() function which may set this
3339  flag. SQL layer remembers the flag value and then passes it to
3340  multi_read_range_init().
3341 */
3342 #define HA_MRR_USE_DEFAULT_IMPL 64
3343 
3344 /*
3345  Used only as parameter to multi_range_read_info():
3346  Flag set <=> the caller guarantees that the bounds of the scanned ranges
3347  will not have NULL values.
3348 */
3349 #define HA_MRR_NO_NULL_ENDPOINTS 128
3350 
3351 /*
3352  Set by the MRR implementation to signal that it will natively
3353  produced sorted result if multi_range_read_init() is called with
3354  the HA_MRR_SORTED flag - Else multi_range_read_init(HA_MRR_SORTED)
3355  will revert to use the default MRR implementation.
3356 */
3357 #define HA_MRR_SUPPORT_SORTED 256
3358 
3360  public:
3361  ulonglong data_file_length; /* Length off data file */
3362  ulonglong max_data_file_length; /* Length off data file */
3365  ulonglong delete_length; /* Free bytes */
3367  /*
3368  The number of records in the table.
3369  0 - means the table has exactly 0 rows
3370  other - if (table_flags() & HA_STATS_RECORDS_IS_EXACT)
3371  the value is the exact number of records in the table
3372  else
3373  it is an estimate
3374  */
3376  ha_rows deleted; /* Deleted records */
3377  ulong mean_rec_length; /* physical reclength */
3378  /* TODO: create_time should be retrieved from the new DD. Remove this. */
3379  time_t create_time; /* When table was created */
3382  uint block_size; /* index block size */
3383 
3384  /*
3385  number of buffer bytes that native mrr implementation needs,
3386  */
3388 
3389  /**
3390  Estimate for how much of the table that is availabe in a memory
3391  buffer. Valid range is [0..1]. If it has the special value
3392  IN_MEMORY_ESTIMATE_UNKNOWN (defined in structs.h), it means that
3393  the storage engine has not supplied any value for it.
3394  */
3396 
3398  : data_file_length(0),
3400  index_file_length(0),
3401  delete_length(0),
3403  records(0),
3404  deleted(0),
3405  mean_rec_length(0),
3406  create_time(0),
3407  check_time(0),
3408  update_time(0),
3409  block_size(0),
3411 };
3412 
3413 /**
3414  Calculates length of key.
3415 
3416  Given a key index and a map of key parts return length of buffer used by key
3417  parts.
3418 
3419  @param table Table containing the key
3420  @param key Key index
3421  @param keypart_map which key parts that is used
3422 
3423  @return Length of used key parts.
3424 */
3425 uint calculate_key_len(TABLE *table, uint key, key_part_map keypart_map);
3426 /*
3427  bitmap with first N+1 bits set
3428  (keypart_map for a key prefix of [0..N] keyparts)
3429 */
3430 #define make_keypart_map(N) (((key_part_map)2 << (N)) - 1)
3431 /*
3432  bitmap with first N bits set
3433  (keypart_map for a key prefix of [0..N-1] keyparts)
3434 */
3435 #define make_prev_keypart_map(N) (((key_part_map)1 << (N)) - 1)
3436 
3437 /** Base class to be used by handlers different shares */
3439  public:
3441  virtual ~Handler_share() {}
3442 };
3443 
3444 /**
3445  Wrapper for struct ft_hints.
3446 */
3447 
3448 class Ft_hints {
3449  private:
3450  struct ft_hints hints;
3451 
3452  public:
3453  Ft_hints(uint ft_flags) {
3454  hints.flags = ft_flags;
3456  hints.op_value = 0.0;
3458  }
3459 
3460  /**
3461  Set comparison operation type and and value for master MATCH function.
3462 
3463  @param type comparison operation type
3464  @param value comparison operation value
3465  */
3466  void set_hint_op(enum ft_operation type, double value) {
3467  hints.op_type = type;
3468  hints.op_value = value;
3469  }
3470 
3471  /**
3472  Set Ft_hints flag.
3473 
3474  @param ft_flag Ft_hints flag
3475  */
3476  void set_hint_flag(uint ft_flag) { hints.flags |= ft_flag; }
3477 
3478  /**
3479  Set Ft_hints limit.
3480 
3481  @param ft_limit limit
3482  */
3483  void set_hint_limit(ha_rows ft_limit) { hints.limit = ft_limit; }
3484 
3485  /**
3486  Get Ft_hints limit.
3487 
3488  @return Ft_hints limit
3489  */
3491 
3492  /**
3493  Get Ft_hints operation value.
3494 
3495  @return operation value
3496  */
3497  double get_op_value() { return hints.op_value; }
3498 
3499  /**
3500  Get Ft_hints operation type.
3501 
3502  @return operation type
3503  */
3505 
3506  /**
3507  Get Ft_hints flags.
3508 
3509  @return Ft_hints flags
3510  */
3511  uint get_flags() { return hints.flags; }
3512 
3513  /**
3514  Get ft_hints struct.
3515 
3516  @return pointer to ft_hints struct
3517  */
3518  struct ft_hints *get_hints() {
3519  return &hints;
3520  }
3521 };
3522 
3523 /**
3524  The handler class is the interface for dynamically loadable
3525  storage engines. Do not add ifdefs and take care when adding or
3526  changing virtual functions to avoid vtable confusion
3527 
3528  Functions in this class accept and return table columns data. Two data
3529  representation formats are used:
3530  1. TableRecordFormat - Used to pass [partial] table records to/from
3531  storage engine
3532 
3533  2. KeyTupleFormat - used to pass index search tuples (aka "keys") to
3534  storage engine. See opt_range.cc for description of this format.
3535 
3536  TableRecordFormat
3537  =================
3538  [Warning: this description is work in progress and may be incomplete]
3539  The table record is stored in a fixed-size buffer:
3540 
3541  record: null_bytes, column1_data, column2_data, ...
3542 
3543  The offsets of the parts of the buffer are also fixed: every column has
3544  an offset to its column{i}_data, and if it is nullable it also has its own
3545  bit in null_bytes.
3546 
3547  The record buffer only includes data about columns that are marked in the
3548  relevant column set (table->read_set and/or table->write_set, depending on
3549  the situation).
3550  <not-sure>It could be that it is required that null bits of non-present
3551  columns are set to 1</not-sure>
3552 
3553  VARIOUS EXCEPTIONS AND SPECIAL CASES
3554 
3555  If the table has no nullable columns, then null_bytes is still
3556  present, its length is one byte <not-sure> which must be set to 0xFF
3557  at all times. </not-sure>
3558 
3559  If the table has columns of type BIT, then certain bits from those columns
3560  may be stored in null_bytes as well. Grep around for Field_bit for
3561  details.
3562 
3563  For blob columns (see Field_blob), the record buffer stores length of the
3564  data, following by memory pointer to the blob data. The pointer is owned
3565  by the storage engine and is valid until the next operation.
3566 
3567  If a blob column has NULL value, then its length and blob data pointer
3568  must be set to 0.
3569 
3570 
3571  Overview of main modules of the handler API
3572  ===========================================
3573  The overview below was copied from the storage/partition/ha_partition.h when
3574  support for non-native partitioning was removed.
3575 
3576  -------------------------------------------------------------------------
3577  MODULE create/delete handler object
3578  -------------------------------------------------------------------------
3579  Object create/delete method. Normally called when a table object
3580  exists.
3581 
3582  -------------------------------------------------------------------------
3583  MODULE meta data changes
3584  -------------------------------------------------------------------------
3585  Meta data routines to CREATE, DROP, RENAME table are often used at
3586  ALTER TABLE (update_create_info used from ALTER TABLE and SHOW ..).
3587 
3588  Methods:
3589  delete_table()
3590  rename_table()
3591  create()
3592  update_create_info()
3593 
3594  -------------------------------------------------------------------------
3595  MODULE open/close object
3596  -------------------------------------------------------------------------
3597  Open and close handler object to ensure all underlying files and
3598  objects allocated and deallocated for query handling is handled
3599  properly.
3600 
3601  A handler object is opened as part of its initialisation and before
3602  being used for normal queries (not before meta-data changes always.
3603  If the object was opened it will also be closed before being deleted.
3604 
3605  Methods:
3606  open()
3607  close()
3608 
3609  -------------------------------------------------------------------------
3610  MODULE start/end statement
3611  -------------------------------------------------------------------------
3612  This module contains methods that are used to understand start/end of
3613  statements, transaction boundaries, and aid for proper concurrency
3614  control.
3615 
3616  Methods:
3617  store_lock()
3618  external_lock()
3619  start_stmt()
3620  lock_count()
3621  unlock_row()
3622  was_semi_consistent_read()
3623  try_semi_consistent_read()
3624 
3625  -------------------------------------------------------------------------
3626  MODULE change record
3627  -------------------------------------------------------------------------
3628  This part of the handler interface is used to change the records
3629  after INSERT, DELETE, UPDATE, REPLACE method calls but also other
3630  special meta-data operations as ALTER TABLE, LOAD DATA, TRUNCATE.
3631 
3632  These methods are used for insert (write_row), update (update_row)
3633  and delete (delete_row). All methods to change data always work on
3634  one row at a time. update_row and delete_row also contains the old
3635  row.
3636  delete_all_rows will delete all rows in the table in one call as a
3637  special optimization for DELETE from table;
3638 
3639  Bulk inserts are supported if all underlying handlers support it.
3640  start_bulk_insert and end_bulk_insert is called before and after a
3641  number of calls to write_row.
3642 
3643  Methods:
3644  write_row()
3645  update_row()
3646  delete_row()
3647  delete_all_rows()
3648  start_bulk_insert()
3649  end_bulk_insert()
3650 
3651  -------------------------------------------------------------------------
3652  MODULE full table scan
3653  -------------------------------------------------------------------------
3654  This module is used for the most basic access method for any table
3655  handler. This is to fetch all data through a full table scan. No
3656  indexes are needed to implement this part.
3657  It contains one method to start the scan (rnd_init) that can also be
3658  called multiple times (typical in a nested loop join). Then proceeding
3659  to the next record (rnd_next) and closing the scan (rnd_end).
3660  To remember a record for later access there is a method (position)
3661  and there is a method used to retrieve the record based on the stored
3662  position.
3663  The position can be a file position, a primary key, a ROWID dependent
3664  on the handler below.
3665 
3666  All functions that retrieve records and are callable through the
3667  handler interface must indicate whether a record is present after the call
3668  or not. Record found is indicated by returning 0 and setting table status
3669  to "has row". Record not found is indicated by returning a non-zero value
3670  and setting table status to "no row".
3671  @see TABLE::set_found_row() and TABLE::set_no_row().
3672  By enforcing these rules in the handler interface, storage handler functions
3673  need not set any status in struct TABLE. These notes also apply to module
3674  index scan, documented below.
3675 
3676  Methods:
3677 
3678  rnd_init()
3679  rnd_end()
3680  rnd_next()
3681  rnd_pos()
3682  rnd_pos_by_record()
3683  position()
3684 
3685  -------------------------------------------------------------------------
3686  MODULE index scan
3687  -------------------------------------------------------------------------
3688  This part of the handler interface is used to perform access through
3689  indexes. The interface is defined as a scan interface but the handler
3690  can also use key lookup if the index is a unique index or a primary
3691  key index.
3692  Index scans are mostly useful for SELECT queries but are an important
3693  part also of UPDATE, DELETE, REPLACE and CREATE TABLE table AS SELECT
3694  and so forth.
3695  Naturally an index is needed for an index scan and indexes can either
3696  be ordered, hash based. Some ordered indexes can return data in order
3697  but not necessarily all of them.
3698  There are many flags that define the behavior of indexes in the
3699  various handlers. These methods are found in the optimizer module.
3700 
3701  index_read is called to start a scan of an index. The find_flag defines
3702  the semantics of the scan. These flags are defined in
3703  include/my_base.h
3704  index_read_idx is the same but also initializes index before calling doing
3705  the same thing as index_read. Thus it is similar to index_init followed
3706  by index_read. This is also how we implement it.
3707 
3708  index_read/index_read_idx does also return the first row. Thus for
3709  key lookups, the index_read will be the only call to the handler in
3710  the index scan.
3711 
3712  index_init initializes an index before using it and index_end does
3713  any end processing needed.
3714 
3715  Methods:
3716  index_read_map()
3717  index_init()
3718  index_end()
3719  index_read_idx_map()
3720  index_next()
3721  index_prev()
3722  index_first()
3723  index_last()
3724  index_next_same()
3725  index_read_last_map()
3726  read_range_first()
3727  read_range_next()
3728 
3729  -------------------------------------------------------------------------
3730  MODULE information calls
3731  -------------------------------------------------------------------------
3732  This calls are used to inform the handler of specifics of the ongoing
3733  scans and other actions. Most of these are used for optimisation
3734  purposes.
3735 
3736  Methods:
3737  info()
3738  get_dynamic_partition_info
3739  extra()
3740  extra_opt()
3741  reset()
3742 
3743  -------------------------------------------------------------------------
3744  MODULE optimizer support
3745  -------------------------------------------------------------------------
3746  NOTE:
3747  One important part of the public handler interface that is not depicted in
3748  the methods is the attribute records which is defined in the base class.
3749  This is looked upon directly and is set by calling info(HA_STATUS_INFO) ?
3750 
3751  Methods:
3752  min_rows_for_estimate()
3753  get_biggest_used_partition()
3754  scan_time()
3755  read_time()
3756  records_in_range()
3757  estimate_rows_upper_bound()
3758  records()
3759 
3760  -------------------------------------------------------------------------
3761  MODULE print messages
3762  -------------------------------------------------------------------------
3763  This module contains various methods that returns text messages for
3764  table types, index type and error messages.
3765 
3766  Methods:
3767  table_type()
3768  get_row_type()
3769  print_error()
3770  get_error_message()
3771 
3772  -------------------------------------------------------------------------
3773  MODULE handler characteristics
3774  -------------------------------------------------------------------------
3775  This module contains a number of methods defining limitations and
3776  characteristics of the handler (see also documentation regarding the
3777  individual flags).
3778 
3779  Methods:
3780  table_flags()
3781  index_flags()
3782  min_of_the_max_uint()
3783  max_supported_record_length()
3784  max_supported_keys()
3785  max_supported_key_parts()
3786  max_supported_key_length()
3787  max_supported_key_part_length()
3788  low_byte_first()
3789  extra_rec_buf_length()
3790  min_record_length(uint options)
3791  primary_key_is_clustered()
3792  ha_key_alg get_default_index_algorithm()
3793  is_index_algorithm_supported()
3794 
3795  -------------------------------------------------------------------------
3796  MODULE compare records
3797  -------------------------------------------------------------------------
3798  cmp_ref checks if two references are the same. For most handlers this is
3799  a simple memcmp of the reference. However some handlers use primary key
3800  as reference and this can be the same even if memcmp says they are
3801  different. This is due to character sets and end spaces and so forth.
3802 
3803  Methods:
3804  cmp_ref()
3805 
3806  -------------------------------------------------------------------------
3807  MODULE auto increment
3808  -------------------------------------------------------------------------
3809  This module is used to handle the support of auto increments.
3810 
3811  This variable in the handler is used as part of the handler interface
3812  It is maintained by the parent handler object and should not be
3813  touched by child handler objects (see handler.cc for its use).
3814 
3815  Methods:
3816  get_auto_increment()
3817  release_auto_increment()
3818 
3819  -------------------------------------------------------------------------
3820  MODULE initialize handler for HANDLER call
3821  -------------------------------------------------------------------------
3822  This method is a special InnoDB method called before a HANDLER query.
3823 
3824  Methods:
3825  init_table_handle_for_HANDLER()
3826 
3827  -------------------------------------------------------------------------
3828  MODULE foreign key support
3829  -------------------------------------------------------------------------
3830  The following methods are used to implement foreign keys as supported by
3831  InnoDB and NDB.
3832  get_foreign_key_create_info is used by SHOW CREATE TABLE to get a textual
3833  description of how the CREATE TABLE part to define FOREIGN KEY's is done.
3834  free_foreign_key_create_info is used to free the memory area that provided
3835  this description.
3836 
3837  Methods:
3838  get_parent_foreign_key_list()
3839  get_foreign_key_create_info()
3840  free_foreign_key_create_info()
3841  get_foreign_key_list()
3842  referenced_by_foreign_key()
3843 
3844  -------------------------------------------------------------------------
3845  MODULE fulltext index
3846  -------------------------------------------------------------------------
3847  Fulltext index support.
3848 
3849  Methods:
3850  ft_init_ext_with_hints()
3851  ft_init()
3852  ft_init_ext()
3853  ft_read()
3854 
3855  -------------------------------------------------------------------------
3856  MODULE in-place ALTER TABLE
3857  -------------------------------------------------------------------------
3858  Methods for in-place ALTER TABLE support (implemented by InnoDB and NDB).
3859 
3860  Methods:
3861  check_if_supported_inplace_alter()
3862  prepare_inplace_alter_table()
3863  inplace_alter_table()
3864  commit_inplace_alter_table()
3865  notify_table_changed()
3866 
3867  -------------------------------------------------------------------------
3868  MODULE tablespace support
3869  -------------------------------------------------------------------------
3870  Methods:
3871  discard_or_import_tablespace()
3872 
3873  -------------------------------------------------------------------------
3874  MODULE administrative DDL
3875  -------------------------------------------------------------------------
3876  Methods:
3877  optimize()
3878  analyze()
3879  check()
3880  repair()
3881  check_and_repair()
3882  auto_repair()
3883  is_crashed()
3884  check_for_upgrade()
3885  checksum()
3886  assign_to_keycache()
3887 
3888  -------------------------------------------------------------------------
3889  MODULE enable/disable indexes
3890  -------------------------------------------------------------------------
3891  Enable/Disable Indexes are only supported by HEAP and MyISAM.
3892 
3893  Methods:
3894  disable_indexes()
3895  enable_indexes()
3896  indexes_are_disabled()
3897 
3898  -------------------------------------------------------------------------
3899  MODULE append_create_info
3900  -------------------------------------------------------------------------
3901  Only used by MyISAM MERGE tables.
3902 
3903  Methods:
3904  append_create_info()
3905 
3906  -------------------------------------------------------------------------
3907  MODULE partitioning specific handler API
3908  -------------------------------------------------------------------------
3909  Methods:
3910  get_partition_handler()
3911 */
3912 
3913 class handler {
3914  friend class Partition_handler;
3915 
3916  public:
3918 
3919  protected:
3920  TABLE_SHARE *table_share; /* The table definition */
3921  TABLE *table; /* The current open table */
3922  Table_flags cached_table_flags; /* Set on init() and open() */
3923 
3925 
3926  public:
3927  handlerton *ht; /* storage engine of this handler */
3928  /** Pointer to current row */
3930  /** Pointer to duplicate row */
3932 
3934 
3935  /* MultiRangeRead-related members: */
3936  range_seq_t mrr_iter; /* Interator to traverse the range sequence */
3937  RANGE_SEQ_IF mrr_funcs; /* Range sequence traversal functions */
3938  HANDLER_BUFFER *multi_range_buffer; /* MRR buffer info */
3939  uint ranges_in_seq; /* Total number of ranges in the traversed sequence */
3940  /* true <=> source MRR ranges and the output are ordered */
3942 
3943  /* true <=> we're currently traversing a range in mrr_cur_range. */
3945  /* Current range (the one we're now returning rows from) */
3947 
3948  /*
3949  The direction of the current range or index scan. This is used by
3950  the ICP implementation to determine if it has reached the end
3951  of the current range.
3952  */
3954 
3955  private:
3956  Record_buffer *m_record_buffer = nullptr; ///< Buffer for multi-row reads.
3957  /*
3958  Storage space for the end range value. Should only be accessed using
3959  the end_range pointer. The content is invalid when end_range is NULL.
3960  */
3964 
3965  /**
3966  Pointer to the handler of the table in the primary storage engine,
3967  if this handler represents a table in a secondary storage engine.
3968  */
3970 
3971  protected:
3973  bool eq_range;
3974  /*
3975  true <=> the engine guarantees that returned records are within the range
3976  being scanned.
3977  */
3979 
3980  public:
3981  /**
3982  End value for a range scan. If this is NULL the range scan has no
3983  end value. Should also be NULL when there is no ongoing range scan.
3984  Used by the read_range() functions and also evaluated by pushed
3985  index conditions.
3986  */
3988  /**
3989  Flag which tells if #end_range contains a virtual generated column.
3990  The content is invalid when #end_range is @c nullptr.
3991  */
3993  uint errkey; /* Last dup key */
3996  /** Length of ref (1-8 or the clustered key length) */
3999  enum { NONE = 0, INDEX, RND, SAMPLING } inited;
4000  bool implicit_emptied; /* Can be !=0 only if HEAP */
4002 
4004  uint pushed_idx_cond_keyno; /* The index which the above condition is for */
4005 
4006  /**
4007  next_insert_id is the next value which should be inserted into the
4008  auto_increment column: in a inserting-multi-row statement (like INSERT
4009  SELECT), for the first row where the autoinc value is not specified by the
4010  statement, get_auto_increment() called and asked to generate a value,
4011  next_insert_id is set to the next value, then for all other rows
4012  next_insert_id is used (and increased each time) without calling
4013  get_auto_increment().
4014  */
4016  /**
4017  insert id for the current row (*autogenerated*; if not
4018  autogenerated, it's 0).
4019  At first successful insertion, this variable is stored into
4020  THD::first_successful_insert_id_in_cur_stmt.
4021  */
4023  /**
4024  Interval returned by get_auto_increment() and being consumed by the
4025  inserter.
4026  */
4028  /**
4029  Number of reserved auto-increment intervals. Serves as a heuristic
4030  when we have no estimation of how many records the statement will insert:
4031  the more intervals we have reserved, the bigger the next one. Reset in
4032  handler::ha_release_auto_increment().
4033  */
4035 
4036  /**
4037  Instrumented table associated with this handler.
4038  */
4040 
4043 
4044  private:
4045  /** Internal state of the batch instrumentation. */
4047  /** Batch mode not used. */
4049  /** Batch mode used, before first table io. */
4051  /** Batch mode used, after first table io. */
4053  };
4054  /**
4055  Batch mode state.
4056  @sa start_psi_batch_mode.
4057  @sa end_psi_batch_mode.
4058  */
4060  /**
4061  The number of rows in the batch.
4062  @sa start_psi_batch_mode.
4063  @sa end_psi_batch_mode.
4064  */
4066  /**
4067  The current event in a batch.
4068  @sa start_psi_batch_mode.
4069  @sa end_psi_batch_mode.
4070  */
4072  /**
4073  Storage for the event in a batch.
4074  @sa start_psi_batch_mode.
4075  @sa end_psi_batch_mode.
4076  */
4078 
4079  public:
4080  void unbind_psi();
4081  void rebind_psi();
4082  /**
4083  Put the handler in 'batch' mode when collecting
4084  table io instrumented events.
4085  When operating in batch mode:
4086  - a single start event is generated in the performance schema.
4087  - all table io performed between @c start_psi_batch_mode
4088  and @c end_psi_batch_mode is not instrumented:
4089  the number of rows affected is counted instead in @c m_psi_numrows.
4090  - a single end event is generated in the performance schema
4091  when the batch mode ends with @c end_psi_batch_mode.
4092  */
4093  void start_psi_batch_mode();
4094  /** End a batch started with @c start_psi_batch_mode. */
4095  void end_psi_batch_mode();
4096  /**
4097  If a PSI batch was started, turn if off.
4098  @returns true if it was started.
4099  */
4101  bool rc = m_psi_batch_mode;
4102  if (rc) end_psi_batch_mode();
4103  return rc;
4104  }
4105 
4106  private:
4107  /**
4108  The lock type set by when calling::ha_external_lock(). This is
4109  propagated down to the storage engine. The reason for also storing
4110  it here, is that when doing MRR we need to create/clone a second handler
4111  object. This cloned handler object needs to know about the lock_type used.
4112  */
4114  /**
4115  Pointer where to store/retrieve the Handler_share pointer.
4116  For non partitioned handlers this is &TABLE_SHARE::ha_share.
4117  */
4119 
4120  /**
4121  Some non-virtual ha_* functions, responsible for reading rows,
4122  like ha_rnd_pos(), must ensure that virtual generated columns are
4123  calculated before they return. For that, they should set this
4124  member to true at their start, and check it before they return: if
4125  the member is still true, it means they should calculate; if it's
4126  false, it means the calculation has been done by some called
4127  lower-level function and does not need to be re-done (which is why
4128  we need this status flag: to avoid redundant calculations, for
4129  performance).
4130  */
4132 
4133  public:
4134  handler(handlerton *ht_arg, TABLE_SHARE *share_arg)
4135  : table_share(share_arg),
4136  table(0),
4138  ht(ht_arg),
4139  ref(0),
4142  end_range(NULL),
4145  ref_length(sizeof(my_off_t)),
4146  ft_handler(0),
4147  inited(NONE),
4148  implicit_emptied(0),
4149  pushed_cond(0),
4152  next_insert_id(0),
4155  m_psi(NULL),
4157  m_psi_numrows(0),
4158  m_psi_locker(NULL),
4159  m_lock_type(F_UNLCK),
4160  ha_share(NULL),
4162  DBUG_PRINT("info", ("handler created F_UNLCK %d F_RDLCK %d F_WRLCK %d",
4163  F_UNLCK, F_RDLCK, F_WRLCK));
4164  }
4165 
4166  virtual ~handler(void) {
4167  DBUG_ASSERT(m_psi == NULL);
4170  DBUG_ASSERT(m_lock_type == F_UNLCK);
4171  DBUG_ASSERT(inited == NONE);
4172  }
4173 
4174  /*
4175  @todo reorganize functions, make proper public/protected/private qualifiers
4176  */
4177  virtual handler *clone(const char *name, MEM_ROOT *mem_root);
4178  /** This is called after create to allow us to set up cached variables */
4180  /* ha_ methods: public wrappers for private virtual API */
4181 
4182  /**
4183  Set a record buffer that the storage engine can use for multi-row reads.
4184  The buffer has to be provided prior to the first read from an index or a
4185  table.
4186 
4187  @param buffer the buffer to use for multi-row reads
4188  */
4190 
4191  /**
4192  Get the record buffer that was set with ha_set_record_buffer().
4193 
4194  @return the buffer to use for multi-row reads, or nullptr if there is none
4195  */
4197 
4198  /**
4199  Does this handler want to get a Record_buffer for multi-row reads
4200  via the ha_set_record_buffer() function? And if so, what is the
4201  maximum number of records to allocate space for in the buffer?
4202 
4203  Storage engines that support using a Record_buffer should override
4204  handler::is_record_buffer_wanted().
4205 
4206  @param[out] max_rows gets set to the maximum number of records to
4207  allocate space for in the buffer if the function
4208  returns true
4209 
4210  @retval true if the handler would like a Record_buffer
4211  @retval false if the handler does not want a Record_buffer
4212  */
4213  bool ha_is_record_buffer_wanted(ha_rows *const max_rows) const {
4214  return is_record_buffer_wanted(max_rows);
4215  }
4216 
4217  int ha_open(TABLE *table, const char *name, int mode, int test_if_locked,
4218  const dd::Table *table_def);
4219  int ha_close(void);
4220  int ha_index_init(uint idx, bool sorted);
4221  int ha_index_end();
4222  int ha_rnd_init(bool scan);
4223  int ha_rnd_end();
4224  int ha_rnd_next(uchar *buf);
4225  int ha_rnd_pos(uchar *buf, uchar *pos);
4226  int ha_index_read_map(uchar *buf, const uchar *key, key_part_map keypart_map,
4227  enum ha_rkey_function find_flag);
4228  int ha_index_read_last_map(uchar *buf, const uchar *key,
4229  key_part_map keypart_map);
4230  int ha_index_read_idx_map(uchar *buf, uint index, const uchar *key,
4231  key_part_map keypart_map,
4232  enum ha_rkey_function find_flag);
4233  int ha_index_next(uchar *buf);
4234  int ha_index_prev(uchar *buf);
4235  int ha_index_first(uchar *buf);
4236  int ha_index_last(uchar *buf);
4237  int ha_index_next_same(uchar *buf, const uchar *key, uint keylen);
4238  int ha_reset();
4239  /* this is necessary in many places, e.g. in HANDLER command */
4241  return inited == INDEX ? ha_index_end() : inited == RND ? ha_rnd_end() : 0;
4242  }
4243  /**
4244  The cached_table_flags is set at ha_open and ha_external_lock
4245  */
4247  /**
4248  These functions represent the public interface to *users* of the
4249  handler class, hence they are *not* virtual. For the inheritance
4250  interface, see the (private) functions write_row(), update_row(),
4251  and delete_row() below.
4252  */
4253  int ha_external_lock(THD *thd, int lock_type);
4254  int ha_write_row(uchar *buf);
4255  /**
4256  Update the current row.
4257 
4258  @param old_data the old contents of the row
4259  @param new_data the new contents of the row
4260  @return error status (zero on success, HA_ERR_* error code on error)
4261  */
4262  int ha_update_row(const uchar *old_data, uchar *new_data);
4263  int ha_delete_row(const uchar *buf);
4265 
4266  int ha_check_for_upgrade(HA_CHECK_OPT *check_opt);
4267  /** to be actually called to get 'check()' functionality*/
4268  int ha_check(THD *thd, HA_CHECK_OPT *check_opt);
4269  int ha_repair(THD *thd, HA_CHECK_OPT *check_opt);
4270  void ha_start_bulk_insert(ha_rows rows);
4271  int ha_end_bulk_insert();
4272  int ha_bulk_update_row(const uchar *old_data, uchar *new_data,
4273  uint *dup_key_found);
4274  int ha_delete_all_rows();
4276  int ha_optimize(THD *thd, HA_CHECK_OPT *check_opt);
4277  int ha_analyze(THD *thd, HA_CHECK_OPT *check_opt);
4278  bool ha_check_and_repair(THD *thd);
4279  int ha_disable_indexes(uint mode);
4280  int ha_enable_indexes(uint mode);
4282  int ha_rename_table(const char *from, const char *to,
4283  const dd::Table *from_table_def, dd::Table *to_table_def);
4284  int ha_delete_table(const char *name, const dd::Table *table_def);
4285  void ha_drop_table(const char *name);
4286 
4287  int ha_create(const char *name, TABLE *form, HA_CREATE_INFO *info,
4288  dd::Table *table_def);
4289 
4290  int ha_prepare_load_table(const TABLE &table);
4291 
4292  int ha_load_table(const TABLE &table);
4293 
4294  int ha_unload_table(const char *db_name, const char *table_name);
4295 
4296  /**
4297  Initializes a parallel scan. It creates a parallel_scan_ctx that has to
4298  be used across all parallel_scan methods. Also, gets the number of
4299  threads that would be spawned for parallel scan.
4300  @return error code
4301  @retval 0 on success
4302  */
4303  virtual int pread_adapter_parallel_scan_start(void *& /* parallel_scan_ctx */,
4304  size_t & /* num_threads */) {
4305  return (0);
4306  }
4307 
4308  /**
4309  This callback is called by each parallel load thread at the beginning of
4310  the parallel load for the adapter scan.
4311  @param cookie The cookie for this thread
4312  @param ncols Number of columns in each row
4313  @param row_len The size of a row in bytes
4314  @param col_offsets An array of size ncols, where each element represents
4315  the offset of a column in the row data. The memory of
4316  this array belongs to the caller and will be free-ed
4317  after the pload_end_cbk call.
4318  @param null_byte_offsets An array of size ncols, where each element
4319  represents the offset of a column in the row data. The
4320  memory of this array belongs to the caller and will be
4321  free-ed after the pload_end_cbk call.
4322  @param null_bitmasks An array of size ncols, where each element
4323  represents the bitmask required to get the null bit. The
4324  memory of this array belongs to the caller and will be
4325  free-ed after the pload_end_cbk call.
4326  */
4327  using pread_adapter_pload_init_cbk = std::function<bool(
4328  void *cookie, ulong ncols, ulong row_len, ulong *col_offsets,
4329  ulong *null_byte_offsets, ulong *null_bitmasks)>;
4330 
4331  /**
4332  This callback is called by each parallel load thread when processing
4333  of rows is required for the adapter scan.
4334  @param[in] cookie The cookie for this thread
4335  @param[in] nrows The nrows that are available
4336  @param[in] rowdata The mysql-in-memory row data buffer. This is a memory
4337  buffer for nrows records. The length of each record
4338  is fixed and communicated via
4339  pread_adapter_pload_init_cbk.
4340  @returns true if there is an error, false otherwise.
4341  */
4343  std::function<bool(void *cookie, uint nrows, void *rowdata)>;
4344 
4345  /**
4346  This callback is called by each parallel load thread when processing
4347  of rows has ended for the adapter scan.
4348  @param[in] cookie The cookie for this thread
4349  */
4350  using pread_adapter_pload_end_cbk = std::function<void(void *cookie)>;
4351 
4352  /**
4353  Run the parallel read of data.
4354  @return error code
4355  @retval 0 on success
4356  */
4358  void * /* parallel_scan_ctx */, void ** /* thread_contexts */,
4359  pread_adapter_pload_init_cbk /* load_init_fn */,
4360  pread_adapter_pload_row_cbk /* load_rows_fn */,
4361  pread_adapter_pload_end_cbk /* load_end_fn */) {
4362  return (0);
4363  }
4364 
4365  /**
4366  Run the parallel read of data.
4367  @return error code
4368  @retval 0 on success
4369  */
4370  virtual int pread_adapter_parallel_scan_end(void * /* parallel_scan_ctx */) {
4371  return (0);
4372  }
4373 
4374  /**
4375  Submit a dd::Table object representing a core DD table having
4376  hardcoded data to be filled in by the DDSE. This function can be
4377  used for retrieving the hard coded SE private data for the
4378  mysql.dd_properties table, before creating or opening it, or for
4379  retrieving the hard coded SE private data for a core table,
4380  before creating or opening them.
4381 
4382  @param dd_table [in,out] A dd::Table object representing
4383  a core DD table.
4384  @param reset Reset counters.
4385 
4386  @retval true An error occurred.
4387  @retval false Success - no errors.
4388  */
4389 
4390  bool ha_get_se_private_data(dd::Table *dd_table, bool reset);
4391 
4393  int update_auto_increment();
4394  virtual void print_error(int error, myf errflag);
4395  virtual bool get_error_message(int error, String *buf);
4396  uint get_dup_key(int error);
4397  /**
4398  Retrieves the names of the table and the key for which there was a
4399  duplicate entry in the case of HA_ERR_FOREIGN_DUPLICATE_KEY.
4400 
4401  If any of the table or key name is not available this method will return
4402  false and will not change any of child_table_name or child_key_name.
4403 
4404  @param [out] child_table_name Table name
4405  @param [in] child_table_name_len Table name buffer size
4406  @param [out] child_key_name Key name
4407  @param [in] child_key_name_len Key name buffer size
4408 
4409  @retval true table and key names were available
4410  and were written into the corresponding
4411  out parameters.
4412  @retval false table and key names were not available,
4413  the out parameters were not touched.
4414  */
4415  virtual bool get_foreign_dup_key(char *child_table_name,
4416  uint child_table_name_len,
4417  char *child_key_name,
4418  uint child_key_name_len);
4419  /**
4420  Change the internal TABLE_SHARE pointer.
4421 
4422  @param table_arg TABLE object
4423  @param share New share to use
4424 
4425  @note Is used in error handling in ha_delete_table.
4426  */
4427 
4428  virtual void change_table_ptr(TABLE *table_arg, TABLE_SHARE *share) {
4429  table = table_arg;
4430  table_share = share;
4431  }
4432  const TABLE_SHARE *get_table_share() const { return table_share; }
4433 
4434  /* Estimates calculation */
4435 
4436  /**
4437  @deprecated This function is deprecated and will be removed in a future
4438  version. Use table_scan_cost() instead.
4439  */
4440 
4441  virtual double scan_time() {
4442  return ulonglong2double(stats.data_file_length) / IO_SIZE + 2;
4443  }
4444 
4445  /**
4446  The cost of reading a set of ranges from the table using an index
4447  to access it.
4448 
4449  @deprecated This function is deprecated and will be removed in a future
4450  version. Use read_cost() instead.
4451 
4452  @param index The index number.
4453  @param ranges The number of ranges to be read.
4454  @param rows Total number of rows to be read.
4455 
4456  This method can be used to calculate the total cost of scanning a table
4457  using an index by calling it using read_time(index, 1, table_size).
4458  */
4459 
4460  virtual double read_time(uint index MY_ATTRIBUTE((unused)), uint ranges,
4461  ha_rows rows) {
4462  return rows2double(ranges + rows);
4463  }
4464 
4465  /**
4466  @deprecated This function is deprecated and will be removed in a future
4467  version. Use index_scan_cost() instead.
4468  */
4469 
4470  virtual double index_only_read_time(uint keynr, double records);
4471 
4472  /**
4473  Cost estimate for doing a complete table scan.
4474 
4475  @note For this version it is recommended that storage engines continue
4476  to override scan_time() instead of this function.
4477 
4478  @returns the estimated cost
4479  */
4480 
4481  virtual Cost_estimate table_scan_cost();
4482 
4483  /**
4484  Cost estimate for reading a number of ranges from an index.
4485 
4486  The cost estimate will only include the cost of reading data that
4487  is contained in the index. If the records need to be read, use
4488  read_cost() instead.
4489 
4490  @note The ranges parameter is currently ignored and is not taken
4491  into account in the cost estimate.
4492 
4493  @note For this version it is recommended that storage engines continue
4494  to override index_only_read_time() instead of this function.
4495 
4496  @param index the index number
4497  @param ranges the number of ranges to be read
4498  @param rows total number of rows to be read
4499 
4500  @returns the estimated cost
4501  */
4502 
4503  virtual Cost_estimate index_scan_cost(uint index, double ranges, double rows);
4504 
4505  /**
4506  Cost estimate for reading a set of ranges from the table using an index
4507  to access it.
4508 
4509  @note For this version it is recommended that storage engines continue
4510  to override read_time() instead of this function.
4511 
4512  @param index the index number
4513  @param ranges the number of ranges to be read
4514  @param rows total number of rows to be read
4515 
4516  @returns the estimated cost
4517  */
4518 
4519  virtual Cost_estimate read_cost(uint index, double ranges, double rows);
4520 
4521  /**
4522  Return an estimate on the amount of memory the storage engine will
4523  use for caching data in memory. If this is unknown or the storage
4524  engine does not cache data in memory -1 is returned.
4525  */
4526  virtual longlong get_memory_buffer_size() const { return -1; }
4527 
4528  /**
4529  Return an estimate of how much of the table that is currently stored
4530  in main memory.
4531 
4532  This estimate should be the fraction of the table that currently
4533  is available in a main memory buffer. The estimate should be in the
4534  range from 0.0 (nothing in memory) to 1.0 (entire table in memory).
4535 
4536  @return The fraction of the table in main memory buffer
4537  */
4538 
4539  double table_in_memory_estimate() const;
4540 
4541  /**
4542  Return an estimate of how much of the index that is currently stored
4543  in main memory.
4544 
4545  This estimate should be the fraction of the index that currently
4546  is available in a main memory buffer. The estimate should be in the
4547  range from 0.0 (nothing in memory) to 1.0 (entire index in memory).
4548 
4549  @param keyno the index to get an estimate for
4550 
4551  @return The fraction of the index in main memory buffer
4552  */
4553 
4554  double index_in_memory_estimate(uint keyno) const;
4555 
4556  int ha_sample_init(double sampling_percentage, int sampling_seed,
4557  enum_sampling_method sampling_method);
4558  int ha_sample_next(uchar *buf);
4559  int ha_sample_end();
4560 
4561  private:
4563 
4564  /**
4565  Make a guestimate for how much of a table or index is in a memory
4566  buffer in the case where the storage engine has not provided any
4567  estimate for this.
4568 
4569  @param table_index_size size of the table or index
4570 
4571  @return The fraction of the table or index in main memory buffer
4572  */
4573 
4574  double estimate_in_memory_buffer(ulonglong table_index_size) const;
4575 
4576  public:
4578  void *seq_init_param,
4579  uint n_ranges, uint *bufsz,
4580  uint *flags, Cost_estimate *cost);
4581  virtual ha_rows multi_range_read_info(uint keyno, uint n_ranges, uint keys,
4582  uint *bufsz, uint *flags,
4583  Cost_estimate *cost);
4584  virtual int multi_range_read_init(RANGE_SEQ_IF *seq, void *seq_init_param,
4585  uint n_ranges, uint mode,
4586  HANDLER_BUFFER *buf);
4587 
4588  int ha_multi_range_read_next(char **range_info);
4589 
4590  int ha_read_range_first(const key_range *start_key, const key_range *end_key,
4591  bool eq_range, bool sorted);
4592  int ha_read_range_next();
4593 
4595  return (ha_table_flags() & HA_NO_TRANSACTIONS) == 0;
4596  }
4597  virtual uint extra_rec_buf_length() const { return 0; }
4598 
4599  /**
4600  @brief Determine whether an error can be ignored or not.
4601 
4602  @details This method is used to analyze the error to see whether the
4603  error is ignorable or not. Such errors will be reported as warnings
4604  instead of errors for IGNORE statements. This means that the statement
4605  will not abort, but instead continue to the next row.
4606 
4607  HA_ERR_FOUND_DUP_UNIQUE is a special case in MyISAM that means the
4608  same thing as HA_ERR_FOUND_DUP_KEY, but can in some cases lead to
4609  a slightly different error message.
4610 
4611  @param error error code received from the handler interface (HA_ERR_...)
4612 
4613  @return whether the error is ignorablel or not
4614  @retval true the error is ignorable
4615  @retval false the error is not ignorable
4616  */
4617 
4618  virtual bool is_ignorable_error(int error);
4619 
4620  /**
4621  @brief Determine whether an error is fatal or not.
4622 
4623  @details This method is used to analyze the error to see whether the
4624  error is fatal or not. A fatal error is an error that will not be
4625  possible to handle with SP handlers and will not be subject to
4626  retry attempts on the slave.
4627 
4628  @param error error code received from the handler interface (HA_ERR_...)
4629 
4630  @return whether the error is fatal or not
4631  @retval true the error is fatal
4632  @retval false the error is not fatal
4633  */
4634 
4635  virtual bool is_fatal_error(int error);
4636 
4637  protected:
4638  virtual int multi_range_read_next(char **range_info);
4639 
4640  /**
4641  Number of rows in table. If HA_COUNT_ROWS_INSTANT is set, count is
4642  available instantly. Else do a table scan.
4643 
4644  @param num_rows [out] num_rows number of rows in table.
4645 
4646  @retval 0 for OK, one of the HA_xxx values in case of error.
4647  */
4648  virtual int records(ha_rows *num_rows);
4649 
4650  /**
4651  Number of rows in table counted using the secondary index chosen by
4652  optimizer. See comments in optimize_aggregated_query() .
4653 
4654  @param num_rows [out] Number of rows in table.
4655  @param index Index chosen by optimizer for counting.
4656 
4657  @retval 0 for OK, one of the HA_xxx values in case of error.
4658  */
4659  virtual int records_from_index(ha_rows *num_rows, uint index);
4660 
4661  private:
4662  /**
4663  Function will handle the error code from call to records() and
4664  records_from_index().
4665 
4666  @param error return code from records() and records_from_index().
4667  @param num_rows Check if it contains HA_POS_ERROR in case error < 0.
4668 
4669  @retval 0 for OK, one of the HA_xxx values in case of error.
4670  */
4671  int handle_records_error(int error, ha_rows *num_rows);
4672 
4673  public:
4674  /**
4675  Wrapper function to call records() in storage engine.
4676 
4677  @param num_rows [out] Number of rows in table.
4678 
4679  @retval 0 for OK, one of the HA_xxx values in case of error.
4680  */
4681  int ha_records(ha_rows *num_rows) {
4682  return handle_records_error(records(num_rows), num_rows);
4683  }
4684 
4685  /**
4686  Wrapper function to call records_from_index() in storage engine.
4687 
4688  @param num_rows [out] Number of rows in table.
4689  @param index Index chosen by optimizer for counting.
4690 
4691  @retval 0 for OK, one of the HA_xxx values in case of error.
4692  */
4693  int ha_records(ha_rows *num_rows, uint index) {
4694  return handle_records_error(records_from_index(num_rows, index), num_rows);
4695  }
4696 
4697  /**
4698  Return upper bound of current number of records in the table
4699  (max. of how many records one will retrieve when doing a full table scan)
4700  If upper bound is not known, HA_POS_ERROR should be returned as a max
4701  possible upper bound.
4702  */
4704  return stats.records + EXTRA_RECORDS;
4705  }
4706 
4707  /**
4708  Get real row type for the table created based on one specified by user,
4709  CREATE TABLE options and SE capabilities.
4710  */
4712  const HA_CREATE_INFO *create_info) const {
4713  return (create_info->table_options & HA_OPTION_COMPRESS_RECORD)
4715  : ((create_info->table_options & HA_OPTION_PACK_RECORD)
4717  : ROW_TYPE_FIXED);
4718  }
4719 
4720  /**
4721  Get default key algorithm for SE. It is used when user has not provided
4722  algorithm explicitly or when algorithm specified is not supported by SE.
4723  */
4725  return HA_KEY_ALG_SE_SPECIFIC;
4726  }
4727 
4728  /**
4729  Check if SE supports specific key algorithm.
4730 
4731  @note This method is never used for FULLTEXT or SPATIAL keys.
4732  We rely on handler::ha_table_flags() to check if such keys
4733  are supported.
4734  */
4735  virtual bool is_index_algorithm_supported(enum ha_key_alg key_alg) const {
4736  return key_alg == HA_KEY_ALG_SE_SPECIFIC;
4737  }
4738 
4739  /**
4740  Signal that the table->read_set and table->write_set table maps changed
4741  The handler is allowed to set additional bits in the above map in this
4742  call. Normally the handler should ignore all calls until we have done
4743  a ha_rnd_init() or ha_index_init(), write_row(), update_row or delete_row()
4744  as there may be several calls to this routine.
4745  */
4746  virtual void column_bitmaps_signal();
4747  uint get_index(void) const { return active_index; }
4748 
4749  /**
4750  @retval 0 Bulk update used by handler
4751  @retval 1 Bulk update not used, normal operation used
4752  */
4753  virtual bool start_bulk_update() { return 1; }
4754  /**
4755  @retval 0 Bulk delete used by handler
4756  @retval 1 Bulk delete not used, normal operation used
4757  */
4758  virtual bool start_bulk_delete() { return 1; }
4759  /**
4760  After this call all outstanding updates must be performed. The number
4761  of duplicate key errors are reported in the duplicate key parameter.
4762  It is allowed to continue to the batched update after this call, the
4763  handler has to wait until end_bulk_update with changing state.
4764 
4765  @param dup_key_found Number of duplicate keys found
4766 
4767  @retval 0 Success
4768  @retval >0 Error code
4769  */
4770  virtual int exec_bulk_update(uint *dup_key_found MY_ATTRIBUTE((unused))) {
4771  DBUG_ASSERT(false);
4772  return HA_ERR_WRONG_COMMAND;
4773  }
4774  /**
4775  Perform any needed clean-up, no outstanding updates are there at the
4776  moment.
4777  */
4778  virtual void end_bulk_update() { return; }
4779  /**
4780  Execute all outstanding deletes and close down the bulk delete.
4781 
4782  @retval 0 Success
4783  @retval >0 Error code
4784  */
4785  virtual int end_bulk_delete() {
4786  DBUG_ASSERT(false);
4787  return HA_ERR_WRONG_COMMAND;
4788  }
4789 
4790  protected:
4791  /**
4792  @brief
4793  Positions an index cursor to the index specified in the handle
4794  ('active_index'). Fetches the row if available. If the key value is null,
4795  begin at the first key of the index.
4796  @returns 0 if success (found a record); non-zero if no record.
4797  */
4798  virtual int index_read_map(uchar *buf, const uchar *key,
4799  key_part_map keypart_map,
4800  enum ha_rkey_function find_flag) {
4801  uint key_len = calculate_key_len(table, active_index, keypart_map);
4802  return index_read(buf, key, key_len, find_flag);
4803  }
4804  /**
4805  Positions an index cursor to the index specified in argument. Fetches
4806  the row if available. If the key value is null, begin at the first key of
4807  the index.
4808  @sa index_read_map()
4809  */
4810  virtual int index_read_idx_map(uchar *buf, uint index, const uchar *key,
4811  key_part_map keypart_map,
4812  enum ha_rkey_function find_flag);
4813 
4814  /*
4815  These methods are used to jump to next or previous entry in the index
4816  scan. There are also methods to jump to first and last entry.
4817  */
4818  /// @see index_read_map().
4819  virtual int index_next(uchar *) { return HA_ERR_WRONG_COMMAND; }
4820 
4821  /// @see index_read_map().
4822  virtual int index_prev(uchar *) { return HA_ERR_WRONG_COMMAND; }
4823 
4824  /// @see index_read_map().
4825  virtual int index_first(uchar *) { return HA_ERR_WRONG_COMMAND; }
4826 
4827  /// @see index_read_map().
4828  virtual int index_last(uchar *) { return HA_ERR_WRONG_COMMAND; }
4829 
4830  /// @see index_read_map().
4831  virtual int index_next_same(uchar *buf, const uchar *key, uint keylen);
4832  /**
4833  The following functions works like index_read, but it find the last
4834  row with the current key value or prefix.
4835  @see index_read_map().
4836  */
4837  virtual int index_read_last_map(uchar *buf, const uchar *key,
4838  key_part_map keypart_map) {
4839  uint key_len = calculate_key_len(table, active_index, keypart_map);
4840  return index_read_last(buf, key, key_len);
4841  }
4842 
4843  virtual int read_range_first(const key_range *start_key,
4844  const key_range *end_key, bool eq_range,
4845  bool sorted);
4846  virtual int read_range_next();
4847 
4848  public:
4849  /**
4850  Set the end position for a range scan. This is used for checking
4851  for when to end the range scan and by the ICP code to determine
4852  that the next record is within the current range.
4853 
4854  @param range The end value for the range scan
4855  @param direction Direction of the range scan
4856  */
4857  void set_end_range(const key_range *range,
4858  enum_range_scan_direction direction);
4859  int compare_key(key_range *range);
4860  int compare_key_icp(const key_range *range) const;
4861  int compare_key_in_buffer(const uchar *buf) const;
4862  virtual int ft_init() { return HA_ERR_WRONG_COMMAND; }
4863  void ft_end() { ft_handler = NULL; }
4864  virtual FT_INFO *ft_init_ext(uint flags MY_ATTRIBUTE((unused)),
4865  uint inx MY_ATTRIBUTE((unused)),
4866  String *key MY_ATTRIBUTE((unused))) {
4867  return NULL;
4868  }
4870  Ft_hints *hints) {
4871  return ft_init_ext(hints->get_flags(), inx, key);
4872  }
4873  int ha_ft_read(uchar *buf);
4874  int ha_read_first_row(uchar *buf, uint primary_key);
4875 
4876  protected:
4877  /// @see index_read_map().
4878  virtual int rnd_next(uchar *buf) = 0;
4879  /// @see index_read_map().
4880  virtual int rnd_pos(uchar *buf, uchar *pos) = 0;
4881 
4882  virtual int ft_read(uchar *) { return HA_ERR_WRONG_COMMAND; }
4883 
4884  public:
4885  /**
4886  This function only works for handlers having
4887  HA_PRIMARY_KEY_REQUIRED_FOR_POSITION set.
4888  It will return the row with the PK given in the record argument.
4889  */
4891  int error;
4893 
4894  error = ha_rnd_init(false);
4895  if (error != 0) return error;
4896 
4897  position(record);
4898  error = ha_rnd_pos(record, ref);
4899 
4900  ha_rnd_end();
4901  return error;
4902  }
4903 
4904  /**
4905  Find number of records in a range.
4906 
4907  Given a starting key, and an ending key estimate the number of rows that
4908  will exist between the two. max_key may be empty which in case determine
4909  if start_key matches any rows. Used by optimizer to calculate cost of
4910  using a particular index.
4911 
4912  @param inx Index number
4913  @param min_key Start of range
4914  @param max_key End of range
4915 
4916  @return Number of rows in range.
4917  */
4918 
4919  virtual ha_rows records_in_range(uint inx MY_ATTRIBUTE((unused)),
4920  key_range *min_key MY_ATTRIBUTE((unused)),
4921  key_range *max_key MY_ATTRIBUTE((unused))) {
4922  return (ha_rows)10;
4923  }
4924  /*
4925  If HA_PRIMARY_KEY_REQUIRED_FOR_POSITION is set, then it sets ref
4926  (reference to the row, aka position, with the primary key given in
4927  the record).
4928  Otherwise it set ref to the current row.
4929  */
4930  virtual void position(const uchar *record) = 0;
4931 
4932  /**
4933  General method to gather info from handler
4934 
4935  ::info() is used to return information to the optimizer.
4936  SHOW also makes use of this data Another note, if your handler
4937  doesn't proved exact record count, you will probably want to
4938  have the following in your code:
4939  if (records < 2)
4940  records = 2;
4941  The reason is that the server will optimize for cases of only a single
4942  record. If in a table scan you don't know the number of records
4943  it will probably be better to set records to two so you can return
4944  as many records as you need.
4945 
4946  Along with records a few more variables you may wish to set are:
4947  records
4948  deleted
4949  data_file_length
4950  index_file_length
4951  delete_length
4952  check_time
4953  Take a look at the public variables in handler.h for more information.
4954  See also my_base.h for a full description.
4955 
4956  @param flag Specifies what info is requested
4957  */
4958 
4959  virtual int info(uint flag) = 0;
4961  Field **field_array MY_ATTRIBUTE((unused))) {
4962  DBUG_ASSERT(0);
4963  return 0;
4964  }
4965  virtual int extra(enum ha_extra_function operation MY_ATTRIBUTE((unused))) {
4966  return 0;
4967  }
4968  virtual int extra_opt(enum ha_extra_function operation,
4969  ulong cache_size MY_ATTRIBUTE((unused))) {
4970  return extra(operation);
4971  }
4972 
4973  /**
4974  Start read (before write) removal on the current table.
4975  @see HA_READ_BEFORE_WRITE_REMOVAL
4976  */
4977  virtual bool start_read_removal(void) {
4978  DBUG_ASSERT(0);
4979  return false;
4980  }
4981 
4982  /**
4983  End read (before write) removal and return the number of rows
4984  really written
4985  @see HA_READ_BEFORE_WRITE_REMOVAL
4986  */
4987  virtual ha_rows end_read_removal(void) {
4988  DBUG_ASSERT(0);
4989  return (ha_rows)0;
4990  }
4991 
4992  /**
4993  In an UPDATE or DELETE, if the row under the cursor was locked by another
4994  transaction, and the engine used an optimistic read of the last
4995  committed row value under the cursor, then the engine returns 1 from this
4996  function. MySQL must NOT try to update this optimistic value. If the
4997  optimistic value does not match the WHERE condition, MySQL can decide to
4998  skip over this row. Currently only works for InnoDB. This can be used to
4999  avoid unnecessary lock waits.
5000 
5001  If this method returns nonzero, it will also signal the storage
5002  engine that the next read will be a locking re-read of the row.
5003  */
5004  virtual bool was_semi_consistent_read() { return 0; }
5005  /**
5006  Tell the engine whether it should avoid unnecessary lock waits.
5007  If yes, in an UPDATE or DELETE, if the row under the cursor was locked
5008  by another transaction, the engine may try an optimistic read of
5009  the last committed row value under the cursor.
5010  */
5011  virtual void try_semi_consistent_read(bool) {}
5012 
5013  /**
5014  Unlock last accessed row.
5015 
5016  Record currently processed was not in the result set of the statement
5017  and is thus unlocked. Used for UPDATE and DELETE queries.
5018  */
5019 
5020  virtual void unlock_row() {}
5021 
5022  /**
5023  Start a statement when table is locked
5024 
5025  This method is called instead of external lock when the table is locked
5026  before the statement is executed.
5027 
5028  @param thd Thread object.
5029  @param lock_type Type of external lock.
5030 
5031  @retval >0 Error code.
5032  @retval 0 Success.
5033  */
5034 
5035  virtual int start_stmt(THD *thd MY_ATTRIBUTE((unused)),
5036  thr_lock_type lock_type MY_ATTRIBUTE((unused))) {
5037  return 0;
5038  }
5039  virtual void get_auto_increment(ulonglong offset, ulonglong increment,
5040  ulonglong nb_desired_values,
5041  ulonglong *first_value,
5042  ulonglong *nb_reserved_values);
5044  DBUG_PRINT("info", ("auto_increment: next value %lu", (ulong)id));
5045  next_insert_id = id;
5046  }
5048  /*
5049  Insertion of a row failed, re-use the lastly generated auto_increment
5050  id, for the next row. This is achieved by resetting next_insert_id to
5051  what it was before the failed insertion (that old value is provided by
5052  the caller). If that value was 0, it was the first row of the INSERT;
5053  then if insert_id_for_cur_row contains 0 it means no id was generated
5054  for this first row, so no id was generated since the INSERT started, so
5055  we should set next_insert_id to 0; if insert_id_for_cur_row is not 0, it
5056  is the generated id of the first and failed row, so we use it.
5057  */
5058  next_insert_id =
5060  }
5061 
5062  /**
5063  Update create info as part of ALTER TABLE.
5064 
5065  Forward this handler call to the storage engine foreach
5066  partition handler. The data_file_name for each partition may
5067  need to be reset if the tablespace was moved. Use a dummy
5068  HA_CREATE_INFO structure and transfer necessary data.
5069 
5070  @param create_info Create info from ALTER TABLE.
5071  */
5072 
5073  virtual void update_create_info(
5074  HA_CREATE_INFO *create_info MY_ATTRIBUTE((unused))) {}
5076  return HA_ADMIN_NOT_IMPLEMENTED;
5077  }
5078  virtual int preload_keys(THD *, HA_CHECK_OPT *) {
5079  return HA_ADMIN_NOT_IMPLEMENTED;
5080  }
5081  /* end of the list of admin commands */
5082 
5083  /**
5084  Check if indexes are disabled.
5085 
5086  @retval 0 Indexes are enabled.
5087  @retval != 0 Indexes are disabled.
5088  */
5089 
5090  virtual int indexes_are_disabled(void) { return 0; }
5091  virtual void append_create_info(String *packet MY_ATTRIBUTE((unused))) {}
5092  /**
5093  If index == MAX_KEY then a check for table is made and if index <
5094  MAX_KEY then a check is made if the table has foreign keys and if
5095  a foreign key uses this index (and thus the index cannot be dropped).
5096 
5097  @param index Index to check if foreign key uses it
5098 
5099  @retval true Foreign key defined on table or index
5100  @retval false No foreign key defined
5101  */
5103  uint index MY_ATTRIBUTE((unused))) {
5104  return false;
5105  }
5107  return (NULL);
5108  } /* gets foreign key create string from InnoDB */
5109  /**
5110  Get the list of foreign keys in this table.
5111 
5112  @remark Returns the set of foreign keys where this table is the
5113  dependent or child table.
5114 
5115  @param thd The thread handle.
5116  @param [out] f_key_list The list of foreign keys.
5117 
5118  @return The handler error code or zero for success.
5119  */
5120  virtual int get_foreign_key_list(THD *thd MY_ATTRIBUTE((unused)),
5121  List<FOREIGN_KEY_INFO> *f_key_list
5122  MY_ATTRIBUTE((unused))) {
5123  return 0;
5124  }
5125  /**
5126  Get the list of foreign keys referencing this table.
5127 
5128  @remark Returns the set of foreign keys where this table is the
5129  referenced or parent table.
5130 
5131  @param thd The thread handle.
5132  @param [out] f_key_list The list of foreign keys.
5133 
5134  @return The handler error code or zero for success.
5135  */
5136  virtual int get_parent_foreign_key_list(THD *thd MY_ATTRIBUTE((unused)),
5137  List<FOREIGN_KEY_INFO> *f_key_list
5138  MY_ATTRIBUTE((unused))) {
5139  return 0;
5140  }
5141  /**
5142  Get the list of tables which are direct or indirect parents in foreign
5143  key with cascading actions for this table.
5144 
5145  @remarks Returns the set of parent tables connected by FK clause that
5146  can modify the given table.
5147 
5148  @param thd The thread handle.
5149  @param[out] fk_table_list List of parent tables (including indirect
5150  parents). Elements of the list as well as buffers for database and schema
5151  names are allocated from the current memory root.
5152 
5153  @return The handler error code or zero for success
5154  */
5156  THD *thd MY_ATTRIBUTE((unused)),
5157  List<st_handler_tablename> *fk_table_list MY_ATTRIBUTE((unused))) {
5158  return 0;
5159  }
5160  virtual uint referenced_by_foreign_key() { return 0; }
5162  return;
5163  } /* prepare InnoDB for HANDLER */
5164  virtual void free_foreign_key_create_info(char *) {}
5165  /** The following can be called without an open handler */
5166  virtual const char *table_type() const = 0;
5167 
5168  virtual ulong index_flags(uint idx, uint part, bool all_parts) const = 0;
5169 
5171  return std::min(HA_MAX_REC_LENGTH, max_supported_record_length());
5172  }
5173  uint max_keys() const {
5174  return std::min<uint>(MAX_KEY, max_supported_keys());
5175  }
5177  return std::min(MAX_REF_PARTS, max_supported_key_parts());
5178  }
5180  return std::min(MAX_KEY_LENGTH, max_supported_key_length());
5181  }
5183  return std::min(MAX_KEY_LENGTH, max_supported_key_part_length(create_info));
5184  }
5185 
5187  virtual uint max_supported_keys() const { return 0; }
5188  virtual uint max_supported_key_parts() const { return MAX_REF_PARTS; }
5189  virtual uint max_supported_key_length() const { return MAX_KEY_LENGTH; }
5191  HA_CREATE_INFO *create_info MY_ATTRIBUTE((unused))) const {
5192  return 255;
5193  }
5194  virtual uint min_record_length(uint options MY_ATTRIBUTE((unused))) const {
5195  return 1;
5196  }
5197 
5198  virtual bool low_byte_first() const { return 1; }
5199  virtual ha_checksum checksum() const { return 0; }
5200 
5201  /**
5202  Check if the table is crashed.
5203 
5204  @retval true Crashed
5205  @retval false Not crashed
5206  */
5207 
5208  virtual bool is_crashed() const { return 0; }
5209 
5210  /**
5211  Check if the table can be automatically repaired.
5212 
5213  @retval true Can be auto repaired
5214  @retval false Cannot be auto repaired
5215  */
5216 
5217  virtual bool auto_repair() const { return 0; }
5218 
5219  /**
5220  Get number of lock objects returned in store_lock.
5221 
5222  Returns the number of store locks needed in call to store lock.
5223  We return number of partitions we will lock multiplied with number of
5224  locks needed by each partition. Assists the above functions in allocating
5225  sufficient space for lock structures.
5226 
5227  @returns Number of locks returned in call to store_lock.
5228 
5229  @note lock_count() can return > 1 if the table is MERGE or partitioned.
5230  */
5231 
5232  virtual uint lock_count(void) const { return 1; }
5233 
5234  /**
5235  Is not invoked for non-transactional temporary tables.
5236 
5237  @note store_lock() can return more than one lock if the table is MERGE
5238  or partitioned.
5239 
5240  @note that one can NOT rely on table->in_use in store_lock(). It may
5241  refer to a different thread if called from mysql_lock_abort_for_thread().
5242 
5243  @note If the table is MERGE, store_lock() can return less locks
5244  than lock_count() claimed. This can happen when the MERGE children
5245  are not attached when this is called from another thread.
5246 
5247  The idea with handler::store_lock() is the following:
5248 
5249  The statement decided which locks we should need for the table
5250  for updates/deletes/inserts we get WRITE locks, for SELECT... we get
5251  read locks.
5252 
5253  Before adding the lock into the table lock handler (see thr_lock.c)
5254  mysqld calls store lock with the requested locks. Store lock can now
5255  modify a write lock to a read lock (or some other lock), ignore the
5256  lock (if we don't want to use MySQL table locks at all) or add locks
5257  for many tables (like we do when we are using a MERGE handler).
5258 
5259  In some exceptional cases MySQL may send a request for a TL_IGNORE;
5260  This means that we are requesting the same lock as last time and this
5261  should also be ignored.
5262 
5263  Called from lock.cc by get_lock_data().
5264  */
5265  virtual THR_LOCK_DATA **store_lock(THD *thd, THR_LOCK_DATA **to,
5266  enum thr_lock_type lock_type) = 0;
5267 
5268  /**
5269  Check if the primary key is clustered or not.
5270 
5271  @retval true Primary key (if there is one) is a clustered
5272  key covering all fields
5273  @retval false otherwise
5274  */
5275 
5276  virtual bool primary_key_is_clustered() const { return false; }
5277 
5278  /**
5279  Compare two positions.
5280 
5281  @param ref1 First position.
5282  @param ref2 Second position.
5283 
5284  @retval <0 ref1 < ref2.
5285  @retval 0 Equal.
5286  @retval >0 ref1 > ref2.
5287  */
5288 
5289  virtual int cmp_ref(const uchar *ref1, const uchar *ref2) const {
5290  return memcmp(ref1, ref2, ref_length);
5291  }
5292 
5293  /*
5294  Condition pushdown to storage engines
5295  */
5296 
5297  /**
5298  Push condition down to the table handler.
5299 
5300  @param cond Condition to be pushed. The condition tree
5301  must not be modified by the caller.
5302  @param other_tbls_ok Are other tables than than 'this' allowed to
5303  be referred by the condition terms being pushed.
5304 
5305  @return
5306  The 'remainder' condition that caller must use to filter out records.
5307  NULL means the handler will not return rows that do not match the
5308  passed condition.
5309 
5310  @note
5311  handler->ha_reset() call discard any pushed conditions.
5312  Calls to rnd_init/rnd_end, index_init/index_end etc do not affect the
5313  pushed conditions.
5314  */
5315  virtual const Item *cond_push(const Item *cond,
5316  bool other_tbls_ok MY_ATTRIBUTE((unused))) {
5318  return cond;
5319  }
5320 
5321  /**
5322  Push down an index condition to the handler.
5323 
5324  The server will use this method to push down a condition it wants
5325  the handler to evaluate when retrieving records using a specified
5326  index. The pushed index condition will only refer to fields from
5327  this handler that is contained in the index (but it may also refer
5328  to fields in other handlers). Before the handler evaluates the
5329  condition it must read the content of the index entry into the
5330  record buffer.
5331 
5332  The handler is free to decide if and how much of the condition it
5333  will take responsibility for evaluating. Based on this evaluation
5334  it should return the part of the condition it will not evaluate.
5335  If it decides to evaluate the entire condition it should return
5336  NULL. If it decides not to evaluate any part of the condition it
5337  should return a pointer to the same condition as given as argument.
5338 
5339  @param keyno the index number to evaluate the condition on
5340  @param idx_cond the condition to be evaluated by the handler
5341 
5342  @return The part of the pushed condition that the handler decides
5343  not to evaluate
5344  */
5345 
5346  virtual Item *idx_cond_push(uint keyno MY_ATTRIBUTE((unused)),
5347  Item *idx_cond) {
5348  return idx_cond;
5349  }
5350 
5351  /** Reset information about pushed index conditions */
5352  virtual void cancel_pushed_idx_cond() {
5354