bk commit into 6.0 tree (kostja:1.2551) WL#3288

[konstantin]

Below is the list of changes that have just been committed into a local
6.0 repository of kostja.  When kostja does a push these changes
will be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://dev.mysql.com/doc/mysql/en/installing-source-tree.html

ChangeSet@stripped, 2008-02-13 16:55:20+03:00, kostja@dipika.(none) +2 -0
  WL#3288 Foreign Keys: Storage engine API for foreign key support
  Step 1: Define tentative cursor API

  sql/handler.cc@stripped, 2008-02-13 16:55:16+03:00, kostja@dipika.(none) +7 -0
    WL#3288, step 1

  sql/handler.h@stripped, 2008-02-13 16:55:16+03:00, kostja@dipika.(none) +118 -0
    WL#3288, step 1

diff -Nrup a/sql/handler.cc b/sql/handler.cc
--- a/sql/handler.cc	2008-01-25 23:27:09 +03:00
+++ b/sql/handler.cc	2008-02-13 16:55:16 +03:00
@@ -1527,6 +1527,13 @@ int ha_delete_table(THD *thd, handlerton
 }
 
 /****************************************************************************
+** Handler_cursor methods
+****************************************************************************/
+Handler_cursor::~Handler_cursor()
+{
+}
+
+/****************************************************************************
 ** General handler functions
 ****************************************************************************/
 handler *handler::clone(MEM_ROOT *mem_root)
diff -Nrup a/sql/handler.h b/sql/handler.h
--- a/sql/handler.h	2008-01-25 23:23:15 +03:00
+++ b/sql/handler.h	2008-02-13 16:55:16 +03:00
@@ -620,6 +620,124 @@ struct handler_iterator {
   void *buffer;
 };
 
+
+/**
+  Iterate over table records.
+
+  Represents an abstract API for different table access methods
+  (sequential scan, index scan) and selection criteria (all,
+  primary key, range). Encapsulates forward and backward
+  scrolling and updatability options.
+
+  Forward scrolling is the minimal subset of functionality
+  that is expected to be supported by all implementations in
+  all storage engines. If a particular implementation
+  does not support more advanced features, HA_ERR_WRONG_COMMAND
+  is returned.
+
+  The memory management of Handler_cursor is Sql_alloc based.
+  The user must supply a memory root whenever a cursor is
+  created.
+*/
+
+class Handler_cursor: public Sql_alloc
+{
+public:
+  /**
+    Open the cursor and position it on the first record, if any.
+    Supported by all implementations.
+
+    @retval  0 in case of success.
+    @retval  HA_ERR_END_OF_FILE There is no first row, the result set
+             is empty
+  */
+  virtual int cursor_open()= 0;
+  /**
+    Similar to open, but applicable only to a cursor that has been
+    opened already. Supported by all implementations.
+
+    @return  0 if case of success.
+    @return  HA_ERR_END_OF_FILE There is no first row, the result
+             set is empty.
+  */
+  virtual int cursor_reset()= 0;
+
+  /**
+    Advance cursor position to the next record.
+    Read the record under the current position into a buffer.
+
+    @param[out]  buff  a buffer to read the record into.
+                       Must be of the appropriate size,
+                       defined by record format in the
+                       table share.
+
+    @retval  0  success
+    @retval  HA_ERR_END_OF_FILE This is not an error.
+             Returned when the cursor position has been
+             advanced beyond the last row or
+             on attempt to advance the position further
+             when it's already beyond the last row.
+             'buff' has been left intact.
+    @retval  HA_ERR_* A storage engine error.
+  */
+  virtual int cursor_read_next(void *buff)= 0;
+  /**
+    Advance cursor position to the previous record.
+    Read the record under the current position into a buffer.
+
+    @param[out]  buff  a buffer to read the record into.
+
+    @retval  0  success
+    @retval  HA_ERR_WRONG_COMMAND The operation is not supported.
+    @retval  HA_ERR_END_OF_FILE This is not an error.
+             Returned when the cursor position has been
+             advanced before the first row or
+             on attempt to advance the position further
+             when it's already before the first row.
+             'buff' has been left intact.
+    @retval  HA_ERR_* A storage engine error.
+  */
+  virtual int cursor_read_prev(void *buff)= 0;
+  /**
+    Update the record under the current position.
+
+    @param[in]  buff New record value.
+
+    @retval  0  success
+    @retval  HA_ERR_WRONG_COMMAND The operation is not supported.
+    @retval  HA_ERR_END_OF_FILE The cursor does not
+             point to a record.
+    @retval  HA_ERR_RECORD_IS_THE_SAME No update happened
+             since the old and new records are the same.
+    @retval  HA_ERR_* A storage engine error.
+  */
+  virtual int positioned_update(const void *buff)= 0;
+  /**
+    Delete the record under the current position.
+
+    @retval  0  success
+    @retval  HA_ERR_WRONG_COMMAND The operation is not supported.
+    @retval  HA_ERR_END_OF_FILE The cursor does not
+             point to a record.
+    @retval  HA_ERR_* A storage engine error.
+  */
+  virtual int positioned_delete()= 0;
+
+  enum {
+    CAN_READ_PREV= 1, /* cursor_read_prev() is supported */
+    CAN_MODIFY= 2 /* positioned_{update,delete}() are supported */
+  };
+
+  virtual ~Handler_cursor();
+
+protected:
+  /**
+    Capabilities flags. Must be initialized by the implementation.
+  */
+  uint32 m_cursor_flags;
+};
+
+
 /*
   handlerton is a singleton structure - one instance per storage engine -
   to provide access to storage engine functionality that works on the