MySQL 5.1 Database Reference Guide :: 15.4 Creating the handlerton

Previous / Next / Up / Table of Contents

15.4. Creating the `handlerton`

$8.99

The handlerton (short for “handler singleton”) defines the storage engine and contains function pointers to those functions that apply to the storage engine as a whole, as opposed to functions that work on a per-table basis. Some examples of such functions include transaction functions to handle commits and rollbacks.

Here's an example from the EXAMPLE storage engine:

handlerton example_hton= {
  "EXAMPLE",
  SHOW_OPTION_YES,
  "Example storage engine", 
  DB_TYPE_EXAMPLE_DB,
  NULL,    /* Initialize */
  0,       /* slot */
  0,       /* savepoint size. */
  NULL,    /* close_connection */
  NULL,    /* savepoint */
  NULL,    /* rollback to savepoint */
  NULL,    /* release savepoint */
  NULL,    /* commit */
  NULL,    /* rollback */
  NULL,    /* prepare */
  NULL,    /* recover */
  NULL,    /* commit_by_xid */
  NULL,    /* rollback_by_xid */
  NULL,    /* create_cursor_read_view */
  NULL,    /* set_cursor_read_view */
  NULL,    /* close_cursor_read_view */
  example_create_handler,    /* Create a new handler */
  NULL,    /* Drop a database */
  NULL,    /* Panic call */
  NULL,    /* Release temporary latches */
  NULL,    /* Update Statistics */
  NULL,    /* Start Consistent Snapshot */
  NULL,    /* Flush logs */
  NULL,    /* Show status */
  NULL,    /* Replication Report Sent Binlog */
  HTON_CAN_RECREATE
};

This is the definition of the handlerton from handler.h:

typedef struct
  {
    const char *name;
    SHOW_COMP_OPTION state;
    const char *comment;
    enum db_type db_type;
    bool (*init)();
    uint slot;
    uint savepoint_offset;
    int  (*close_connection)(THD *thd);
    int  (*savepoint_set)(THD *thd, void *sv);
    int  (*savepoint_rollback)(THD *thd, void *sv);
    int  (*savepoint_release)(THD *thd, void *sv);
    int  (*commit)(THD *thd, bool all);
    int  (*rollback)(THD *thd, bool all);
    int  (*prepare)(THD *thd, bool all);
    int  (*recover)(XID *xid_list, uint len);
    int  (*commit_by_xid)(XID *xid);
    int  (*rollback_by_xid)(XID *xid);
    void *(*create_cursor_read_view)();
    void (*set_cursor_read_view)(void *);
    void (*close_cursor_read_view)(void *);
    handler *(*create)(TABLE *table);
    void (*drop_database)(char* path);
    int (*panic)(enum ha_panic_function flag);
    int (*release_temporary_latches)(THD *thd);
    int (*update_statistics)();
    int (*start_consistent_snapshot)(THD *thd);
    bool (*flush_logs)();
    bool (*show_status)(THD *thd, stat_print_fn *print, enum ha_stat_type stat);
    int (*repl_report_sent_binlog)(THD *thd, char *log_file_name, my_off_t end_offset);
    uint32 flags;                                
  } handlerton;

There are a total of 30 handlerton elements, only a few of which are mandatory (specifically the first four elements and the create() function).

The name of the storage engine. This is the name that will be used when creating tables (CREATE TABLE ... ENGINE = FOO;).
The value to be displayed in the status field when a user issues the SHOW STORAGE ENGINES command.
The storage engine comment, a description of the storage engine displayed when using the SHOW STORAGE ENGINES command.
An integer that uniquely identifies the storage engine within the MySQL server. The constants used by the built-in storage engines are defined in the handler.h file. Custom engines should use DB_TYPE_CUSTOM.
A function pointer to the storage engine initializer. This function is only called once when the server starts to allow the storage engine class to perform any housekeeping that is necessary before handlers are instanced.
The slot. Each storage engine has its own memory area (actually a pointer) in the thd, for storing per-connection information. It is accessed as thd->ha_data[foo_hton.slot]. The slot number is initialized by MySQL after foo_init() is called. For more information on the thd, see Section 15.16.3, “Implementing ROLLBACK”.
The savepoint offset. To store per-savepoint data the storage engine is provided with an area of a requested size (0, if no savepoint memory is necessary).

