svn commit - mysqldoc@docsrva: r136 - branches/MikePluggable/trunk/refman-5.1

[eherman]

Author: eherman
Date: 2005-10-21 23:36:56 +0200 (Fri, 21 Oct 2005)
New Revision: 136

Log:
added more commentary pulled from ha_example.cc

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-10-21 21:34:28 UTC (rev
135)
+++ branches/MikePluggable/trunk/refman-5.1/custom-engine.xml	2005-10-21 21:36:56 UTC (rev
136)
@@ -1435,6 +1435,14 @@
        <title>Description</title>
 
     <para>This is the <function>create</function> method.</para>
+        <para>create() is called to create a database. The variable name will have
the name
+          of the table. When create() is called you do not need to worry about opening
+          the table. Also, the FRM file will have already been created so adjusting
+          create_info will not do you any good. You can overwrite the frm file at this
+          point if you wish to change the table definition, but there are no methods
+          currently provided for doing that.
+          </para><para>
+          Called from handle.cc by ha_create_table().</para>
       </refsection>
 
       <refsection>
@@ -1546,7 +1554,7 @@
 
       <refnamediv>
         <refname>delete_all_rows</refname>
-        <refpurpose></refpurpose>
+        <refpurpose>Used to delete all rows in a table.</refpurpose>
       </refnamediv>
 
       <refsynopsisdiv>
@@ -1563,10 +1571,19 @@
        <title>Description</title>
 
     <para>This is the <function>delete_all_rows</function>
method.</para>
-        <para>This is called to delete all rows in a table
-          If the handler don't support this, then this function will
+        <para>This is called to delete all rows in a table</para><para>
+          If the handler doesn't support this, then this function will
           return HA_ERR_WRONG_COMMAND and MySQL will delete the rows one
           by one.</para>
+        <para>Used both for cases of truncate and
+          for cases where the optimizer realizes that all rows will be
+          removed as a result of a SQL statement.
+          </para><para>
+          Called from item_sum.cc by Item_func_group_concat::clear(),
+          Item_sum_count_distinct::clear(), and Item_func_group_concat::clear().
+          Called from sql_delete.cc by mysql_delete().
+          Called from sql_select.cc by JOIN::reinit().
+          Called from sql_union.cc by st_select_lex_unit::exec().</para>
       </refsection>
 
       <refsection>
@@ -1712,8 +1729,20 @@
        <title>Description</title>
 
     <para>This is the <function>delete_table</function>
