The general theme for table function names seem to be "table_<am_callback_name>". For example table_scan_getnextslot() and its corresponding callback scan_getnextslot(). Most of the table functions and callbacks follow mentioned convention except following ones
table_beginscan
table_endscan
table_rescan
table_fetch_row_version
table_get_latest_tid
table_insert
table_insert_speculative
table_complete_speculative
table_delete
table_update
table_lock_tuple
the corresponding callback names for them are
scan_begin
scan_end
scan_rescan
tuple_fetch_row_version
tuple_get_latest_tid
tuple_insert
tuple_insert_speculative
tuple_delete
tuple_update
tuple_lock
It confuses while browsing through the code and hence I would like to propose we make them consistent. Either fix the callback names or table functions but all should follow the same convention, makes it easy to browse around and refer to as well. Personally, I would say fix the table function names as callback names seem fine. So, for example, make it table_scan_begin().
Also, some of these table function names read little odd
table_relation_set_new_filenode
table_relation_nontransactional_truncate
table_relation_copy_data
table_relation_copy_for_cluster
table_relation_vacuum
table_relation_estimate_size
Can we drop relation word from callback names and as a result from these function names as well? Just have callback names as set_new_filenode, copy_data, estimate_size?
Also, a question about comments. Currently, redundant comments are written above callback functions as also above table functions. They differ sometimes a little bit on descriptions but majority content still being the same. Should we have only one place finalized to have the comments to keep them in sync and also know which one to refer to?
Plus, file name amapi.h now seems very broad, if possible should be renamed to indexamapi.h or indexam.h to follow tableam.h. No idea what's our policy around header file renames.