The savepoint offset must be initialized statically to the size of the needed memory to store per-savepoint information. After foo_init it is changed to be an offset to the savepoint storage area and need not be used by the storage engine.

For more information, see Section 15.16.5.1, “Specifying the Savepoint Offset”.
Used by transactional storage engines, clean up any memory allocated in their slot.
A function pointer to the handler's savepoint_set() function. This is used to create a savepoint and store it in memory of the requested size.

For more information, see Section 15.16.5.2, “Implementing the savepoint_set Function”.
A function pointer to the handler's rollback_to_savepoint() function. This is used to return to a savepoint during a transaction. It's only populated for storage engines that support savepoints.

For more information, see Section 15.16.5.3, “Implementing the savepoint_rollback() Function”.
A function pointer to the handler's release_savepoint() function. This is used to release the resources of a savepoint during a transaction. It's optionally populated for storage engines that support savepoints.

For more information, see Section 15.16.5.4, “Implementing the savepoint_release() Function”.
A function pointer to the handler's commit() function. This is used to commit a transaction. It's only populated for storage engines that support transactions.

For more information, see Section 15.16.4, “Implementing COMMIT”.
A function pointer to the handler's rollback() function. This is used to roll back a transaction. It's only populated for storage engines that support transactions.

For more information, see Section 15.16.3, “Implementing ROLLBACK”.
Required for XA transactional storage engines. Prepare transaction for commit.
Required for XA transactional storage engines. Returns a list of transactions that are in the prepared state.
Required for XA transactional storage engines. Commit transaction identified by XID.
Required for XA transactional storage engines. Rollback transaction identified by XID.
Called when a cursor is created to allow the storage engine to create a consistent read view.
Called to switch to a specific consistent read view.
Called to close a specific read view.
MANDATORY - Construct and return a handler instance.

For more information, see Section 15.5, “Handling Handler Instantiation”.
Used if the storage engine needs to perform special steps when a schema is dropped (such as in a storage engine that uses tablespaces).
Cleanup function called during server shutdown and crashes.
InnoDB-specific function.
InnoDB-specific function called at start of SHOW ENGINE InnoDB STATUS.
Function called to begin a consistent read.
Called to indicate that logs should be flushed to reliable storage.
Provides human readable status information on the storage engine for SHOW ENGINE foo STATUS.
InnoDB-specific function used for replication.
Handlerton flags that indicate the capabilities of the storage engine. Possible values are defined in sql/handler.h and copied here:
```
#define HTON_NO_FLAGS                 0
#define HTON_CLOSE_CURSORS_AT_COMMIT (1 << 0)
#define HTON_ALTER_NOT_SUPPORTED     (1 << 1)
#define HTON_CAN_RECREATE            (1 << 2)
#define HTON_FLUSH_AFTER_RENAME      (1 << 3)
#define HTON_NOT_USER_SELECTABLE     (1 << 4)
```
HTON_ALTER_NOT_SUPPORTED is used to indicate that the storage engine cannot accept ALTER TABLE statements. The FEDERATED storage engine is an example.

HTON_FLUSH_AFTER_RENAME indicates that FLUSH LOGS must be called after a table rename.

HTON_NOT_USER_SELECTABLE indicates that the storage engine should not be shown when a user calls SHOW STORAGE ENGINES. Used for system storage engines such as the dummy storage engine for binary logs.

Previous / Next / Up / Table of Contents

15.4. Creating the handlerton

15.4. Creating the `handlerton`