release/src/router/mysql/storage/example/ha_example.h

   1 /*
   2   Copyright (c) 2004, 2010, Oracle and/or its affiliates. All rights reserved.
   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
  18 /** @file ha_example.h
  19
  20     @brief
  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.
  25
  26     @note
  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
  30   handler.h.
  31
  32    @see
  33   /sql/handler.h and /storage/example/ha_example.cc
  34 */
  35
  36 #ifdef USE_PRAGMA_INTERFACE
  37 #pragma interface                       /* gcc class implementation */
  38 #endif
  39
  40 /** @brief
  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.
  43 */
  44 typedef struct st_example_share {
  45   char *table_name;
  46   uint table_name_length,use_count;
  47   pthread_mutex_t mutex;
  48   THR_LOCK lock;
  49 } EXAMPLE_SHARE;
  50
  51 /** @brief
  52   Class definition for the storage engine
  53 */
  54 class ha_example: public handler
  55 {
  56   THR_LOCK_DATA lock;      ///< MySQL lock
  57   EXAMPLE_SHARE *share;    ///< Shared lock info
  58
  59 public:
  60   ha_example(handlerton *hton, TABLE_SHARE *table_arg);
  61   ~ha_example()
  62   {
  63   }
  64
  65   /** @brief
  66     The name that will be used for display purposes.
  67    */
  68   const char *table_type() const { return "EXAMPLE"; }
  69
  70   /** @brief
  71     The name of the index type that will be used for display.
  72     Don't implement this method unless you really have indexes.
  73    */
  74   const char *index_type(uint inx) { return "HASH"; }
  75
  76   /** @brief
  77     The file extensions.
  78    */
  79   const char **bas_ext() const;
  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 row capable to have an
  89       engine that can only handle row-based logging. This is used in
  90       testing.
  91     */
  92     return HA_BINLOG_ROW_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, 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 rename_table(const char * from, const char * to);
 249   int create(const char *name, TABLE *form,
 250              HA_CREATE_INFO *create_info);                      ///< required
 251
 252   THR_LOCK_DATA **store_lock(THD *thd, THR_LOCK_DATA **to,
 253                              enum thr_lock_type lock_type);     ///< required
 254 };