MySQL Bugs: #78608: index_read_idx is no longer present, replace doc with index_read_idx

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:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.6.X	OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
This page documents a function that no longer exists in MySQL 5.6
http://dev.mysql.com/doc/internals/en/index-read-idx.html

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:
http://dev.mysql.com/doc/internals/en/api-reference.html

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:
http://dev.mysql.com/doc/internals/en/index-read-idx.html

And this page:
http://dev.mysql.com/doc/internals/en/api-reference.html

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\storage\innobase\handler\ha_innodb.cc(7729):ha_innobase::index_read_idx(
  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

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:
http://dev.mysql.com/doc/internals/en/api-reference.html
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.

-Fred

Thank you for the feedback and clarification.

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/.