ha_example.cc File Reference

The ha_example engine is a stubbed storage engine for example purposes only; it does nothing at this point. More...

#include "storage/example/ha_example.h"
#include "my_dbug.h"
#include "mysql/plugin.h"
#include "sql/sql_class.h"
#include "sql/sql_plugin.h"
#include "typelib.h"

Classes
struct	example_vars_t

Functions
static handler *	example_create_handler (handlerton *hton, TABLE_SHARE *table, bool partitioned, MEM_ROOT *mem_root)
static bool	example_is_supported_system_table (const char *db, const char *table_name, bool is_sql_layer_system_table)
	Check if the given db.tablename is a system table for this SE. More...
static int	example_init_func (void *p)
static int	example_deinit_func (void *p)
static	MYSQL_THDVAR_STR (last_create_thdvar, PLUGIN_VAR_MEMALLOC, nullptr, nullptr, nullptr, nullptr)
static	MYSQL_THDVAR_UINT (create_count_thdvar, 0, nullptr, nullptr, nullptr, 0, 0, 1000, 0)
static	MYSQL_SYSVAR_ENUM (enum_var, srv_enum_var, PLUGIN_VAR_RQCMDARG, "Sample ENUM system variable.", nullptr, nullptr, 0, &enum_var_typelib)
static	MYSQL_SYSVAR_ULONG (ulong_var, srv_ulong_var, PLUGIN_VAR_RQCMDARG, "0..1000", nullptr, nullptr, 8, 0, 1000, 0)
static	MYSQL_SYSVAR_DOUBLE (double_var, srv_double_var, PLUGIN_VAR_RQCMDARG, "0.500000..1000.500000", nullptr, nullptr, 8.5, 0.5, 1000.5, 0)
static	MYSQL_THDVAR_DOUBLE (double_thdvar, PLUGIN_VAR_RQCMDARG, "0.500000..1000.500000", nullptr, nullptr, 8.5, 0.5, 1000.5, 0)
static	MYSQL_SYSVAR_INT (signed_int_var, srv_signed_int_var, PLUGIN_VAR_RQCMDARG, "INT_MIN..INT_MAX", nullptr, nullptr, -10, INT_MIN, INT_MAX, 0)
static	MYSQL_THDVAR_INT (signed_int_thdvar, PLUGIN_VAR_RQCMDARG, "INT_MIN..INT_MAX", nullptr, nullptr, -10, INT_MIN, INT_MAX, 0)
static	MYSQL_SYSVAR_LONG (signed_long_var, srv_signed_long_var, PLUGIN_VAR_RQCMDARG, "LONG_MIN..LONG_MAX", nullptr, nullptr, -10, LONG_MIN, LONG_MAX, 0)
static	MYSQL_THDVAR_LONG (signed_long_thdvar, PLUGIN_VAR_RQCMDARG, "LONG_MIN..LONG_MAX", nullptr, nullptr, -10, LONG_MIN, LONG_MAX, 0)
static	MYSQL_SYSVAR_LONGLONG (signed_longlong_var, srv_signed_longlong_var, PLUGIN_VAR_RQCMDARG, "LLONG_MIN..LLONG_MAX", nullptr, nullptr, -10, LLONG_MIN, LLONG_MAX, 0)
static	MYSQL_THDVAR_LONGLONG (signed_longlong_thdvar, PLUGIN_VAR_RQCMDARG, "LLONG_MIN..LLONG_MAX", nullptr, nullptr, -10, LLONG_MIN, LLONG_MAX, 0)
static int	show_func_example (MYSQL_THD, SHOW_VAR *var, char *buf)
	mysql_declare_plugin (example)

Variables
handlerton *	example_hton
static st_handler_tablename	ha_example_system_tables []
struct st_mysql_storage_engine	example_storage_engine
static ulong	srv_enum_var = 0
static ulong	srv_ulong_var = 0
static double	srv_double_var = 0
static int	srv_signed_int_var = 0
static long	srv_signed_long_var = 0
static longlong	srv_signed_longlong_var = 0
const char *	enum_var_names [] = {"e1", "e2", NullS}
TYPELIB	enum_var_typelib
static SYS_VAR *	example_system_variables []
example_vars_t	example_vars = {100, 20.01, "three hundred", true, false, 8250}
static SHOW_VAR	show_status_example []
static SHOW_VAR	show_array_example []
static SHOW_VAR	func_status []
	mysql_declare_plugin_end

Detailed Description

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.h.

ha_example will let you create/open/delete tables, but nothing further (for example, indexes are not supported nor can data be stored in the table). Use this example as a template for implementing the same functionality in your own storage engine. You can enable the example storage engine in your build by doing the following during your build process:
./configure –with-example-storage-engine

