diff options
Diffstat (limited to 'storage/example/ha_example.h')
| -rw-r--r-- | storage/example/ha_example.h | 206 |
1 files changed, 150 insertions, 56 deletions
diff --git a/storage/example/ha_example.h b/storage/example/ha_example.h index 4e2de9be3d3..2d173368493 100644 --- a/storage/example/ha_example.h +++ b/storage/example/ha_example.h @@ -14,20 +14,31 @@ along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/* - Please read ha_exmple.cc before reading this file. - Please keep in mind that the example storage engine implements all methods - that are required to be implemented. handler.h has a full list of methods - that you can implement. +/** @file ha_example.h + + @brief + The ha_example engine is a stubbed storage engine for example purposes only; + it does nothing at this point. Its purpose is to provide a source + code illustration of how to begin writing new storage engines; see also + /storage/example/ha_example.cc. + + @note + Please read ha_example.cc before reading this file. + Reminder: The example storage engine implements all methods that are *required* + to be implemented. For a full list of all methods that you can implement, see + handler.h. + + @see + /sql/handler.h and /storage/example/ha_example.cc */ #ifdef USE_PRAGMA_INTERFACE #pragma interface /* gcc class implementation */ #endif -/* - EXAMPLE_SHARE is a structure that will be shared amoung all open handlers - The example implements the minimum of what you will probably need. +/** @brief + EXAMPLE_SHARE is a structure that will be shared among all open handlers. + This example implements the minimum of what you will probably need. */ typedef struct st_example_share { char *table_name; @@ -36,117 +47,200 @@ typedef struct st_example_share { THR_LOCK lock; } EXAMPLE_SHARE; -/* +/** @brief Class definition for the storage engine */ class ha_example: public handler { - THR_LOCK_DATA lock; /* MySQL lock */ - EXAMPLE_SHARE *share; /* Shared lock info */ + THR_LOCK_DATA lock; ///< MySQL lock + EXAMPLE_SHARE *share; ///< Shared lock info public: ha_example(handlerton *hton, TABLE_SHARE *table_arg); ~ha_example() { } - /* The name that will be used for display purposes */ + + /** @brief + The name that will be used for display purposes. + */ const char *table_type() const { return "EXAMPLE"; } - /* - The name of the index type that will be used for display - don't implement this method unless you really have indexes + + /** @brief + The name of the index type that will be used for display. + Don't implement this method unless you really have indexes. */ const char *index_type(uint inx) { return "HASH"; } + + /** @brief + The file extensions. + */ const char **bas_ext() const; - /* - This is a list of flags that says what the storage engine - implements. The current table flags are documented in - handler.h + + /** @brief + This is a list of flags that indicate what functionality the storage engine + implements. The current table flags are documented in handler.h */ ulonglong table_flags() const { return 0; } - /* - This is a bitmap of flags that says how the storage engine + + /** @brief + This is a bitmap of flags that indicates how the storage engine implements indexes. The current index flags are documented in - handler.h. If you do not implement indexes, just return zero - here. + handler.h. If you do not implement indexes, just return zero here. - part is the key part to check. First key part is 0 - If all_parts it's set, MySQL want to know the flags for the combined - index up to and including 'part'. + @details + part is the key part to check. First key part is 0. + If all_parts is set, MySQL wants to know the flags for the combined + index, up to and including 'part'. */ ulong index_flags(uint inx, uint part, bool all_parts) const { return 0; } - /* - unireg.cc will call the following to make sure that the storage engine can - handle the data it is about to send. - - Return *real* limits of your storage engine here. MySQL will do - min(your_limits, MySQL_limits) automatically - There is no need to implement ..._key_... methods if you don't suport - indexes. - */ + /** @brief + unireg.cc will call max_supported_record_length(), max_supported_keys(), + max_supported_key_parts(), uint max_supported_key_length() + to make sure that the storage engine can handle the data it is about to + send. Return *real* limits of your storage engine here; MySQL will do + min(your_limits, MySQL_limits) automatically. + */ uint max_supported_record_length() const { return HA_MAX_REC_LENGTH; } + + /** @brief + unireg.cc will call this to make sure that the storage engine can handle + the data it is about to send. Return *real* limits of your storage engine + here; MySQL will do min(your_limits, MySQL_limits) automatically. + + @details + There is no need to implement ..._key_... methods if your engine doesn't + support indexes. + */ uint max_supported_keys() const { return 0; } + + /** @brief + unireg.cc will call this to make sure that the storage engine can handle + the data it is about to send. Return *real* limits of your storage engine + here; MySQL will do min(your_limits, MySQL_limits) automatically. + + @details + There is no need to implement ..._key_... methods if your engine doesn't + support indexes. + */ uint max_supported_key_parts() const { return 0; } + + /** @brief + unireg.cc will call this to make sure that the storage engine can handle + the data it is about to send. Return *real* limits of your storage engine + here; MySQL will do min(your_limits, MySQL_limits) automatically. + + @details + There is no need to implement ..._key_... methods if your engine doesn't + support indexes. + */ uint max_supported_key_length() const { return 0; } - /* + + /** @brief Called in test_quick_select to determine if indexes should be used. */ virtual double scan_time() { return (double) (stats.records+stats.deleted) / 20.0+10; } - /* - The next method will never be called if you do not implement indexes. + + /** @brief + This method will never be called if you do not implement indexes. */ virtual double read_time(ha_rows rows) { return (double) rows / 20.0+1; } /* - Everything below are methods that we implment in ha_example.cc. + Everything below are methods that we implement in ha_example.cc. Most of these methods are not obligatory, skip them and MySQL will treat them as not implemented */ + /** @brief + We implement this in ha_example.cc; it's a required method. + */ int open(const char *name, int mode, uint test_if_locked); // required + + /** @brief + We implement this in ha_example.cc; it's a required method. + */ int close(void); // required + /** @brief + We implement this in ha_example.cc. It's not an obligatory method; + skip it and and MySQL will treat it as not implemented. + */ int write_row(byte * buf); + + /** @brief + We implement this in ha_example.cc. It's not an obligatory method; + skip it and and MySQL will treat it as not implemented. + */ int update_row(const byte * old_data, byte * new_data); + + /** @brief + We implement this in ha_example.cc. It's not an obligatory method; + skip it and and MySQL will treat it as not implemented. + */ int delete_row(const byte * buf); + + /** @brief + We implement this in ha_example.cc. It's not an obligatory method; + skip it and and MySQL will treat it as not implemented. + */ int index_read(byte * buf, const byte * key, uint key_len, enum ha_rkey_function find_flag); + + /** @brief + We implement this in ha_example.cc. It's not an obligatory method; + skip it and and MySQL will treat it as not implemented. + */ int index_next(byte * buf); + + /** @brief + We implement this in ha_example.cc. It's not an obligatory method; + skip it and and MySQL will treat it as not implemented. + */ int index_prev(byte * buf); + + /** @brief + We implement this in ha_example.cc. It's not an obligatory method; + skip it and and MySQL will treat it as not implemented. + */ int index_first(byte * buf); + + /** @brief + We implement this in ha_example.cc. It's not an obligatory method; + skip it and and MySQL will treat it as not implemented. + */ int index_last(byte * buf); - /* - unlike index_init(), rnd_init() can be called two times - without rnd_end() in between (it only makes sense if scan=1). - then the second call should prepare for the new table scan - (e.g if rnd_init allocates the cursor, second call should - position it to the start of the table, no need to deallocate - and allocate it again + + /** @brief + Unlike index_init(), rnd_init() can be called two consecutive times + without rnd_end() in between (it only makes sense if scan=1). In this + case, the second call should prepare for the new table scan (e.g if + rnd_init() allocates the cursor, the second call should position the + cursor to the start of the table; no need to deallocate and allocate + it again. This is a required method. */ int rnd_init(bool scan); //required int rnd_end(); - int rnd_next(byte *buf); //required - int rnd_pos(byte * buf, byte *pos); //required - void position(const byte *record); //required - int info(uint); //required - + int rnd_next(byte *buf); ///< required + int rnd_pos(byte * buf, byte *pos); ///< required + void position(const byte *record); ///< required + int info(uint); ///< required int extra(enum ha_extra_function operation); - int external_lock(THD *thd, int lock_type); //required + int external_lock(THD *thd, int lock_type); ///< required int delete_all_rows(void); ha_rows records_in_range(uint inx, key_range *min_key, key_range *max_key); int delete_table(const char *from); int rename_table(const char * from, const char * to); int create(const char *name, TABLE *form, - HA_CREATE_INFO *create_info); //required + HA_CREATE_INFO *create_info); ///< required THR_LOCK_DATA **store_lock(THD *thd, THR_LOCK_DATA **to, - enum thr_lock_type lock_type); //required -}; - + enum thr_lock_type lock_type); ///< required |