1/*
2 Copyright (c) 2004, 2010, Oracle and/or its affiliates
3
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.
7
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.
12
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 */
16
17/** @file ha_example.h
18
19 @brief
20 The ha_example engine is a stubbed storage engine for example purposes only;
21 it does nothing at this point. Its purpose is to provide a source
22 code illustration of how to begin writing new storage engines; see also
23 /storage/example/ha_example.cc.
24
25 @note
26 Please read ha_example.cc before reading this file.
27 Reminder: The example storage engine implements all methods that are *required*
28 to be implemented. For a full list of all methods that you can implement, see
29 handler.h.
30
31 @see
32 /sql/handler.h and /storage/example/ha_example.cc
33*/
34
35#ifdef USE_PRAGMA_INTERFACE
36#pragma interface /* gcc class implementation */
37#endif
38
39#include "my_global.h" /* ulonglong */
40#include "thr_lock.h" /* THR_LOCK, THR_LOCK_DATA */
41#include "handler.h" /* handler */
42#include "my_base.h" /* ha_rows */
43
44/** @brief
45 Example_share is a class that will be shared among all open handlers.
46 This example implements the minimum of what you will probably need.
47*/
48class Example_share : public Handler_share {
49public:
50 mysql_mutex_t mutex;
51 THR_LOCK lock;
52 Example_share();
53 ~Example_share()
54 {
55 thr_lock_delete(&lock);
56 mysql_mutex_destroy(&mutex);
57 }
58};
59
60/** @brief
61 Class definition for the storage engine
62*/
63class ha_example: public handler
64{
65 THR_LOCK_DATA lock; ///< MySQL lock
66 Example_share *share; ///< Shared lock info
67 Example_share *get_share(); ///< Get the share
68
69public:
70 ha_example(handlerton *hton, TABLE_SHARE *table_arg);
71 ~ha_example()
72 {
73 }
74
75 /** @brief
76 The name of the index type that will be used for display.
77 Don't implement this method unless you really have indexes.
78 */
79 const char *index_type(uint inx) { return "HASH"; }
80
81 /** @brief
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
84 */
85 ulonglong table_flags() const
86 {
87 /*
88 We are saying that this engine is just statement capable to have
89 an engine that can only handle statement-based logging. This is
90 used in testing.
91 */
92 return HA_BINLOG_STMT_CAPABLE;
93 }
94
95 /** @brief
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.
99
100 @details
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'.
104 */
105 ulong index_flags(uint inx, uint part, bool all_parts) const
106 {
107 return 0;
108 }
109
110 /** @brief
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.
116 */
117 uint max_supported_record_length() const { return HA_MAX_REC_LENGTH; }
118
119 /** @brief
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.
123
124 @details
125 There is no need to implement ..._key_... methods if your engine doesn't
126 support indexes.
127 */
128 uint max_supported_keys() const { return 0; }
129
130 /** @brief
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.
134
135 @details
136 There is no need to implement ..._key_... methods if your engine doesn't
137 support indexes.
138 */
139 uint max_supported_key_parts() const { return 0; }
140
141 /** @brief
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.
145
146 @details
147 There is no need to implement ..._key_... methods if your engine doesn't
148 support indexes.
149 */
150 uint max_supported_key_length() const { return 0; }
151
152 /** @brief
153 Called in test_quick_select to determine if indexes should be used.
154 */
155 virtual double scan_time() { return (double) (stats.records+stats.deleted) / 20.0+10; }
156
157 /** @brief
158 This method will never be called if you do not implement indexes.
159 */
160 virtual double read_time(uint, uint, ha_rows rows)
161 { return (double) rows / 20.0+1; }
162
163 /*
164 Everything below are methods that we implement in ha_example.cc.
165
166 Most of these methods are not obligatory, skip them and
167 MySQL will treat them as not implemented
168 */
169 /** @brief
170 We implement this in ha_example.cc; it's a required method.
171 */
172 int open(const char *name, int mode, uint test_if_locked); // required
173
174 /** @brief
175 We implement this in ha_example.cc; it's a required method.
176 */
177 int close(void); // required
178
179 /** @brief
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.
182 */
183 int write_row(uchar *buf);
184
185 /** @brief
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.
188 */
189 int update_row(const uchar *old_data, const uchar *new_data);
190
191 /** @brief
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.
194 */
195 int delete_row(const uchar *buf);
196
197 /** @brief
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.
200 */
201 int index_read_map(uchar *buf, const uchar *key,
202 key_part_map keypart_map, enum ha_rkey_function find_flag);
203
204 /** @brief
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.
207 */
208 int index_next(uchar *buf);
209
210 /** @brief
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.
213 */
214 int index_prev(uchar *buf);
215
216 /** @brief
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.
219 */
220 int index_first(uchar *buf);
221
222 /** @brief
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.
225 */
226 int index_last(uchar *buf);
227
228 /** @brief
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.
235 */
236 int rnd_init(bool scan); //required
237 int rnd_end();
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,
246 key_range *max_key);
247 int delete_table(const char *from);
248 int create(const char *name, TABLE *form,
249 HA_CREATE_INFO *create_info); ///< required
250 enum_alter_inplace_result
251 check_if_supported_inplace_alter(TABLE* altered_table,
252 Alter_inplace_info* ha_alter_info);
253
254 THR_LOCK_DATA **store_lock(THD *thd, THR_LOCK_DATA **to,
255 enum thr_lock_type lock_type); ///< required
256};
257