MDEV-33661 MENT-1591 Documenting spider_mon_table_cache and friends.

Partial documentation due to time constraints. Will improve over time.

Also removed a redundant parameter link_idx from
spider_get_sys_tables_connect_info().

And deleted some commented out code.

storage/spider/spd_copy_tables.cc

@@ -307,7 +307,7 @@ int spider_udf_get_copy_tgt_tables(
 
     if (
       (error_num = spider_get_sys_tables_connect_info(
-        table_tables, tmp_share, 0, mem_root)) ||
+        table_tables, tmp_share, mem_root)) ||
       (error_num = spider_get_sys_tables_link_status(
         table_tables, tmp_share, 0, mem_root)) ||
       (error_num = spider_get_sys_tables_link_idx(

storage/spider/spd_include.h

@@ -1606,6 +1606,7 @@ typedef struct st_spider_table_mon
   st_spider_table_mon        *next;
 } SPIDER_TABLE_MON;
 
+/* List of `SPIDER_TABLE_MON's */
 typedef struct st_spider_table_mon_list
 {
   char                       *key;

storage/spider/spd_sys_table.cc

@@ -570,6 +570,11 @@ int spider_check_sys_table_for_update_all_columns(
 #endif
 }
 
+/*
+  Creates a key (`table_key') consisting of `col_count' key parts of
+  `idx'th index of the table, then positions an index cursor to that
+  key.
+*/
 int spider_get_sys_table_by_idx(
   TABLE *table,
   char *table_key,
@@ -602,17 +607,6 @@ int spider_get_sys_table_by_idx(
     key_length);
 
   if (
-/*
-#if defined(MARIADB_BASE_VERSION) && MYSQL_VERSION_ID >= 50200
-    (error_num = table->file->ha_index_read_idx_map(
-      table->record[0], idx, (uchar *) table_key,
-      make_prev_keypart_map(col_count), HA_READ_KEY_EXACT))
-#else
-    (error_num = table->file->index_read_idx_map(
-      table->record[0], idx, (uchar *) table_key,
-      make_prev_keypart_map(col_count), HA_READ_KEY_EXACT))
-#endif
-*/
 #if defined(MARIADB_BASE_VERSION) && MYSQL_VERSION_ID >= 50200
     (error_num = table->file->ha_index_read_map(
       table->record[0], (uchar *) table_key,
@@ -649,7 +643,7 @@ int spider_sys_index_next_same(
 
 int spider_sys_index_first(
   TABLE *table,
-  const int idx
+  const int idx                 /* which index to use */
 ) {
   int error_num;
   DBUG_ENTER("spider_sys_index_first");
@@ -870,6 +864,10 @@ void spider_store_xa_member_info(
   DBUG_VOID_RETURN;
 }
 
+/*
+  Store db and table names from `name' to `table's corresponding
+  fields
+*/
 void spider_store_tables_name(
   TABLE *table,
   const char *name,
@@ -2064,14 +2062,16 @@ int spider_get_sys_tables(
   DBUG_RETURN(0);
 }
 
+/* Read table info from mysql.spider_tables into a `SPIDER_SHARE' */
 int spider_get_sys_tables_connect_info(
-  TABLE *table,
-  SPIDER_SHARE *share,
-  int link_idx,
+  TABLE *table,                         /* The mysql.spider_tables table */
+  SPIDER_SHARE *share,                  /* The `SPIDER_SHARE' to
+                                        update info */
   MEM_ROOT *mem_root
 ) {
   char *ptr;
   int error_num = 0;
+  const int link_idx= 0;
   DBUG_ENTER("spider_get_sys_tables_connect_info");
   if ((ptr = get_field(mem_root, table->field[3])))
   {
@@ -2297,9 +2297,14 @@ int spider_get_sys_tables_monitoring_binlog_pos_at_failing(
   DBUG_RETURN(error_num);
 }
 
+/*
+  Read the link status from mysql.spider_tables into a `SPIDER_SHARE'
+  with default value 1 (`SPIDER_LINK_STATUS_OK')
+*/
 int spider_get_sys_tables_link_status(
-  TABLE *table,
-  SPIDER_SHARE *share,
+  TABLE *table,                        /* The mysql.spider_tables table */
+  SPIDER_SHARE *share,                 /* The share to read link
+                                       status into */
   int link_idx,
   MEM_ROOT *mem_root
 ) {
@@ -2484,11 +2489,17 @@ int spider_sys_log_xa_failed(
   DBUG_RETURN(error_num);
 }
 
+/* Populate `mon_key' from the current row in `table' */
 int spider_get_sys_link_mon_key(
-  TABLE *table,
-  SPIDER_MON_KEY *mon_key,
+  TABLE *table,                 /* the mysql.spider_link_mon_servers
+                                table */
+  SPIDER_MON_KEY *mon_key,      /* output, to be populated in this
+                                function */
   MEM_ROOT *mem_root,
-  int *same
+  int *same                     /* output, true if the data from the
+                                current row in the table agrees with
+                                existing data in `mon_key' and false
+                                otherwise */
 ) {
   char *db_name, *table_name, *link_id;
   uint db_name_length, table_name_length, link_id_length;
@@ -2504,6 +2515,7 @@ int spider_get_sys_link_mon_key(
     DBUG_RETURN(ER_SPIDER_SYS_TABLE_VERSION_NUM);
   }
 
+  /* get data for `mon_key' from the table record */
   if (!(db_name = get_field(mem_root, table->field[0])))
     DBUG_RETURN(HA_ERR_OUT_OF_MEM);
   if (!(table_name = get_field(mem_root, table->field[1])))
@@ -2549,9 +2561,12 @@ int spider_get_sys_link_mon_key(
   DBUG_RETURN(0);
 }
 
+/* Get the server id from the spider_link_mon_servers table field */
 int spider_get_sys_link_mon_server_id(
-  TABLE *table,
-  uint32 *server_id,
+  TABLE *table,                        /* the
+                                       mysql.spider_link_mon_servers
+                                       table */
+  uint32 *server_id,                   /* output to server_id */
   MEM_ROOT *mem_root
 ) {
   char *ptr;
@@ -2564,14 +2579,17 @@ int spider_get_sys_link_mon_server_id(
   DBUG_RETURN(error_num);
 }
 
+/* Get connect info from the spider_link_mon_servers table fields */
 int spider_get_sys_link_mon_connect_info(
-  TABLE *table,
-  SPIDER_SHARE *share,
-  int link_idx,
+  TABLE *table,                           /* The
+                                          mysql.spider_link_mon_servers
+                                          table */
+  SPIDER_SHARE *share,                    /* The output spider_share */
   MEM_ROOT *mem_root
 ) {
   char *ptr;
   int error_num = 0;
+  const int link_idx= 0;
   DBUG_ENTER("spider_get_sys_link_mon_connect_info");
   if (
     !table->field[4]->is_null() &&
@@ -2753,9 +2771,6 @@ int spider_get_link_statuses(
       if (
         (error_num == HA_ERR_KEY_NOT_FOUND || error_num == HA_ERR_END_OF_FILE)
       ) {
-/*
-        table->file->print_error(error_num, MYF(0));
-*/
         DBUG_RETURN(error_num);
       }
     } else if ((error_num =

storage/spider/spd_sys_table.h

@@ -56,6 +56,7 @@
 #define SPIDER_SYS_LINK_MON_TABLE_TABLE_NAME_SIZE 64
 #define SPIDER_SYS_LINK_MON_TABLE_LINK_ID_SIZE 64
 
+/* For insertion into `spider_mon_table_cache'. */
 class SPIDER_MON_KEY: public SPIDER_SORT
 {
 public:
@@ -425,7 +426,6 @@ int spider_get_sys_tables(
 int spider_get_sys_tables_connect_info(
   TABLE *table,
   SPIDER_SHARE *share,
-  int link_idx,
   MEM_ROOT *mem_root
 );
 
@@ -502,7 +502,6 @@ int spider_get_sys_link_mon_server_id(
 int spider_get_sys_link_mon_connect_info(
   TABLE *table,
   SPIDER_SHARE *share,
-  int link_idx,
   MEM_ROOT *mem_root
 );
 

storage/spider/spd_table.cc

@@ -3421,13 +3421,15 @@ int spider_parse_connect_info(
   DBUG_RETURN(error_num);
 }
 
+/* Set default connect info of a SPIDER_SHARE if needed */
 int spider_set_connect_info_default(
-  SPIDER_SHARE *share,
+  SPIDER_SHARE *share,               /* The `SPIDER_SHARE' to set
+                                     default connect info */
 #ifdef WITH_PARTITION_STORAGE_ENGINE
-  partition_element *part_elem,
-  partition_element *sub_elem,
+  partition_element *part_elem, /* partition info used as input */
+  partition_element *sub_elem,  /* subpartition info used as input */
 #endif
-  TABLE_SHARE *table_share
+  TABLE_SHARE *table_share      /* table share info used as input */
 ) {
   int error_num, roop_count;
   DBUG_ENTER("spider_set_connect_info_default");
@@ -3558,22 +3560,6 @@ int spider_set_connect_info_default(
       }
     }
 
-/*
-    if (!share->static_link_ids[roop_count])
-    {
-      DBUG_PRINT("info",("spider create default static_link_ids"));
-      share->static_link_ids_lengths[roop_count] =
-        SPIDER_DB_STATIC_LINK_ID_LEN;
-      if (
-        !(share->static_link_ids[roop_count] = spider_create_string(
-          SPIDER_DB_STATIC_LINK_ID_STR,
-          share->static_link_ids_lengths[roop_count]))
-      ) {
-        DBUG_RETURN(HA_ERR_OUT_OF_MEM);
-      }
-    }
-*/
-
     if (share->tgt_ports[roop_count] == -1)
     {
       share->tgt_ports[roop_count] = MYSQL_PORT;
@@ -3705,6 +3691,11 @@ int spider_set_connect_info_default(
   DBUG_RETURN(0);
 }
 
+/*
+  This function is a no-op if all share->tgt_dbs and
+  share->tgt_table_names are non-null, otherwise it may assign them
+  with db_name and table_name
+*/
 int spider_set_connect_info_default_db_table(
   SPIDER_SHARE *share,
   const char *db_name,
@@ -3748,6 +3739,11 @@ int spider_set_connect_info_default_db_table(
   DBUG_RETURN(0);
 }
 
+/*
+  Parse `dbtable_name' into db name and table name, and call
+  spider_set_connect_info_default_db_table() to set the db/table name
+  values of `share' if needed
+*/
 int spider_set_connect_info_default_dbtable(
   SPIDER_SHARE *share,
   const char *dbtable_name,
@@ -6062,7 +6058,7 @@ int spider_open_all_tables(
       (error_num = spider_get_sys_tables(
         table_tables, &db_name, &table_name, &mem_root)) ||
       (error_num = spider_get_sys_tables_connect_info(
-        table_tables, &tmp_share, 0, &mem_root)) ||
+        table_tables, &tmp_share, &mem_root)) ||
       (error_num = spider_set_connect_info_default(
         &tmp_share,
 #ifdef WITH_PARTITION_STORAGE_ENGINE
@@ -6676,16 +6672,6 @@ int spider_db_init(
 #ifdef HTON_CAN_READ_CONNECT_STRING_IN_PARTITION
   spider_hton->flags |= HTON_CAN_READ_CONNECT_STRING_IN_PARTITION;
 #endif
-  /* spider_hton->db_type = DB_TYPE_SPIDER; */
-  /*
-  spider_hton->savepoint_offset;
-  spider_hton->savepoint_set = spider_savepoint_set;
-  spider_hton->savepoint_rollback = spider_savepoint_rollback;
-  spider_hton->savepoint_release = spider_savepoint_release;
-  spider_hton->create_cursor_read_view = spider_create_cursor_read_view;
-  spider_hton->set_cursor_read_view = spider_set_cursor_read_view;
-  spider_hton->close_cursor_read_view = spider_close_cursor_read_view;
-  */
   spider_hton->panic = spider_panic;
   spider_hton->close_connection = spider_close_connection;
   spider_hton->start_consistent_snapshot = spider_start_consistent_snapshot;