16. 编写自定义存储引擎

在执行任何读取或写操作之前，调用store_lock()函数。

将锁定添加到表锁定处理程序之前（请参见thr_lock.c），mysqld将用请求的锁调用存储锁定。目前，存储锁定能将写锁定更改为读锁定（或其他锁定），忽略锁定（如果不打算使用MySQL锁定的话），或为很多表添加锁定（就像使用MERGE处理程序时作的那样）。

例如，Berkeley DB能将所有的WRITE锁定更改为TL_WRITE_ALLOW_WRITE（表示我们正在执行WRITES，但我们仍允许其他人员进行操作）。

释放锁定时，也将调用store_lock()，在这种情况下，通常不需做任何事。

在某些特殊情况下，MySQL可能会发送对TL_IGNORE的请求。这意味着我们正在请求与上次相同的锁定，这也应被忽略（当我们打开了表的某一部分时，如果其他人执行了表刷新操作，就会出现该情况，此时，mysqld将关闭并再次打开表，然后获取与上次相同的锁定）。我们打算在将来删除该特性。

可能的锁定类型定义于includes/thr_lock.h中，并列在下面：

enum thr_lock_type

{

         TL_IGNORE=-1,

                    TL_UNLOCK,                             /* UNLOCK ANY LOCK */

                    TL_READ,                                 /* Read lock */

                    TL_READ_WITH_SHARED_LOCKS,  

         TL_READ_HIGH_PRIORITY,      /* High prior. than TL_WRITE. Allow concurrent insert */

         TL_READ_NO_INSERT,                /* READ, Don't allow concurrent insert */

         TL_WRITE_ALLOW_WRITE,                   /*   Write lock, but allow other threads to read / write. */

         TL_WRITE_ALLOW_READ,        /*       Write lock, but allow other threads to read / write. */

         TL_WRITE_CONCURRENT_INSERT, /* WRITE lock used by concurrent insert. */

         TL_WRITE_DELAYED,                 /* Write used by INSERT DELAYED.  Allows READ locks */

         TL_WRITE_LOW_PRIORITY,            /* WRITE lock that has lower priority than TL_READ */

         TL_WRITE,                         /* Normal WRITE lock */

         TL_WRITE_ONLY               /* Abort new lock request with an error */

};  

实际的锁定处理因锁定实施的不同而不同，你可以选择某些请求的锁定类型或不选择任何锁定类型，并根据情况恰当地代入你自己的方法。下面给出了1个CSV存储引擎实施示例：

THR_LOCK_DATA **ha_tina::store_lock(THD *thd,

                                     THR_LOCK_DATA **to,

                                     enum thr_lock_type lock_type)

 {

   if (lock_type != TL_IGNORE && lock.type == TL_UNLOCK)

     lock.type=lock_type;

   *to++= &lock;

   return to;

 }  

external_lock()函数是在事务开始时调用的，或发出LOCK TABLES语句时调用的，用于事务性存储引擎。

在sql/ha_innodb.cc和sql/ha_berkeley.cc文件中，可找到使用external_lock()的示例，但大多数存储引擎简单地返回0，就像EXAMPLE存储引擎那样：

int ha_example::external_lock(THD *thd, int lock_type)

 {

   DBUG_ENTER("ha_example::external_lock");

   DBUG_RETURN(0);

 }

在任何表扫描之前调用的函数是rnd_init()函数。函数rnd_init()用于为表扫描作准备，将计数器和指针复位为表的开始状态。

下述示例来自CSV存储引擎：

int ha_tina::rnd_init(bool scan)
{
DBUG_ENTER("ha_tina::rnd_init");
current_position= next_position= 0;
records= 0;
chain_ptr= chain;
DBUG_RETURN(0);
}

ulonglong data_file_length;           /* Length off data file */

ulonglong max_data_file_length;       /* Length off data file */

ulonglong index_file_length;

ulonglong max_index_file_length;

ulonglong delete_length;              /* Free bytes */

