| List: | Commits | « Previous MessageNext Message » | |
| From: | paul | Date: | March 29 2007 10:12pm |
| Subject: | svn commit - mysqldoc@docsrva: r5646 - in trunk: . internals | ||
| View as plain text | |||
Author: paul Date: 2007-03-29 22:12:30 +0200 (Thu, 29 Mar 2007) New Revision: 5646 Log: r22522@polar: paul | 2007-03-29 15:11:49 -0500 Changes for WL#3700 (Handler change: keypart_map instead of key_len) Modified: trunk/internals/custom-engine.xml Property changes on: trunk ___________________________________________________________________ Name: svk:merge - 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:22511 7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:18313 b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218 bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:14593 + 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:22522 7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:18313 b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218 bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:14593 Modified: trunk/internals/custom-engine.xml =================================================================== --- trunk/internals/custom-engine.xml 2007-03-29 19:13:01 UTC (rev 5645) +++ trunk/internals/custom-engine.xml 2007-03-29 20:12:30 UTC (rev 5646) Changed blocks: 25, Lines Added: 187, Lines Deleted: 77; 16200 bytes @@ -127,9 +127,9 @@ <filename>ha_example.h</filename> can be found in the <filename>storage/example</filename> directory of the MySQL 5.1 source tree. For instructions on how to obtain the 5.1 source - tree, see <ulink - url="http://dev.mysql.com/doc/refman/5.1/en/installing-source.html">MySQL - Installation Using a Source Distribution</ulink>. + tree, see + <ulink url="http://dev.mysql.com/doc/refman/5.1/en/installing-source.html">MySQL + Installation Using a Source Distribution</ulink>. </para> <para> @@ -709,7 +709,7 @@ <para> The additional elements in the <literal>FEDERATED</literal> example are extra initializations for the handler. The minimum - implementation required is the <literal>handler()</literal> + implementation required is the <function>handler()</function> initialization shown in the <literal>EXAMPLE</literal> version. </para> @@ -1271,13 +1271,13 @@ <para> After the NULL bitmap come the columns, one by one. Each column - is of the size indicated in <ulink + is of the size indicated in + <ulink url="http://dev.mysql.com/doc/refman/5.1/en/data-types.html">MySQL - Data Types</ulink>. In the - server, column data types are defined in the - <filename>sql/field.cc</filename> file. In the fixed length row - format, the columns are simply laid out one by one. In a - variable-length row, <literal>VARCHAR</literal> columns are + Data Types</ulink>. In the server, column data types are defined + in the <filename>sql/field.cc</filename> file. In the fixed + length row format, the columns are simply laid out one by one. + In a variable-length row, <literal>VARCHAR</literal> columns are coded as a one or two-byte length, followed by a string of characters. In a variable-length row with <literal>BLOB</literal> columns, each blob is represented by two @@ -1868,6 +1868,39 @@ <literal>table->key_info[<replaceable>index</replaceable>]->key_part[<replaceable>part_num</replaceable>]</literal>. </para> + <para> + Along with the key, handler methods pass a <literal>ulonglong + keypart_map</literal> parameter to indicate which parts of the + key are present in the <literal>key</literal> parameter. + <literal>keypart_map</literal> is a bitmap with one bit per key + part: 1 for <literal>keypart[0]</literal>, 2 for + <literal>keypart[1]</literal>, 4 for + <literal>keypart[2]</literal>, and so forth. If a bit in + <literal>keypart_map</literal> is set, the value for this key + part is present in the key buffer. Bits following the bit for + the last key part don't matter. That is, ~0 can be used for + <quote>all keyparts.</quote> Currently, only key prefixes are + supported. That is, <literal>assert((keypart_map + 1) & + keypart_map == 0)</literal>. + </para> + + <para> + A <literal>keypart_map</literal> is part of the + <literal>key_range</literal> structure used by + <function>records_in_range()</function>. A + <literal>keypart_map</literal> value is passed directly to + <function>index_read()</function>, + <function>index_read_idx()</function>, and + <function>index_read_last()</function>. + </para> + + <para> + Older handlers have a <literal>uint key_len</literal> parameter + instead of <literal>keypart_map</literal>. The + <literal>key_len</literal> value indicates the prefix length + when matching by prefix. + </para> + <remark> This was removed when the BDB engine was removed. Need to find an equivalent example from MyISAM. [MC] @@ -2062,10 +2095,59 @@ The <literal>inx</literal> parameter is the index to be checked. The <literal>*min_key</literal> parameter is the low end of the range while the <literal>*max_key</literal> - parameter is the high end of the range. + parameter is the high end of the range. The + <literal>key_range</literal> structure looks like this: </para> +<programlisting> +typedef struct st_key_range +{ + const byte *key; + uint length; + key_part_map keypart_map; + enum ha_rkey_function flag; +} key_range; +</programlisting> + <para> + The <literal>key_range</literal> members are used as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>key</literal> is a pointer to the key buffer. + </para> + </listitem> + + <listitem> + <para> + <literal>length</literal> is the key length. + </para> + </listitem> + + <listitem> + <para> + <literal>keypart_map</literal> is a bitmap that indicates + which key parts are passed in <literal>key</literal> (as + described in + <xref linkend="custom-engine-index-parse-keys"/>). + </para> + </listitem> + + <listitem> + <para> + <literal>flag</literal> indicates whether to include the + key in the range. Its value differs for + <literal>min_key</literal> and <literal>max_key</literal>, + as described following. + </para> + </listitem> + + </itemizedlist> + + <para> <literal>min_key.flag</literal> can have one of the following values: </para> @@ -2126,9 +2208,9 @@ <listitem> <para> - <literal>number > 0</literal> - There is approximately - <replaceable>number</replaceable> matching rows in the - range + <replaceable>number > 0</replaceable> - There are + approximately <replaceable>number</replaceable> matching + rows in the range </para> </listitem> @@ -2156,7 +2238,7 @@ <para> The - <link linkend="custom-engine-api-reference-index_init"><literal>index_init()</literal></link> + <link linkend="custom-engine-api-reference-index_init"><function>index_init()</function></link> method is called before an index is used to allow the storage engine to perform any necessary preparation or optimization: </para> @@ -2209,17 +2291,19 @@ </para> <programlisting> -int ha_foo::index_read(byte * buf, const byte * key, uint key_len, enum ha_rkey_function find_flag) +int ha_foo::index_read(byte * buf, const byte * key, + ulonglong keypart_map, + enum ha_rkey_function find_flag) </programlisting> <para> The <literal>*buf</literal> parameter is a byte array that the storage engine populates with the row that matches the index key specified in <literal>*key</literal>. The - <literal>key_len</literal> parameter indicates the prefix length - when matching by prefix, and the <literal>find_flag</literal> - parameter is an enumerator that dictates the search behavior to - be used. + <literal>keypart_map</literal> is a bitmap that indicates which + parts of the key are present in the <literal>key</literal> + parameter. The <literal>find_flag</literal> parameter is an + enumerator that dictates the search behavior to be used. </para> <para> @@ -2273,23 +2357,22 @@ <para> The - <link - linkend="custom-engine-api-reference-index_read_idx"><function>index_read_idx()</function></link> - method is identical to the - <link - linkend="custom-engine-index-read"><function>index_read()</function></link> + <link linkend="custom-engine-api-reference-index_read_idx"><function>index_read_idx()</function></link> + method is identical to + <link linkend="custom-engine-index-read"><function>index_read()</function></link> with the exception that <function>index_read_idx()</function> accepts an additional <literal>keynr</literal> parameter: </para> <programlisting> int ha_foo::index_read_idx(byte * buf, uint keynr, const byte * key, - uint key_len, enum ha_rkey_function find_flag) + ulonglong keypart_map, + 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 + read, as opposed to <function>index_read()</function>, where the index is already set. </para> @@ -2302,6 +2385,35 @@ </section> + <section id="custom-engine-index-read-last"> + + <title>Implementing the <function>index_read_last()</function> Method</title> + + <para> + The + <link linkend="custom-engine-api-reference-index_read_last"><function>index_read_last()</function></link> + method works like + <link linkend="custom-engine-index-read"><function>index_read()</function></link> + but finds the last row with the current key value or prefix. + </para> + +<programlisting> +int ha_foo::index_read_last(byte * buf, const byte * key, + key_part_map keypart_map) +</programlisting> + + <para> + <function>index_read_last()</function> is used when optimizing + away the <literal>ORDER BY</literal> clause for statements such + as this: + </para> + +<programlisting> +SELECT * FROM t1 WHERE a=1 ORDER BY a DESC,b DESC; +</programlisting> + + </section> + <section id="custom-engine-index-next"> <title>Implementing the <function>index_next()</function> Method</title> @@ -9765,9 +9877,9 @@ </section> - <section id="custom-engine-api-reference-index_read_idx"> + <section id="custom-engine-api-reference-index_read"> - <title>index_read_idx</title> + <title>index_read</title> <bridgehead>Purpose</bridgehead> @@ -9781,7 +9893,7 @@ <funcprototype> - <funcdef>virtual int <function>index_read_idx</function> + <funcdef>virtual int <function>index_read</function> </funcdef> @@ -9789,15 +9901,11 @@ </paramdef> - <paramdef>uint<parameter>index</parameter> - - </paramdef> - <paramdef>const byte *<parameter>key</parameter> </paramdef> - <paramdef>uint<parameter>key_len</parameter> + <paramdef>ulonglong<parameter>keypart_map</parameter> </paramdef> @@ -9813,12 +9921,13 @@ <bridgehead>Description</bridgehead> <para> - This is the <function>index_read_idx</function> method. + This is the <function>index_read</function> method. </para> <para> - Positions an index cursor to the index specified in key. Fetches - the row if any. This is only used to read whole keys. + Positions an index cursor to the index specified in the handle. + Fetches the row if available. If the key value is null, begin at + the first key of the index. </para> <bridgehead>Parameters</bridgehead> @@ -9833,19 +9942,13 @@ <listitem> <para> - <literal>index</literal> - </para> - </listitem> - - <listitem> - <para> <literal>key</literal> </para> </listitem> <listitem> <para> - <literal>key_len</literal> + <literal>keypart_map</literal> </para> </listitem> @@ -9865,16 +9968,17 @@ <bridgehead>Usage</bridgehead> - <para> - Locate the row that matches the key passed and return it in the - buffer provided. - </para> + <bridgehead>Default Implementation</bridgehead> +<programlisting> + { return HA_ERR_WRONG_COMMAND; } + </programlisting> + </section> - <section id="custom-engine-api-reference-index_read"> + <section id="custom-engine-api-reference-index_read_idx"> - <title>index_read</title> + <title>index_read_idx</title> <bridgehead>Purpose</bridgehead> @@ -9888,7 +9992,7 @@ <funcprototype> - <funcdef>virtual int <function>index_read</function> + <funcdef>virtual int <function>index_read_idx</function> </funcdef> @@ -9896,11 +10000,15 @@ </paramdef> + <paramdef>uint<parameter>index</parameter> + + </paramdef> + <paramdef>const byte *<parameter>key</parameter> </paramdef> - <paramdef>uint<parameter>key_len</parameter> + <paramdef>ulonglong<parameter>keypart_map</parameter> </paramdef> @@ -9916,13 +10024,12 @@ <bridgehead>Description</bridgehead> <para> - This is the <function>index_read</function> method. + This is the <function>index_read_idx</function> method. </para> <para> - Positions an index cursor to the index specified in the handle. - Fetches the row if available. If the key value is null, begin at - the first key of the index. + Positions an index cursor to the index specified in key. Fetches + the row if any. This is only used to read whole keys. </para> <bridgehead>Parameters</bridgehead> @@ -9937,13 +10044,19 @@ <listitem> <para> + <literal>index</literal> + </para> + </listitem> + + <listitem> + <para> <literal>key</literal> </para> </listitem> <listitem> <para> - <literal>key_len</literal> + <literal>keypart_map</literal> </para> </listitem> @@ -9963,15 +10076,13 @@ <bridgehead>Usage</bridgehead> - <bridgehead>Default Implementation</bridgehead> + <para> + Locate the row that matches the key passed and return it in the + buffer provided. + </para> -<programlisting> - { return HA_ERR_WRONG_COMMAND; } - </programlisting> - </section> -<!-- <section id="custom-engine-api-reference-index_read_last"> <title>index_read_last</title> @@ -9996,7 +10107,7 @@ </paramdef> - <paramdef>uint<parameter>key_len</parameter> + <paramdef>ulonglong<parameter>keypart_map</parameter> </paramdef> @@ -10028,7 +10139,7 @@ <listitem> <para> - <literal>key_len</literal> + <literal>keypart_map</literal> </para> </listitem> @@ -10059,7 +10170,6 @@ </programlisting> </section> ---> <!-- <section id="custom-engine-api-reference-index_type"> @@ -11700,16 +11810,16 @@ </para> <programlisting> - #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 +#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 </programlisting> <para>
| Thread | ||
|---|---|---|
| • svn commit - mysqldoc@docsrva: r5646 - in trunk: . internals | paul | 29 Mar |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.479 sec. using MySQL 5.1.14-beta-log