Once this is done, MySQL will let you create tables with:
CREATE TABLE <table name> (...) ENGINE=EXAMPLE;

The example storage engine is set up to use table locks. It implements an example "SHARE" that is inserted into a hash by table name. You can use this to store information of state that any example handler object will be able to see when it is using that table.

Please read the object definition in ha_example.h before reading the rest of this file.

Note

When you create an EXAMPLE table, the MySQL Server creates a table .frm (format) file in the database directory, using the table name as the file name as is customary with MySQL. No other files are created. To get an idea of what occurs, here is an example select that would do a scan of an entire table:

ha_example::store_lock
ha_example::external_lock
ha_example::info
ha_example::rnd_init
ha_example::extra
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::extra
ha_example::external_lock
ha_example::extra
ENUM HA_EXTRA_RESET        Reset database to after open

Here you see that the example storage engine has 9 rows called before rnd_next signals that it has reached the end of its data. Also note that the table in question was already opened; had it not been open, a call to ha_example::open() would also have been necessary. Calls to ha_example::extra() are hints as to what will be occurring to the request.

A Longer Example can be found called the "Skeleton Engine" which can be found on TangentOrg. It has both an engine and a full build environment for building a pluggable storage engine.

Happy coding!
-Brian

Function Documentation

example_create_handler()

static handler * example_create_handler ( handlerton *  hton, TABLE_SHARE *  table, bool  partitioned, MEM_ROOT *  mem_root  )

static

example_deinit_func()

static int example_deinit_func ( void *  p )

static

example_init_func()

static int example_init_func ( void *  p )

static

example_is_supported_system_table()

static bool example_is_supported_system_table ( const char *  db, const char *  table_name, bool  is_sql_layer_system_table  )

static

Check if the given db.tablename is a system table for this SE.

Parameters

db	Database name to check.
table_name	table name to check.
is_sql_layer_system_table	if the supplied db.table_name is a SQL layer system table.

Return values

true	Given db.table_name is supported system table.
false	Given db.table_name is not a supported system table.

mysql_declare_plugin()

mysql_declare_plugin

(

example

)

MYSQL_SYSVAR_DOUBLE()

static MYSQL_SYSVAR_DOUBLE ( double_var  , srv_double_var  , PLUGIN_VAR_RQCMDARG  , "0.500000..1000.500000"  , nullptr  , nullptr  , 8.  5, 0.  5, 1000.  5, 0    )

static

MYSQL_SYSVAR_ENUM()

static MYSQL_SYSVAR_ENUM ( enum_var  , srv_enum_var  , PLUGIN_VAR_RQCMDARG  , "Sample ENUM system variable."  , nullptr  , nullptr  , 0  , &  enum_var_typelib  )

static

MYSQL_SYSVAR_INT()

static MYSQL_SYSVAR_INT ( signed_int_var  , srv_signed_int_var  , PLUGIN_VAR_RQCMDARG  , "INT_MIN..INT_MAX"  , nullptr  , nullptr  , -  10, INT_MIN  , INT_MAX  , 0    )

static

MYSQL_SYSVAR_LONG()

static MYSQL_SYSVAR_LONG ( signed_long_var  , srv_signed_long_var  , PLUGIN_VAR_RQCMDARG  , "LONG_MIN..LONG_MAX"  , nullptr  , nullptr  , -  10, LONG_MIN  , LONG_MAX  , 0    )

static

MYSQL_SYSVAR_LONGLONG()

static MYSQL_SYSVAR_LONGLONG ( signed_longlong_var  , srv_signed_longlong_var  , PLUGIN_VAR_RQCMDARG  , "LLONG_MIN..LLONG_MAX"  , nullptr  , nullptr  , -  10, LLONG_MIN  , LLONG_MAX  , 0    )

static

MYSQL_SYSVAR_ULONG()

static MYSQL_SYSVAR_ULONG ( ulong_var  , srv_ulong_var  , PLUGIN_VAR_RQCMDARG  , "0..1000"  , nullptr  , nullptr  , 8  , 0  , 1000  , 0    )

static

MYSQL_THDVAR_DOUBLE()

static MYSQL_THDVAR_DOUBLE ( double_thdvar  , PLUGIN_VAR_RQCMDARG  , "0.500000..1000.500000"  , nullptr  , nullptr  , 8.  5, 0.  5, 1000.  5, 0    )

static

MYSQL_THDVAR_INT()

static MYSQL_THDVAR_INT ( signed_int_thdvar  , PLUGIN_VAR_RQCMDARG  , "INT_MIN..INT_MAX"  , nullptr  , nullptr  , -  10, INT_MIN  , INT_MAX  , 0    )

static

MYSQL_THDVAR_LONG()

