Bug #78608 index_read_idx is no longer present, replace doc with index_read_idx_map
Submitted: 28 Sep 2015 20:08 Modified: 11 Jul 2017 11:12
Reporter: Fred Battle Email Updates:
Status: Won't fix Impact on me:
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.6.X OS:Any
Assigned to: CPU Architecture:Any

[28 Sep 2015 20:08] Fred Battle
This page documents a function that no longer exists in MySQL 5.6

If I'm correct, this function has changed names to index_read_idx_map( ).  It looks like the parameters are already changed, but not the function name itself.  Note also that the Return Values section is also out-of-date, it reads "There is no return value" when actually there is a return value.

Furthermore, index_read_idx( )  is listed on this page:

While you are at it, perhaps you want to document this function:
index_read_last_map( )
as perhaps it goes along with index_read_idx_map( ).

How to repeat:
View this page:

And this page:
[29 Sep 2015 0:14] MySQL Verification Team
Thank you for the bug report. Doing a search on recent source tree the below was returned?

Find all "index_read_idx(", Subfolders, Find Results 1, Entire Solution, ""
  C:\build\2015sep26\mysql-5.6\storage\archive\ha_archive.h(127):  virtual int index_read_idx(uchar * buf, uint index, const uchar * key,
  C:\build\2015sep26\mysql-5.6\storage\archive\ha_archive.cc(1087):  rc= index_read_idx(buf, active_index, key, key_len, find_flag);
  C:\build\2015sep26\mysql-5.6\storage\archive\ha_archive.cc(1093):int ha_archive::index_read_idx(uchar *buf, uint index, const uchar *key,
  C:\build\2015sep26\mysql-5.6\sql\log_event.cc(12763):      DBUG_PRINT("info",("Locating offending record using index_read_idx()"));
  C:\build\2015sep26\mysql-5.6\sql\log_event_old.cc(2073):      DBUG_PRINT("info",("Locating offending record using index_read_idx()"));
  C:\build\2015sep26\mysql-5.6\storage\federated\ha_federated.cc(2370):int ha_federated::index_read_idx(uchar *buf, uint index, const uchar *key,
  C:\build\2015sep26\mysql-5.6\storage\innobase\handler\ha_innodb.cc(2726):call index_read_idx() etc. Actually, we can let the cursor stay open even
  C:\build\2015sep26\mysql-5.6\sql\sql_acl.cc(7041):      index_read_idx() will replace table->record[0] (its first argument)
  Matching lines: 9    Matching files: 7    Total files searched: 1015
[29 Sep 2015 0:57] Fred Battle
Hi Miguel,
Thanks for finding those functions. The fact that you found those functions proves that the Archive, Federated and Innobase storage engines have implemented that function.  

I should explain better what I am doing.  I am implementing a Custom Storage Engine.  Basically, the APIs listed on this page need to be implemented:
and these APIs correspond to the functions listed in mysql-pro-5.6.26/sql/handler.h.  If you look at the current version of handler.h, you will not find index_read_idx( ), but you will find index_read_idx_map( ).

We created our MySQL Custom Storage Engine a few years ago, using MySQL 5.0.84.  If you go back to that version and look at handler.h, you will find index_read_idx( ).  So, it appears the Custom Storage Engine API set has changed over the years.  Another interesting point for us, is that we know certain functionality that called index_read_idx( ) used to work.  But today, as we build against MySQL 5.6.X (actually 5.6.26), testing shows that index_read_idx( ) is no longer being called, and because we don't have index_read_idx_map( ) implemented, our lookup times are now unacceptably long.  As a quick test, I implemented index_read_idx_map( ) in our custom storage engine and just added a simple debug trace to prove that MySQL is calling it.  And it is.

Furthermore, I'm also referring to the book "MySQL 5.1 Plugin Development".  I know this third party book is in no way your team's responsibility.  However, it does document how to implement Custom Storage Engines.  I will point out that index_read_idx( ) is not documented in this book, but index_read_idx_map( ) is.

In conclusion, I think my doc bug is still valid.  sql/handler.h lists many virtual functions that developers may implement in order to create their own Custom Storage Engine.  index_read_idx( ) is no longer present in that file, and index_read_idx_map( ) is. In fact, there are also other virtual functions in sql/handler.h which are not documented.

I hope this long-winded clarification explains what I am doing and why I said index_read_idx( ) is not present.  What I meant to say, is the function is no longer present in sql/handler.h.  And it appears that it was replaced with index_read_idx_map( ).

Please let me know if I have said anything wrong.  And thank you for taking the time to work on this issue.

[29 Sep 2015 10:43] MySQL Verification Team
Thank you for the feedback and clarification.
[5 Jul 2017 17:12] Stefan Hinz
Posted by developer:
No more updates are made to the MySQL Internals documentation, because it's in the process of being replaced by https://dev.mysql.com/doc/dev/mysql-server/latest/.