ulonglong auto_increment_value;

ha_rows records;                      /* Records in table */

ha_rows deleted;                      /* Deleted records */

ulong raid_chunksize;

ulong mean_rec_length;         /* physical reclength */

time_t create_time;                   /* When table was created */

time_t check_time;

time_t update_time;  

执行某些操作之前，应调用extra()函数，以便为存储引擎就如何执行特定操作予以提示。

额外调用中的提示实施不是强制性的，大多数存储引擎均返回0：

int ha_tina::extra(enum ha_extra_function operation)
{
DBUG_ENTER("ha_tina::extra");
DBUG_RETURN(0);
}

完成表的初始化操作后，MySQL服务器将调用处理程序的rnd_next()函数，每两个扫描行调用1次，直至满足了服务器的搜索条件或到达文件结尾为止，在后一种情况下，处理程序将返回HA_ERR_END_OF_FILE。

rnd_next()函数有一个名为*buf的单字节数组参数。对于*buf参数，必须按内部MySQL格式用表行的内容填充它。

服务器采用了三种数据格式：固定长度行，可变长度行，以及具有BLOB指针的可变长度行。对于每种格式，各列将按照它们由CREATE TABLE语句定义的顺序显示（表定义保存在.frm文件中，优化程序和处理程序均能从相同的源，即TABLE结构，访问表的元数据）。

每种格式以每列1比特的"NULL bitmap"开始。对于含6个列的表，其bitmap为1字节，对于含9～16列的表，其bitmap为2字节，依此类推。要想指明特定的值是NULL，应将该列NULL位设置为1。

当NULL bitmap逐个进入列后，每列将具有MySQL手册的“MySQL数据类型”一节中指定的大小。在服务器中，列的数据类型定义在sql/field.cc文件中。对于固定长度行格式，列将简单地逐个放置。对于可变长度行，VARCHAR列将被编码为1字节长，后跟字符串。对于具有BLOB列的可变长度行，每个blob由两部分表示：首先是表示BLOB实际大小的整数，然后是指向内存中BLOB的指针。

在任何表处理程序中从rnd_next()开始，可找到行转换（或“包装”）的示例。例如，在ha_tina.cc中，find_current_row()内的代码给出了使用TABLE结构（由表指向的）和字符串对象（命名缓冲）包装字符数据（来自CSV文件）的方法。将行写回磁盘需要反向转换，从内部格式解包。

下述示例来自CSV存储引擎：

int ha_tina::rnd_next(byte *buf)

 {

   DBUG_ENTER("ha_tina::rnd_next");

   statistic_increment(table->in_use->status_var.ha_read_rnd_next_count, &LOCK_status);

   current_position= next_position;

   if (!share->mapped_file)

     DBUG_RETURN(HA_ERR_END_OF_FILE);

   if (HA_ERR_END_OF_FILE == find_current_row(buf) )

     DBUG_RETURN(HA_ERR_END_OF_FILE);

   records++;

   DBUG_RETURN(0);

 }  

对于从内部行格式到CSV行格式的转换，它是在find_current_row()函数中执行的。