static MYSQL_THDVAR_LONG ( signed_long_thdvar  , PLUGIN_VAR_RQCMDARG  , "LONG_MIN..LONG_MAX"  , nullptr  , nullptr  , -  10, LONG_MIN  , LONG_MAX  , 0    )

static

MYSQL_THDVAR_LONGLONG()

static MYSQL_THDVAR_LONGLONG ( signed_longlong_thdvar  , PLUGIN_VAR_RQCMDARG  , "LLONG_MIN..LLONG_MAX"  , nullptr  , nullptr  , -  10, LLONG_MIN  , LLONG_MAX  , 0    )

static

MYSQL_THDVAR_STR()

static MYSQL_THDVAR_STR ( last_create_thdvar  , PLUGIN_VAR_MEMALLOC  , nullptr  , nullptr  , nullptr  , nullptr    )

static

MYSQL_THDVAR_UINT()

static MYSQL_THDVAR_UINT ( create_count_thdvar  , 0  , nullptr  , nullptr  , nullptr  , 0  , 0  , 1000  , 0    )

static

show_func_example()

static int show_func_example ( MYSQL_THD  , SHOW_VAR *  var, char *  buf  )

static

Variable Documentation

enum_var_names

const char* enum_var_names[] = {"e1", "e2", NullS}

enum_var_typelib

TYPELIB enum_var_typelib

Initial value:

= {array_elements(enum_var_names) - 1,
                            "enum_var_typelib", enum_var_names, nullptr}

example_hton

handlerton* example_hton

example_storage_engine

struct st_mysql_storage_engine example_storage_engine

Initial value:

= {
    MYSQL_HANDLERTON_INTERFACE_VERSION}

example_system_variables

SYS_VAR* example_system_variables[]

static

Initial value:

= {
    MYSQL_SYSVAR(enum_var),
    MYSQL_SYSVAR(ulong_var),
    MYSQL_SYSVAR(double_var),
    MYSQL_SYSVAR(double_thdvar),
    MYSQL_SYSVAR(last_create_thdvar),
    MYSQL_SYSVAR(create_count_thdvar),
    MYSQL_SYSVAR(signed_int_var),
    MYSQL_SYSVAR(signed_int_thdvar),
    MYSQL_SYSVAR(signed_long_var),
    MYSQL_SYSVAR(signed_long_thdvar),
    MYSQL_SYSVAR(signed_longlong_var),
    MYSQL_SYSVAR(signed_longlong_thdvar),
    nullptr}

example_vars

example_vars_t example_vars = {100, 20.01, "three hundred", true, false, 8250}

func_status

SHOW_VAR func_status[]

static

Initial value:

= {
    {"example_func_example", (char *)show_func_example, SHOW_FUNC,
     SHOW_SCOPE_GLOBAL},
    {"example_status_var5", (char *)&example_vars.var5, SHOW_BOOL,
     SHOW_SCOPE_GLOBAL},
    {"example_status_var6", (char *)&example_vars.var6, SHOW_LONG,
     SHOW_SCOPE_GLOBAL},
    {"example_status", (char *)show_array_example, SHOW_ARRAY,
     SHOW_SCOPE_GLOBAL},
    {nullptr, nullptr, SHOW_UNDEF, SHOW_SCOPE_UNDEF}}

ha_example_system_tables

st_handler_tablename ha_example_system_tables[]

static

Initial value:

= {
    {(const char *)nullptr, (const char *)nullptr}}

mysql_declare_plugin_end

mysql_declare_plugin_end

show_array_example

SHOW_VAR show_array_example[]

static

Initial value:

= {
    {"array", (char *)show_status_example, SHOW_ARRAY, SHOW_SCOPE_GLOBAL},
    {"var3", (char *)&example_vars.var3, SHOW_CHAR, SHOW_SCOPE_GLOBAL},
    {"var4", (char *)&example_vars.var4, SHOW_BOOL, SHOW_SCOPE_GLOBAL},
    {nullptr, nullptr, SHOW_UNDEF, SHOW_SCOPE_UNDEF}}

show_status_example

SHOW_VAR show_status_example[]

static

Initial value:

= {
    {"var1", (char *)&example_vars.var1, SHOW_LONG, SHOW_SCOPE_GLOBAL},
    {"var2", (char *)&example_vars.var2, SHOW_DOUBLE, SHOW_SCOPE_GLOBAL},
    {nullptr, nullptr, SHOW_UNDEF,
     SHOW_SCOPE_UNDEF}  
}

srv_double_var

double srv_double_var = 0

static

srv_enum_var

ulong srv_enum_var = 0

static

srv_signed_int_var

int srv_signed_int_var = 0

static

srv_signed_long_var

long srv_signed_long_var = 0

static

srv_signed_longlong_var

longlong srv_signed_longlong_var = 0

static

srv_ulong_var

ulong srv_ulong_var = 0

static