2 Copyright (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved.
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; version 2 of the License.
8 This program is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 GNU General Public License for more details.
13 You should have received a copy of the GNU General Public License
14 along with this program; if not, write to the Free Software
15 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18 /** @file ha_example.h
21 The ha_example engine is a stubbed storage engine for example purposes only;
22 it does nothing at this point. Its purpose is to provide a source
23 code illustration of how to begin writing new storage engines; see also
24 /storage/example/ha_example.cc.
27 Please read ha_example.cc before reading this file.
28 Reminder: The example storage engine implements all methods that are *required*
29 to be implemented. For a full list of all methods that you can implement, see
33 /sql/handler.h and /storage/example/ha_example.cc
36 #ifdef USE_PRAGMA_INTERFACE
37 #pragma interface /* gcc class implementation */
41 EXAMPLE_SHARE is a structure that will be shared among all open handlers.
42 This example implements the minimum of what you will probably need.
44 typedef struct st_example_share
{
46 uint table_name_length
,use_count
;
47 pthread_mutex_t mutex
;
52 Class definition for the storage engine
54 class ha_example
: public handler
56 THR_LOCK_DATA lock
; ///< MySQL lock
57 EXAMPLE_SHARE
*share
; ///< Shared lock info
60 ha_example(handlerton
*hton
, TABLE_SHARE
*table_arg
);
66 The name that will be used for display purposes.
68 const char *table_type() const { return "EXAMPLE"; }
71 The name of the index type that will be used for display.
72 Don't implement this method unless you really have indexes.
74 const char *index_type(uint inx
) { return "HASH"; }
79 const char **bas_ext() const;
82 This is a list of flags that indicate what functionality the storage engine
83 implements. The current table flags are documented in handler.h
85 ulonglong
table_flags() const
88 We are saying that this engine is just row capable to have an
89 engine that can only handle row-based logging. This is used in
92 return HA_BINLOG_ROW_CAPABLE
;
96 This is a bitmap of flags that indicates how the storage engine
97 implements indexes. The current index flags are documented in
98 handler.h. If you do not implement indexes, just return zero here.
101 part is the key part to check. First key part is 0.
102 If all_parts is set, MySQL wants to know the flags for the combined
103 index, up to and including 'part'.
105 ulong
index_flags(uint inx
, uint part
, bool all_parts
) const
111 unireg.cc will call max_supported_record_length(), max_supported_keys(),
112 max_supported_key_parts(), uint max_supported_key_length()
113 to make sure that the storage engine can handle the data it is about to
114 send. Return *real* limits of your storage engine here; MySQL will do
115 min(your_limits, MySQL_limits) automatically.
117 uint
max_supported_record_length() const { return HA_MAX_REC_LENGTH
; }
120 unireg.cc will call this to make sure that the storage engine can handle
121 the data it is about to send. Return *real* limits of your storage engine
122 here; MySQL will do min(your_limits, MySQL_limits) automatically.
125 There is no need to implement ..._key_... methods if your engine doesn't
128 uint
max_supported_keys() const { return 0; }
131 unireg.cc will call this to make sure that the storage engine can handle
132 the data it is about to send. Return *real* limits of your storage engine
133 here; MySQL will do min(your_limits, MySQL_limits) automatically.
136 There is no need to implement ..._key_... methods if your engine doesn't
139 uint
max_supported_key_parts() const { return 0; }
142 unireg.cc will call this to make sure that the storage engine can handle
143 the data it is about to send. Return *real* limits of your storage engine
144 here; MySQL will do min(your_limits, MySQL_limits) automatically.
147 There is no need to implement ..._key_... methods if your engine doesn't
150 uint
max_supported_key_length() const { return 0; }
153 Called in test_quick_select to determine if indexes should be used.
155 virtual double scan_time() { return (double) (stats
.records
+stats
.deleted
) / 20.0+10; }
158 This method will never be called if you do not implement indexes.
160 virtual double read_time(uint
, uint
, ha_rows rows
)
161 { return (double) rows
/ 20.0+1; }
164 Everything below are methods that we implement in ha_example.cc.
166 Most of these methods are not obligatory, skip them and
167 MySQL will treat them as not implemented
170 We implement this in ha_example.cc; it's a required method.
172 int open(const char *name
, int mode
, uint test_if_locked
); // required
175 We implement this in ha_example.cc; it's a required method.
177 int close(void); // required
180 We implement this in ha_example.cc. It's not an obligatory method;
181 skip it and and MySQL will treat it as not implemented.
183 int write_row(uchar
*buf
);
186 We implement this in ha_example.cc. It's not an obligatory method;
187 skip it and and MySQL will treat it as not implemented.
189 int update_row(const uchar
*old_data
, uchar
*new_data
);
192 We implement this in ha_example.cc. It's not an obligatory method;
193 skip it and and MySQL will treat it as not implemented.
195 int delete_row(const uchar
*buf
);
198 We implement this in ha_example.cc. It's not an obligatory method;
199 skip it and and MySQL will treat it as not implemented.
201 int index_read_map(uchar
*buf
, const uchar
*key
,
202 key_part_map keypart_map
, enum ha_rkey_function find_flag
);
205 We implement this in ha_example.cc. It's not an obligatory method;
206 skip it and and MySQL will treat it as not implemented.
208 int index_next(uchar
*buf
);
211 We implement this in ha_example.cc. It's not an obligatory method;
212 skip it and and MySQL will treat it as not implemented.
214 int index_prev(uchar
*buf
);
217 We implement this in ha_example.cc. It's not an obligatory method;
218 skip it and and MySQL will treat it as not implemented.
220 int index_first(uchar
*buf
);
223 We implement this in ha_example.cc. It's not an obligatory method;
224 skip it and and MySQL will treat it as not implemented.
226 int index_last(uchar
*buf
);
229 Unlike index_init(), rnd_init() can be called two consecutive times
230 without rnd_end() in between (it only makes sense if scan=1). In this
231 case, the second call should prepare for the new table scan (e.g if
232 rnd_init() allocates the cursor, the second call should position the
233 cursor to the start of the table; no need to deallocate and allocate
234 it again. This is a required method.
236 int rnd_init(bool scan
); //required
238 int rnd_next(uchar
*buf
); ///< required
239 int rnd_pos(uchar
*buf
, uchar
*pos
); ///< required
240 void position(const uchar
*record
); ///< required
241 int info(uint
); ///< required
242 int extra(enum ha_extra_function operation
);
243 int external_lock(THD
*thd
, int lock_type
); ///< required
244 int delete_all_rows(void);
245 ha_rows
records_in_range(uint inx
, key_range
*min_key
,
247 int delete_table(const char *from
);
248 int rename_table(const char * from
, const char * to
);
249 int create(const char *name
, TABLE
*form
,
250 HA_CREATE_INFO
*create_info
); ///< required
252 THR_LOCK_DATA
**store_lock(THD
*thd
, THR_LOCK_DATA
**to
,
253 enum thr_lock_type lock_type
); ///< required