method.</para>
-        <para>We assume that the handler may return more extensions than
-          was actually used for the file.</para>
+        
+        <para>Used to delete a table. By the time delete_table() has been called
all
+          opened references to this table will have been closed (and your globally
+          shared references released. The variable name will just be the name of
+          the table. You will need to remove any files you have created at this point.
+          </para><para> 
+          If you do not implement this, the default delete_table() is called from
+          handler.cc and it will delete all files with the file extentions returned
+            by bas_ext().We assume that the handler may return more extensions than
+              was actually used for the file.</para>
+        <para>
+          Called from handler.cc by delete_table and  ha_create_table(). Only used
+          during create if the table_flag HA_DROP_BEFORE_CREATE was specified for
+          the storage engine.</para>
       </refsection>
 
       <refsection>
@@ -2547,6 +2576,15 @@
        <title>Description</title>
 
     <para>This is the <function>external_lock</function>
method.</para>
+        <para>The "locking functions for mysql" section in lock.cc has additional 
+          comments on this topic that may be useful to read.</para><para>
+          This creates a lock on the table. If you are implementing a storage engine
+          that can handle transacations, look at ha_berkely.cc to see how you will
+          want to go about doing this. Otherwise you should consider calling flock()
+          here.
+          </para><para>
+          Called from lock.cc by lock_external() and unlock_external(). Also called
+          from sql_table.cc by copy_data_between_tables().</para>
       </refsection>
 
       <refsection>
@@ -2615,6 +2653,9 @@
        <title>Description</title>
 
     <para>This is the <function>extra</function> method.</para>
+        <para>extra() is called whenever the server wishes to send a hint to
+          the storage engine. The myisam engine implements the most hints.
+          ha_innodb.cc has the most exhaustive list of these hints.</para>
       </refsection>
 
       <refsection>
@@ -5675,6 +5716,10 @@
        <title>Description</title>
 
     <para>This is the <function>index_first</function>
method.</para>
+        <para>index_first() asks for the first key in the index.
+          </para><para>
+          Called from opt_range.cc, opt_sum.cc, sql_handler.cc,
+          and sql_select.cc.</para>
       </refsection>
 
       <refsection>
@@ -5890,6 +5935,10 @@
        <title>Description</title>
 
     <para>This is the <function>index_last</function>
method.</para>
+        <para>index_last() asks for the last key in the index.
+          </para><para>
+          Called from opt_range.cc, opt_sum.cc, sql_handler.cc,
+          and sql_select.cc.</para>
       </refsection>
 
       <refsection>
@@ -6088,6 +6137,7 @@
        <title>Description</title>
 
     <para>This is the <function>index_prev</function>
method.</para>
+        <para>Used to read backwards through the index.</para>
       </refsection>
 
       <refsection>
@@ -6506,6 +6556,46 @@
        <title>Description</title>
 
     <para>This is the <function>info</function> method.</para>
+        <para>  ::info() is used to return information to the optimizer.
+          Currently this table handler doesn't implement most of the fields
+          really needed. SHOW also makes use of this data
+          Another note, you will probably want to have the following in your
+          code:
+          if (records &gt; 2)
+          records = 2;
+          The reason is that the server will optimize for cases of only a single
+          record. If in a table scan you don't know the number of records
+          it will probably be better to set records to two so you can return
+          as many records as you need.
+          Along with records a few more variables you may wish to set are:
+          records
+          deleted
+          data_file_length
+          index_file_length
+          delete_length
+          check_time
+          See public variables in handler.h for more information.
+          </para>
+        <para>  Called in:
+          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</para>
       </refsection>
 
       <refsection>
@@ -7995,6 +8085,19 @@
        <title>Description</title>
 
     <para>This is the <function>position</function>
method.</para>
+        <para>position() is called after each call to rnd_next() if the data needs
+          to be ordered. You can do something like the following to store
+          the position:
+          my_store_ptr(ref, ref_length, current_position);
+          </para>
+          <para>
+          The server uses ref to store data. ref_length in the above case is
+          the size needed to store current_position. ref is just a byte array
+          that the server will maintain. If you are using offsets to mark rows, then
+          current_position should be the offset. If it is a primary key like in
+          BDB, then it needs to be a primary key.
+          </para><para>
+          Called from filesort.cc, sql_select.cc, sql_delete.cc and
sql_update.cc.</para>
       </refsection>
 
       <refsection>
@@ -8703,6 +8806,11 @@
        <title>Description</title>
 
     <para>This is the <function>records_in_range</function>
method.</para>
+        <para>Given a starting key, and an ending key estimate the number of rows
that
+          will exist between the two. end_key may be empty which in case determine
+          if start_key matches any rows.
+          </para><para>
+          Called from opt_range.cc by check_quick_keys().</para>
       </refsection>
 
       <refsection>
@@ -8898,7 +9006,7 @@
 
       <refnamediv>
         <refname>rename_table</refname>
-        <refpurpose></refpurpose>
+        <refpurpose>Renames a table from one name to another from alter table
call.</refpurpose>
       </refnamediv>
 
       <refsynopsisdiv>
@@ -8918,6 +9026,12 @@
     <para>This is the <function>rename_table</function>
method.</para>
         <para>default rename_table() and delete_table() rename/delete files with a
           given name and extensions from bas_ext()</para>
+        <para>
+          If you do not implement this, the default rename_table() is called from
+          handler.cc and it will delete all files with the file extentions returned
+          by bas_ext().
+          </para><para>
+          Called from sql_table.cc by mysql_rename_table().</para>
       </refsection>
 
       <refsection>
@@ -9048,6 +9162,10 @@
        <title>Description</title>
 
     <para>This is the <function>reset</function> method.</para>
+        <para>Deprecated and likely to be removed in the future. Storage engines
normally
+          just make a call like:
+          ha_example::extra(HA_EXTRA_RESET);
+          to handle it.</para>
       </refsection>
 
       <refsection>
@@ -9457,12 +9575,16 @@
        <title>Description</title>
 
     <para>This is the <function>rnd_init</function>
method.</para>
+        <para>rnd_init() is called when the system wants the storage engine to do a

+        table scan.</para>
         <para>unlike index_init(), rnd_init() can be called two times
           without rnd_end() in between (it only makes sense if scan=1).
           then the second call should prepare for the new table scan
           (e.g if rnd_init allocates the cursor, second call should
           position it to the start of the table, no need to deallocate
           and allocate it again</para>
+         <para>Called from filesort.cc, records.cc, sql_handler.cc, sql_select.cc, 
+          sql_table.cc, and sql_update.cc.</para>
       </refsection>
 
       <refsection>
@@ -9522,6 +9644,13 @@
        <title>Description</title>
 
     <para>This is the <function>rnd_next</function>
method.</para>
+        <para>This is called for each row of the table scan. When you run out of
records
+          you should return HA_ERR_END_OF_FILE. Fill buff up with the row information.
+          The Field structure for the table is the key to getting data into buf
+          in a manner that will allow the server to understand it.
+          </para><para>
+          Called from filesort.cc, records.cc, sql_handler.cc, sql_select.cc,
sql_table.cc,
+          and sql_update.cc.</para>
       </refsection>
 
       <refsection>
@@ -9582,6 +9711,13 @@
        <title>Description</title>
 
     <para>This is the <function>rnd_pos</function> method.</para>
+    <para>used for finding row previously marked with position. This is useful for
+    large sorts. </para>
+        <para>This is like rnd_next, but you are given a position to use
+          to determine the row. The position will be of the type that you stored in
+          ref. You can use ha_get_ptr(pos,ref_length) to retrieve whatever key
+          or position you saved when position() was called.
+          Called from filesort.cc records.cc sql_insert.cc sql_select.cc
sql_update.cc.</para>
       </refsection>
 
       <refsection>
@@ -10053,6 +10189,34 @@
        <title>Description</title>
 
     <para>This is the <function>store_lock</function>
method.</para>
+        <para>The idea with handler::store_lock() is the following:
+          </para><para>
+          The statement decided which locks we should need for the table
+          for updates/deletes/inserts we get WRITE locks, for SELECT... we get
+          read locks.
+          </para><para>
+          Before adding the lock into the table lock handler (see thr_lock.c)
+          mysqld calls store lock with the requested locks.  Store lock can now
+          modify a write lock to a read lock (or some other lock), ignore the
+          lock (if we don't want to use MySQL table locks at all) or add locks
+          for many tables (like we do when we are using a MERGE handler).
+          </para><para>
+          Berkeley DB for example, changes all WRITE locks to TL_WRITE_ALLOW_WRITE
+          (which signals that we are doing WRITES, but we are still allowing other
+          reader's and writer's.
+          </para><para>
+          When releasing locks, store_lock() are also called. In this case one
+          usually doesn't have to do anything.
+          </para><para>
+          In some exceptional cases MySQL may send a request for a TL_IGNORE;
+          This means that we are requesting the same lock as last time and this
+          should also be ignored. (This may happen when someone does a flush
+          table when we have opened a part of the tables, in which case mysqld
+          closes and reopens the tables and tries to get the same locks at last
+          time).  In the future we will probably try to remove this.
+          </para><para>
+          Called from lock.cc by get_lock_data().
+          </para>
       </refsection>
 
       <refsection>