int ha_tina::find_current_row(byte *buf)

 {

   byte *mapped_ptr= (byte *)share->mapped_file + current_position;

   byte *end_ptr;

   DBUG_ENTER("ha_tina::find_current_row");

   /* EOF should be counted as new line */

   if ((end_ptr=  find_eoln(share->mapped_file, current_position,

                            share->file_stat.st_size)) == 0)

     DBUG_RETURN(HA_ERR_END_OF_FILE);

   for (Field **field=table->field ; *field ; field++)

   {

     buffer.length(0);

     mapped_ptr++; // Increment past the first quote

     for(;mapped_ptr != end_ptr; mapped_ptr++)

     {

       // Need to convert line feeds!

       if (*mapped_ptr == '"' &&

           (((mapped_ptr[1] == ',') && (mapped_ptr[2] == '"')) ||

            (mapped_ptr == end_ptr -1 )))

       {

         mapped_ptr += 2; // Move past the , and the "

         break;

       }

       if (*mapped_ptr == '\' && mapped_ptr != (end_ptr - 1))

       {

         mapped_ptr++;

         if (*mapped_ptr == 'r')

           buffer.append('r');

         else if (*mapped_ptr == 'n' )

           buffer.append('n');

         else if ((*mapped_ptr == '\') || (*mapped_ptr == '"'))

           buffer.append(*mapped_ptr);

         else  /* This could only happed with an externally created file */

         {

           buffer.append('\');

           buffer.append(*mapped_ptr);

         }

       }

       else

         buffer.append(*mapped_ptr);

     }

     (*field)->store(buffer.ptr(), buffer.length(), system_charset_info);

   }

   next_position= (end_ptr - share->mapped_file)+1;

   /* Maybe use N for null? */

   memset(buf, 0, table->s->null_bytes); /* We do not implement nulls! */

   DBUG_RETURN(0);

 }  

目的

定义存储引擎所使用的文件扩展。

概要

描述

这是bas_ext方法。调用它，可为MySQL服务器提供存储引擎所使用的文件扩展列表。该列表将返回以Null终结的字符串数组。

通过提供扩展列表，在很多情况下，存储引擎能省略delete_table()函数，这是因为MySQL服务器将关闭所有对表的引用，并使用指定的扩展删除所有文件。

参数

该函数无参数。

返回值

用法

static const char *ha_tina_exts[] =
{
".CSV",
NullS
};
const char **ha_tina::bas_ext() const
{
return ha_tina_exts;
}

默认实施

static const char *ha_example_exts[] = {
NullS
};
const char **ha_example::bas_ext() const
{
return ha_example_exts;
}

目的

关闭打开的表。

概要

描述

这是close方法。

关闭表。这是释放任何已分配资源的恰当时机。

从sql_base.cc、sql_select.cc和table.cc调用它。在sql_select.cc中，它仅用于关闭临时表，或在将临时表转换为myisam表的过程中关闭表。关于sql_base.cc，请查看close_data_tables()。

参数

返回值

无返回值。

用法

取自CSV引擎的示例：

int ha_example::close(void)
{
DBUG_ENTER("ha_example::close");
DBUG_RETURN(free_share(share));
}

目的

创建新表。

概要

描述

这是create方法。

调用create()以创建表。变量名称为表的名称。调用create()时，不需要打开表。此外，由于已创建了.frm文件，不推荐调整create_info。

由ha_create_table()从handle.cc中调用。

参数

返回值

无返回值。

用法

CSV搜索引擎示例：

int ha_tina::create(const char *name, TABLE *table_arg,
HA_CREATE_INFO *create_info)
{
char name_buff[FN_REFLEN];
File create_file;
DBUG_ENTER("ha_tina::create");
if ((create_file= my_create(fn_format(name_buff, name, "", ".CSV",
MY_REPLACE_EXT|MY_UNPACK_FILENAME),0,
O_RDWR | O_TRUNC,MYF(MY_WME))) < 0)
DBUG_RETURN(-1);
my_close(create_file,MYF(0));
DBUG_RETURN(0);
}

目的

删除行。

概要

描述

这是delete_row方法。

Buf包含删除行的副本。调用了当前行后，服务器将立刻调用它（通过前一个rnd_next()或索引调用）。如果存在指向上一行的指针，或能够访问 主键，删除操作将更为容易。请记住，服务器不保证连续删除。可以使用ORDER BY子句。

在sql_acl.cc和sql_udf.cc中调用，以管理内部的表信息。在sql_delete.cc、sql_insert.cc和sql_select.cc中调用。在sql_select中，它用于删除副本，而在插入操作中，它用于REPLACE调用。

参数

返回值

无返回值。

用法

默认实施

{ return
HA_ERR_WRONG_COMMAND; }

目的

用来自bas_ext()的扩展删除所有文件。

概要

描述

这是delete_table方法。

用于删除表。调用delete_table()时，所有已打开的对该表的引用均将被关闭（并释放全局共享的引用）。变量名称为表名。此时，需要删除任何已创建的文件。

如果未实施它，将从handler.cc调用默认的delete_table()，并用bas_ext()返回的文件扩展删除所有文件。假定处理程序返回的扩展比文件实际使用的多。

由delete_table和ha_create_table()从handler.cc调用。如果为存储引擎指定了table_flag HA_DROP_BEFORE_CREATE，仅在创建过程中使用。

参数

返回值

用法

目的

为事务处理表锁定。

概要

描述

这是external_lock方法。

在lock.cc中“用于mysql的锁定函数”一节，给出了关于该议题的额外注释，值的一读。

在表上创建锁定。如果实施了能处理事务的存储引擎，请查看ha_berkely.cc，以了解如何执行该操作的方法。否则，应考虑在此调用flock()。

由lock_external()和unlock_external()从lock.cc中调用。也能由copy_data_between_tables()从sql_table.cc中调用。

参数

返回值

无返回值。

默认实施

{ return 0; }

目的

将提示从服务器传递给存储引擎。

概要

描述

这是extra方法。

无论何时，当服务器希望将提示发送到存储引擎时，将调用extra()。MyISAM引擎实现了大多数提示。ha_innodb.cc给出了最详尽的提示列表。

参数

返回值

无返回值。

用法

默认实施

默认情况下，存储引擎倾向于不实施任何提示。

{ return 0; }

目的

提示存储引擎通报统计信息。

概要

描述

这是info方法。

::info()用于将信息返回给优化程序。目前，该表处理程序未实施实际需要的大多数字段。SHOW也能利用该数据。注意，或许你打算在你的代码中包含下述内容“if (records > 2) records = 2”。原因在于，服务器仅优化具有一条记录的情形。如果在表扫描过程中，你不清楚记录的数目，最好将记录数设为2，以便能够返回尽可能多的所需记录。除了记录外，你或许还希望设置其他变量，包括：删除的记录，data_file_length，index_file_length，delete_length，check_time。更多信息，请参见handler.h中的公共变量。

在下述文件中调用：filesort.cc ha_heap.cc item_sum.cc opt_sum.cc sql_delete.cc sql_delete.cc sql_derived.cc sql_select.cc sql_select.cc sql_select.cc sql_select.cc sql_select.cc sql_show.cc sql_show.cc sql_show.cc sql_show.cc sql_table.cc sql_union.cc sql_update.cc

参数

返回值

无返回值。

用法

该示例取自CSV存储引擎：

void ha_tina::info(uint flag)
{
DBUG_ENTER("ha_tina::info");
/* This is a lie, but you don't want the optimizer to see zero or 1 */
if (records < 2)
records= 2;
DBUG_VOID_RETURN;
}

目的

打开表。

概要

描述

这是open方法。

用于打开表。名称是文件的名称。在需要打开表时打开它。例如，当请求在表上执行选择操作时（对于每一请求，表未打开并被关闭，对其进行高速缓冲处理）。

由handler::ha_open()从handler.cc中调用。通过调用ha_open()，然后调用处理程序相关的open()，服务器打开所有表。

对于处理程序对象，将作为初始化的一部分并在将其用于正常查询之前打开它（并非总在元数据变化之前）。如果打开了对象，在删除之前还将关闭它。

这是open方法。调用open以打开数据库表。

第1个参数是要打开的表的名称。第2个参数决定了要打开的文件或将要执行的操作。这类值定义于handler.h中，为了方便起见在此列出：

        #define HA_OPEN_KEYFILE                 1

        #define HA_OPEN_RNDFILE                 2

        #define HA_GET_INDEX              4

        #define HA_GET_INFO                 8     /* do a ha_info() after open */

        #define HA_READ_ONLY              16    /* File opened as readonly */

        #define HA_TRY_READ_ONLY        32    /* Try readonly if can't open with read and write */

        #define HA_WAIT_IF_LOCKED       64      /* Wait if locked on open */

        #define HA_ABORT_IF_LOCKED    128       /* skip if locked on open.*/

        #define HA_BLOCK_LOCK             256   /* unlock when reading some records */

        #define HA_OPEN_TEMPORARY       512

最后的选项规定了在打开表之前是否应检查表上的锁定。

典型情况下，存储引擎需要实现某种形式的共享访问控制，以防止多线程环境下的文件损坏。关于如何实现文件锁定的示例，请参见sql/examples/ha_tina.cc的get_share()和free_share()方法。

参数

返回值

无返回值。

用法

该示例取自CSV存储引擎：

int ha_tina::open(const char *name, int mode, uint test_if_locked)
{
DBUG_ENTER("ha_tina::open");
if (!(share= get_share(name, table)))
DBUG_RETURN(1);
thr_lock_data_init(&share->lock,&lock,NULL);
ref_length=sizeof(off_t);
DBUG_RETURN(0);
}

目的

为表扫描功能初始化处理程序。

概要

描述

这是rnd_init方法。

当系统希望存储引擎执行表扫描时，将调用rnd_init()。

与index_init()不同，rnd_init()可以调用两次，两次调用之间不使用rnd_end()（仅当scan=1时才有意义）。随后，第2次调用应准备好新的表扫描。例如，如果rnd_init分配了光标，第2次调用应将光标定位于表的开始部分，不需要撤销分配并再次分配。

从下述文件调用：filesort.cc, records.cc, sql_handler.cc, sql_select.cc, sql_table.cc, 和sql_update.cc。

参数

返回值

无返回值。

用法

该示例取自CSV存储引擎：

int ha_tina::rnd_init(bool scan)
{
DBUG_ENTER("ha_tina::rnd_init");
current_position= next_position= 0;
records= 0;
chain_ptr= chain;
DBUG_RETURN(0);
}

目的

从表中读取下一行，并将其返回服务器。

概要

描述

这是rnd_next方法。

对于表扫描的每一行调用它。耗尽记录时，应返回HA_ERR_END_OF_FILE。用行信息填充buff。表的字段结构是以服务器能理解的方式将数据保存到buf中的键。

从下述文件调用：filesort.cc, records.cc, sql_handler.cc, sql_select.cc, sql_table.cc, 和sql_update.cc。

参数

返回值

无返回值。

用法

下述示例取自ARCHIVE存储引擎：

int ha_archive::rnd_next(byte *buf)
{
int rc;
DBUG_ENTER("ha_archive::rnd_next");
if (share->crashed)
DBUG_RETURN(HA_ERR_CRASHED_ON_USAGE);
if (!scan_rows)
DBUG_RETURN(HA_ERR_END_OF_FILE);
scan_rows--;
statistic_increment(table->in_use->status_var.ha_read_rnd_next_count,
&LOCK_status);
current_position= gztell(archive);
rc= get_row(archive, buf);
if (rc != HA_ERR_END_OF_FILE)
records++;
DBUG_RETURN(rc);
}

目的

创建和释放表锁定。

概要

描述

这是store_lock方法。

下面介绍了关于handler::store_lock()的概念：

该语句决定了在表上需要何种锁定。对于updates/deletes/inserts，我们得到WRITE锁定；对于SELECT...，我们得到读锁定。

将锁定添加到表锁定处理程序之前（请参见thr_lock.c），mysqld将用请求的锁定调用存储锁定。目前，存储锁定能将写锁定更改为读锁定（或某些其他锁定），忽略锁定（如果不打算使用MySQL表锁定），或为很多表添加锁定（就像使用MERGE处理程序时那样）。

例如，Berkeley DB能够将所有的WRITE锁定更改为TL_WRITE_ALLOW_WRITE（表明正在执行WRITES操作，但我们仍允许其他人执行操作）。

释放锁定时，也将调用store_lock()。在这种情况下，通常不需要作任何事。

在某些特殊情况下，MySQL可能会发送对TL_IGNORE的请求。这意味着我们正在请求与上次相同的锁定，这也应被忽略（当我们打开了表的某一部分时，如果其他人执行了表刷新操作，就会出现该情况，此时，mysqld将关闭并再次打开表，然后获取与上次相同的锁定）。我们打算在将来删除该特性。

由get_lock_data()从lock.cc中调用。

参数

返回值

无返回值。

用法

下述示例取自ARCHIVE存储引擎：

/*
Below is an example of how to setup row level locking.
*/
THR_LOCK_DATA **ha_archive::store_lock(THD *thd,
THR_LOCK_DATA **to,
enum thr_lock_type lock_type)
{
if (lock_type == TL_WRITE_DELAYED)
delayed_insert= TRUE;
else
delayed_insert= FALSE;
if (lock_type != TL_IGNORE && lock.type == TL_UNLOCK)
{
/*
Here is where we get into the guts of a row level lock.
If TL_UNLOCK is set
If we are not doing a LOCK TABLE or DISCARD/IMPORT
TABLESPACE, then allow multiple writers
*/
if ((lock_type >= TL_WRITE_CONCURRENT_INSERT &&
lock_type <= TL_WRITE) && !thd->in_lock_tables
&& !thd->tablespace_op)
lock_type = TL_WRITE_ALLOW_WRITE;
/*
In queries of type INSERT INTO t1 SELECT ... FROM t2 ...
MySQL would use the lock TL_READ_NO_INSERT on t2, and that
would conflict with TL_WRITE_ALLOW_WRITE, blocking all inserts
to t2. Convert the lock to a normal read lock to allow
concurrent inserts to t2.
*/
if (lock_type == TL_READ_NO_INSERT && !thd->in_lock_tables)
lock_type = TL_READ;
lock.type=lock_type;
}
*to++= &lock;
return to;
}

目的

更新已有行的内容。

概要

描述

这是update_row方法。

old_data将保存前一行的记录，而new_data将保存最新的数据。

如果使用了ORDER BY子句，服务器能够根据排序执行更新操作。不保证连续排序。

目前，new_data不会拥有已更新的auto_increament记录，或已更新的时间戳字段。你可以通过下述方式（例如）完成该操作：if (table->timestamp_field_type & TIMESTAMP_AUTO_SET_ON_UPDATE) table->timestamp_field->set_time(); if (table->next_number_field && record == table->record[0]) update_auto_increment();

从sql_select.cc, sql_acl.cc, sql_update.cc和sql_insert.cc调用。

参数

返回值

无返回值。

用法

默认实施

{ return
HA_ERR_WRONG_COMMAND; }

目的

为表添加新行。

概要

描述

这是write_row方法。

write_row()用于插入行。目前，如果出现大量加载，不会给出任何extra()提示。buf是数据的字节数组，大小为table->s->reclength。

可以使用字段信息从本地字节数组类型提取数据。例如：

for (Field **field=table->field ; *field ; field++) { ... }

BLOB必须特殊处理：

for (ptr= table->s->blob_field, end= ptr + table->s->blob_fields ; ptr != end ; ptr++) 

  { 

        char *data_ptr; 

        uint32 size= ((Field_blob*)table->field[*ptr])->get_length();

        ((Field_blob*)table->field[*ptr])->get_ptr(&data_ptr); 

        ... 

  }

关于以字符串形式提取所有数据的示例，请参见ha_tina.cc。在ha_berkeley.cc中，对于ha_berkeley自己的本地存储类型，给出了一个通过“包装功能”完整保存它的例子。

请参见update_row()关于auto_increments和时间戳的注释。该情形也适用于write_row()。

从item_sum.cc、item_sum.cc、sql_acl.cc、sql_insert.cc、sql_insert.cc、sql_select.cc、sql_table.cc、sql_udf.cc、以及sql_update.cc调用。

参数

返回值

无返回值。

用法

默认实施

{ return
HA_ERR_WRONG_COMMAND; }