| List: | Internals | « Previous MessageNext Message » | |
| From: | mhillyer | Date: | December 2 2005 10:54pm |
| Subject: | svn commit - mysqldoc@docsrva: r479 - branches/MikePluggable/trunk/refman-5.1 | ||
| View as plain text | |||
Author: mhillyer Date: 2005-12-02 22:54:26 +0100 (Fri, 02 Dec 2005) New Revision: 479 Log: Added some cross linking between sections and the API reference. Corrected problems I caught during a manual review. Modified: branches/MikePluggable/trunk/refman-5.1/custom-engine.xml Modified: branches/MikePluggable/trunk/refman-5.1/custom-engine.xml =================================================================== --- branches/MikePluggable/trunk/refman-5.1/custom-engine.xml 2005-12-02 20:48:51 UTC (rev 478) +++ branches/MikePluggable/trunk/refman-5.1/custom-engine.xml 2005-12-02 21:54:26 UTC (rev 479) @@ -39,8 +39,7 @@ architecture, see <xref linkend="pluggable-storage"/>. </para> - <para> - <emphasis role="bold">Additional resources</emphasis> + <bridgehead>Additional resources</bridgehead> <itemizedlist> @@ -53,8 +52,8 @@ </listitem> </itemizedlist> - </para> + </section> <section id="custom-engine-overview"> @@ -301,10 +300,6 @@ file. Custom engines should use <literal>DB_TYPE_CUSTOM</literal>. </para> - - <remark role="todo"> - [MH] TODO: GET THE ACTUAL CONSTANT - </remark> </listitem> <!-- 5 --> @@ -332,7 +327,8 @@ <literal>thd->ha_data[<replaceable>foo</replaceable>_hton.slot]</literal>. The slot number is initialized by MySQL after <literal><replaceable>foo</replaceable>_init()</literal> is - called. + called. For more information on the <literal>thd</literal>, + see <xref linkend="custom-engine-transactions-rollback"/>. </para> </listitem> @@ -352,6 +348,9 @@ it is changed to be an offset to the savepoint storage area and need not be used by the storage engine. </para> + + <para>For more information, see <xref + linkend="custom-engine-savepoint-offset"/>.</para> </listitem> <!-- 8 --> @@ -372,6 +371,9 @@ create a savepoint and store it in memory of the requested size. </para> + + <para>For more information, see <xref + linkend="custom-engine-savepoint-set"/>.</para> </listitem> <!-- 10 --> @@ -383,6 +385,9 @@ used to return to a savepoint during a transaction. It's only populated for storage engines that support savepoints. </para> + + <para>For more information, see <xref + linkend="custom-engine-savepoint-rollback"/>.</para> </listitem> <!-- 11 --> @@ -395,6 +400,9 @@ transaction. It's optionally populated for storage engines that support savepoints. </para> + + <para>For more information, see <xref + linkend="custom-engine-savepoint-release"/>.</para> </listitem> <!-- 12 --> @@ -406,6 +414,9 @@ a transaction. It's only populated for storage engines that support transactions. </para> + + <para>For more information, see <xref + linkend="custom-engine-transactions-commit"/>.</para> </listitem> <!-- 13 --> @@ -417,6 +428,9 @@ back a transaction. It's only populated for storage engines that support transactions. </para> + + <para>For more information, see <xref + linkend="custom-engine-transactions-rollback"/>.</para> </listitem> <!-- 14 --> @@ -487,6 +501,9 @@ <emphasis>MANDATORY</emphasis> - Construct and return a handler instance. </para> + + <para>For more information, see <xref + linkend="custom-engine-instancing"/>.</para> </listitem> <!-- 22 --> @@ -520,11 +537,7 @@ <listitem> <para> <literal>InnoDB</literal>-specific function called at start of - <literal>SHOW STATUS</literal>. - - <remark> - [SH] SHOW ENGINE INNODB STATUS? - </remark> + <literal>SHOW ENGINE InnoDB STATUS</literal>. </para> </listitem> @@ -785,7 +798,7 @@ <programlisting> typedef struct st_ha_create_information - { +{ CHARSET_INFO *table_charset, *default_table_charset; LEX_STRING connect_string; const char *comment,*password; @@ -801,14 +814,14 @@ enum db_type db_type; enum row_type row_type; uint null_bits; /* NULL bits at start of record */ - uint options; /* OR of HA_CREATE_ options */ + uint options; /* OR of HA_CREATE_ options */ uint raid_type,raid_chunks; uint merge_insert_method; uint extra_size; /* length of extra data segment */ - bool table_existed; /* 1 in create if table existed */ + bool table_existed; /* 1 in create if table existed */ bool frm_only; /* 1 if no ha_create_table() */ bool varchar; /* 1 if table has a VARCHAR */ - } HA_CREATE_INFO; +} HA_CREATE_INFO; </programlisting> <para> @@ -827,7 +840,7 @@ <programlisting> 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"); @@ -840,7 +853,7 @@ my_close(create_file,MYF(0)); DBUG_RETURN(0); - } +} </programlisting> <para> @@ -1001,9 +1014,9 @@ enum thr_lock_type { TL_IGNORE=-1, - TL_UNLOCK, /* UNLOCK ANY LOCK */ - TL_READ, /* Read lock */ - TL_READ_WITH_SHARED_LOCKS, + 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. */ @@ -1028,12 +1041,12 @@ 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; - } +} </programlisting> <para> @@ -1066,10 +1079,10 @@ <programlisting> int ha_example::external_lock(THD *thd, int lock_type) - { +{ DBUG_ENTER("ha_example::external_lock"); DBUG_RETURN(0); - } +} </programlisting> </section> @@ -1093,7 +1106,7 @@ <programlisting> int ha_tina::rnd_init(bool scan) - { +{ DBUG_ENTER("ha_tina::rnd_init"); current_position= next_position= 0; @@ -1101,7 +1114,7 @@ chain_ptr= chain; DBUG_RETURN(0); - } +} </programlisting> <para> @@ -1199,10 +1212,10 @@ <programlisting> int ha_tina::extra(enum ha_extra_function operation) - { +{ DBUG_ENTER("ha_tina::extra"); DBUG_RETURN(0); - } +} </programlisting> </section> @@ -1284,7 +1297,7 @@ <programlisting> 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); @@ -1297,7 +1310,7 @@ records++; DBUG_RETURN(0); - } +} </programlisting> <para> @@ -1308,7 +1321,7 @@ <programlisting> 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"); @@ -1357,7 +1370,7 @@ memset(buf, 0, table->s->null_bytes); /* We do not implement nulls! */ DBUG_RETURN(0); - } +} </programlisting> </section> @@ -1455,7 +1468,7 @@ </programlisting> <para> - Two items of note in the preceding example include the updating of + Three items of note in the preceding example include the updating of table statistics for writes, the setting of the timestamp prior to writing the row, and the updating of <literal>AUTO_INCREMENT</literal> values. @@ -1512,7 +1525,7 @@ <programlisting> int ha_tina::update_row(const byte * old_data, byte * new_data) - { +{ int size; DBUG_ENTER("ha_tina::update_row"); @@ -1530,7 +1543,7 @@ if (my_write(share->data_file, buffer.ptr(), size, MYF(MY_WME | MY_NABP))) DBUG_RETURN(-1); DBUG_RETURN(0); - } +} </programlisting> <para> @@ -1571,7 +1584,7 @@ <programlisting> int ha_tina::delete_row(const byte * buf) - { +{ DBUG_ENTER("ha_tina::delete_row"); statistic_increment(table->in_use->status_var.ha_delete_count, &LOCK_status); @@ -1582,7 +1595,7 @@ --records; DBUG_RETURN(0); - } +} </programlisting> <para> @@ -1607,13 +1620,15 @@ <title>Implementing the <function>position()</function> Function</title> <para> - The <function>position()</function> function is called after + The <link + linkend="custom-engine-api-reference-position"><function>position()</function></link> + function is called after every call to <function>rnd_next()</function> if the data needs to be reordered: </para> <programlisting> - void ha_foo::position(const byte *record) +void ha_foo::position(const byte *record) </programlisting> <para> @@ -1630,13 +1645,13 @@ <title>Implementing the <function>rnd_pos()</function> Function</title> <para> - The <function>rnd_pos()</function> function behaves in a similar + The <link linkend="custom-engine-api-reference-rnd_pos"><function>rnd_pos()</function></link> function behaves in a similar fashion to the <function>rnd_next()</function> function but takes an additional parameter: </para> <programlisting> - int ha_foo::rnd_pos(byte * buf, byte *pos) +int ha_foo::rnd_pos(byte * buf, byte *pos) </programlisting> <para> @@ -1678,7 +1693,7 @@ Adding index support to a storage engine revolves around two tasks: providing information to the optimizer and implementing index-related methods. The information provided to the optimizer - allows the optimizer to make better decisions about which index + helps the optimizer to make better decisions about which index to use or even to skip using an index and instead perform a table scan. </para> @@ -1723,7 +1738,7 @@ TABLE</literal> operation and store it for future use. The reasoning behind this is that the index information is most readily available during table and index creation and is not - easily retrieved afterwards. + as easily retrieved afterwards. </para> <para> @@ -1794,7 +1809,7 @@ <title>Creating Index Keys</title> <para> - As part of every table-write (<literal>INSERT</literal>, + As part of every table-write operation (<literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>), the storage engine is required to update its internal index information. @@ -1808,18 +1823,18 @@ <para> In general, the storage engine will have to use row information - passed in functions such as <function>write_row()</function>, - <function>delete_row()</function>, and - <function>update_row()</function> in combination with index - information for the table to determine what index information + passed in functions such as <link linkend="custom-engine-api-reference-write_row"><function>write_row()</function></link>, + <link linkend="custom-engine-api-reference-delete_row"><function>delete_row()</function></link>, and + <link linkend="custom-engine-api-reference-update_row"><function>update_row()</function></link> in combination with index + information for the table to determine what index data needs to be modified, and make the needed changes. </para> <para> - The method of associating an index to its row will depend on + The method of associating an index with its row will depend on your storage approach. The <literal>BerkeleyDB</literal> storage engine stores the primary key of the row in the index while - other storage engines store the row offset. + other storage engines often store the row offset. </para> </section> @@ -1911,18 +1926,14 @@ <para> The optimizer requests an update of table information by - calling the <function>handler::info()</function> function. The + calling the <link linkend="custom-engine-api-reference-info"><function>handler::info()</function></link> function. The <function>info()</function> function does not have a return value, instead it is expected that the storage engine will set a variety of public variables that the server will then read as needed. These values are also used to populate certain <literal>SHOW</literal> outputs such as <literal>SHOW TABLE - STATUS</literal>. - - <remark> - [SH] Once again, what about SELECT ... FROM - INFORMATION_SCHEMA? - </remark> + STATUS</literal> and for queries of the + <literal>INFORMATION_SCHEMA</literal>. </para> <para> @@ -2013,13 +2024,13 @@ <title>Implementing the <function>records_in_range</function> Function</title> <para> - The <function>records_in_range()</function> function is called + The <link linkend="custom-engine-api-reference-records_in_range"><function>records_in_range()</function></link> function is called by the optimizer to assist in choosing which index on a table to use for a query or join. It is defined as follows: </para> <programlisting> - ha_rows ha_foo::records_in_range(uint inx, key_range *min_key, key_range *max_key) +ha_rows ha_foo::records_in_range(uint inx, key_range *min_key, key_range *max_key) </programlisting> <para> @@ -2119,7 +2130,7 @@ <title>Preparing for Index Use with <function>index_init()</function></title> <para> - The <literal>index_init()</literal> function is called before an + The <link linkend="custom-engine-api-reference-index_init"><literal>index_init()</literal></link> function is called before an index is used to allow the storage engine to perform any necessary preparation or optimization: </para> @@ -2130,7 +2141,8 @@ <para> Most storage engines do not need to make special preparations, - in which case a default implementation will be used: + in which case a default implementation will be used if the + method is not explicitly implemented in the storage engine: </para> <programlisting> @@ -2144,7 +2156,7 @@ <title>Cleaning up with <function>index_end()</function></title> <para> - The <function>index_end()</function> function is a counterpart + The <link linkend="custom-engine-api-reference-index_end"><function>index_end()</function></link> function is a counterpart to the <function>index_init()</function> function. The purpose of the <function>index_end()</function> function is to clean up any preparations made by the <function>index_init()</function> @@ -2164,7 +2176,7 @@ <title>Implementing the <function>index_read()</function> Function</title> <para> - The <function>index_read()</function> function is used to + The <link linkend="custom-engine-api-reference-index_read"><function>index_read()</function></link> function is used to retrieve a row based on a key: </para> @@ -2233,7 +2245,9 @@ <title>Implementing the <function>index_read_idx()</function> Function</title> <para> - The <function>index_read_idx()</function> is identical to the + The <link + linkend="custom-engine-api-reference-index_read_idx"><function>index_read_idx()</function></link> + function is identical to the <link linkend="custom-engine-index-read"><function>index_read()</function></link> with the exception that <function>index_read_idx()</function> @@ -2245,6 +2259,10 @@ uint key_len, enum ha_rkey_function find_flag) </programlisting> + <para>The <literal>keynr</literal> parameter specifies the index + to be read, as opposed to <function>index_read</function> where + the index is already set.</para> + <para> As with the <function>index_read()</function> function, the storage engine must return the row that matches the key @@ -2259,7 +2277,7 @@ <title>Implementing the <function>index_next()</function> Function</title> <para> - The <function>index_next()</function> function is used for index + The <link linkend="custom-engine-api-reference-index_next"><function>index_next()</function></link> function is used for index scanning: </para> @@ -2282,7 +2300,7 @@ <title>Implementing the <function>index_prev()</function> Function</title> <para> - The <function>index_prev()</function> function is used for + The <link linkend="custom-engine-api-reference-index_prev"><function>index_prev()</function></link> function is used for reverse index scanning: </para> @@ -2305,7 +2323,7 @@ <title>Implementing the <function>index_first()</function> Function</title> <para> - The <function>index_first()</function> function is used for + The <link linkend="custom-engine-api-reference-index_first"><function>index_first()</function></link> function is used for index scanning: </para> @@ -2325,7 +2343,7 @@ <title>Implementing the <function>index_last()</function> Function</title> <para> - The <function>index_last()</function> function is used for + The <link linkend="custom-engine-api-reference-index_last"><function>index_last()</function></link> function is used for reverse index scanning: </para> @@ -2375,8 +2393,8 @@ </para> <para> - The storage engine stores transaction information in connection - with specific memory and also registers the transaction in the + The storage engine stores transaction information in per-connection + memory and also registers the transaction in the MySQL server to allow the server to later issue <literal>COMMIT</literal> and <literal>ROLLBACK</literal> operations. @@ -2420,7 +2438,7 @@ <para> The first function call that can start a transaction is the - <function>start_stmt()</function> function. + <link linkend="custom-engine-transactions-starting-start-stmt"><function>start_stmt()</function></link> function. </para> <para> @@ -2449,7 +2467,7 @@ <para> <literal>THD</literal> is the current client connection. It - holds state relevant for the current client, such as identity, + holds state relevant data for the current client, such as identity, network connection and other per-connection data. </para> @@ -2474,7 +2492,7 @@ Function</title> <para> - MySQL calls <function>handler::external_lock()</function> for + MySQL calls <link linkend="custom-engine-api-reference-external_lock"><function>handler::external_lock()</function></link> for every table it is going to use at the beginning of every statement. Thus, if a table is touched for the first time, it implicitly starts a transaction. @@ -2591,7 +2609,7 @@ <para> Of the two major transactional operations, <literal>ROLLBACK</literal> is the more complicated to - implement. All operations that occurred during the transactions + implement. All operations that occurred during the transaction must be reversed so that all rows are unchanged from before the transaction began. </para> @@ -5918,9 +5936,12 @@ <bridgehead>Usage</bridgehead> + <para>Most storage engines will simply return + <literal>0</literal>.</para> + <programlisting> - - </programlisting> +{ return 0; } +</programlisting> <bridgehead>Default Implementation</bridgehead> @@ -9165,6 +9186,7 @@ </section> --> + <section id="custom-engine-api-reference-index_end"> <title>index_end</title> @@ -9311,6 +9333,7 @@ </programlisting> </section> + <!-- <section id="custom-engine-api-reference-index_flags"> @@ -9413,6 +9436,7 @@ </section> --> + <section id="custom-engine-api-reference-index_init"> <title>index_init</title> @@ -9429,11 +9453,11 @@ </funcdef> - <paramdef>uint<parameter>idx</parameter> + <paramdef>uint <parameter>idx</parameter> </paramdef> - <paramdef>bool<parameter>sorted</parameter> + <paramdef>bool <parameter>sorted</parameter> </paramdef> @@ -9640,46 +9664,6 @@ </section> - <listitem> - <para> - <literal>buf</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>key</literal> - </para> - </listitem> - - <listitem> - <para> - <literal>keylen</literal> - </para> - </listitem> - - </itemizedlist> - - <bridgehead>Return Values</bridgehead> - - <itemizedlist> - - <listitem> - <para> - <literal/> - </para> - </listitem> - - </itemizedlist> - - <bridgehead>Usage</bridgehead> - -<programlisting> - - </programlisting> - - </section> - <section id="custom-engine-api-reference-index_prev"> <title>index_prev</title> @@ -9750,8 +9734,10 @@ { return HA_ERR_WRONG_COMMAND; } </programlisting> - </section><section id="custom-engine-api-reference-index_read_idx"> + </section> + <section id="custom-engine-api-reference-index_read_idx"> + <title>index_read_idx</title> <bridgehead>Purpose</bridgehead> @@ -9963,8 +9949,6 @@ </section> - - <section id="custom-engine-api-reference-index_read_last"> <title>index_read_last</title> @@ -10052,6 +10036,7 @@ </programlisting> </section> + <!-- <section id="custom-engine-api-reference-index_type"> @@ -11928,6 +11913,7 @@ </section> --> + <section id="custom-engine-api-reference-position"> <title>position</title> @@ -12009,6 +11995,7 @@ </programlisting> </section> + <!-- <section id="custom-engine-api-reference-preload_keys"> @@ -12850,6 +12837,7 @@ </section> --> + <section id="custom-engine-api-reference-records_in_range"> <title>records_in_range</title> @@ -12956,6 +12944,7 @@ </programlisting> </section> + <!-- <section id="custom-engine-api-reference-referenced_by_foreign_key"> @@ -13972,7 +13961,6 @@ </section> - <section id="custom-engine-api-reference-rnd_pos"> <title>rnd_pos</title> @@ -14058,6 +14046,7 @@ </programlisting> </section> + <!-- <section id="custom-engine-api-reference-rnd_same"> @@ -14428,6 +14417,7 @@ </section> --> + <section id="custom-engine-api-reference-start_stmt"> <title>start_stmt</title>
| Thread | ||
|---|---|---|
| • svn commit - mysqldoc@docsrva: r479 - branches/MikePluggable/trunk/refman-5.1 | mhillyer | 2 Dec |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.718 sec. using MySQL 5.1.14-beta-log