Skip to content

M
mariadb
Commit a7405ca4 authored by unknown's avatar unknown
Browse files
Options

Consistently use doxygen comments in class handler.

parent 7213ca20
Show whitespace changes
Inline Side-by-side
Showing with 92 additions and 114 deletions
sql/handler.h
View file @ a7405ca4
......@@ -959,11 +959,11 @@ uint calculate_key_len(TABLE *, uint, const uchar *, key_part_map);
*/
#define make_prev_keypart_map(N) (((key_part_map)1 << (N)) - 1)
/*
/**
The handler class is the interface for dynamically loadable
storage engines. Do not add ifdefs and take care when adding or
changing virtual functions to avoid vtable confusion
*/
*/
class handler :public Sql_alloc
{
......@@ -981,7 +981,7 @@ public:
virtual int index_init(uint idx, bool sorted) { active_index=idx; return 0; }
virtual int index_end() { active_index=MAX_KEY; return 0; }
/*
/**
rnd_init() can be called two times without rnd_end() in between
(it only makes sense if scan=1).
then the second call should prepare for the new table scan (e.g
......@@ -1006,13 +1006,13 @@ public:
ha_statistics stats;
/* The following are for read_multi_range */
/** The following are for read_multi_range */
bool multi_range_sorted;
KEY_MULTI_RANGE *multi_range_curr;
KEY_MULTI_RANGE *multi_range_end;
HANDLER_BUFFER *multi_range_buffer;
/* The following are for read_range() */
/** The following are for read_range() */
key_range save_end_range, *end_range;
KEY_PART_INFO *range_key_part;
int key_compare_result_on_equal;
......@@ -1021,14 +1021,14 @@ public:
uint errkey; /* Last dup key */
uint key_used_on_scan;
uint active_index;
/* Length of ref (1-8 or the clustered key length) */
/** Length of ref (1-8 or the clustered key length) */
uint ref_length;
FT_INFO *ft_handler;
enum {NONE=0, INDEX, RND} inited;
bool locked;
bool implicit_emptied; /* Can be !=0 only if HEAP */
const COND *pushed_cond;
/*
/**
next_insert_id is the next value which should be inserted into the
auto_increment column: in a inserting-multi-row statement (like INSERT
SELECT), for the first row where the autoinc value is not specified by the
......@@ -1038,14 +1038,14 @@ public:
get_auto_increment().
*/
ulonglong next_insert_id;
/*
/**
insert id for the current row (*autogenerated*; if not
autogenerated, it's 0).
At first successful insertion, this variable is stored into
THD::first_successful_insert_id_in_cur_stmt.
*/
ulonglong insert_id_for_cur_row;
/*
/**
Interval returned by get_auto_increment() and being consumed by the
inserter.
*/
......@@ -1066,7 +1066,7 @@ public:
/* TODO: DBUG_ASSERT(inited == NONE); */
}
virtual handler *clone(MEM_ROOT *mem_root);
/* This is called after create to allow us to set up cached variables */
/** This is called after create to allow us to set up cached variables */
void init()
{
cached_table_flags= table_flags();
......@@ -1092,7 +1092,7 @@ public:
{ return (ha_table_flags() & HA_NO_TRANSACTIONS) == 0; }
virtual uint extra_rec_buf_length() const { return 0; }
/*
/**
This method is used to analyse the error to see whether the error
is ignorable or not, certain handlers can have more error that are
ignorable than others. E.g. the partition handler can get inserts
......@@ -1112,12 +1112,12 @@ public:
return TRUE;
}
/*
/**
Number of rows in table. It will only be called if
(table_flags() & (HA_HAS_RECORDS | HA_STATS_RECORDS_IS_EXACT)) != 0
*/
virtual ha_rows records() { return stats.records; }
/*
/**
Return upper bound of current number of records in the table
(max. of how many records one will retrieve when doing a full table scan)
If upper bound is not known, HA_POS_ERROR should be returned as a max
......@@ -1126,7 +1126,7 @@ public:
virtual ha_rows estimate_rows_upper_bound()
{ return stats.records+EXTRA_RECORDS; }
/*
/**
Get the row type from the storage engine. If this method returns
ROW_TYPE_NOT_USED, the information in HA_CREATE_INFO should be used.
*/
......@@ -1174,7 +1174,7 @@ public:
}
Table_flags ha_table_flags() const { return cached_table_flags; }
/*
/**
Signal that the table->read_set and table->write_set table maps changed
The handler is allowed to set additional bits in the above map in this
call. Normally the handler should ignore all calls until we have done
......@@ -1186,7 +1186,7 @@ public:
virtual int open(const char *name, int mode, uint test_if_locked)=0;
virtual int close(void)=0;
/*
/**
These functions represent the public interface to *users* of the
handler class, hence they are *not* virtual. For the inheritance
interface, see the (private) functions write_row(), update_row(),
......@@ -1197,36 +1197,28 @@ public:
int ha_update_row(const uchar * old_data, uchar * new_data);
int ha_delete_row(const uchar * buf);
/*
SYNOPSIS
start_bulk_update()
RETURN
0 Bulk update used by handler
1 Bulk update not used, normal operation used
/**
@retval 0 Bulk update used by handler
@retval 1 Bulk update not used, normal operation used
*/
virtual bool start_bulk_update() { return 1; }
/*
SYNOPSIS
start_bulk_delete()
RETURN
0 Bulk delete used by handler
1 Bulk delete not used, normal operation used
/**
@retval 0 Bulk delete used by handler
@retval 1 Bulk delete not used, normal operation used
*/
virtual bool start_bulk_delete() { return 1; }
/*
SYNOPSIS
/**
This method is similar to update_row, however the handler doesn't need
to execute the updates at this point in time. The handler can be certain
that another call to bulk_update_row will occur OR a call to
exec_bulk_update before the set of updates in this query is concluded.
bulk_update_row()
old_data Old record
new_data New record
dup_key_found Number of duplicate keys found
RETURN
0 Bulk delete used by handler
1 Bulk delete not used, normal operation used
@param old_data Old record
@param new_data New record
@param dup_key_found Number of duplicate keys found
@retval 0 Bulk delete used by handler
@retval 1 Bulk delete not used, normal operation used
*/
virtual int bulk_update_row(const uchar *old_data, uchar *new_data,
uint *dup_key_found)
......@@ -1234,53 +1226,43 @@ public:
DBUG_ASSERT(FALSE);
return HA_ERR_WRONG_COMMAND;
}
/*
SYNOPSIS
/**
After this call all outstanding updates must be performed. The number
of duplicate key errors are reported in the duplicate key parameter.
It is allowed to continue to the batched update after this call, the
handler has to wait until end_bulk_update with changing state.
exec_bulk_update()
dup_key_found Number of duplicate keys found
RETURN
0 Success
>0 Error code
@param dup_key_found Number of duplicate keys found
@retval 0 Success
@retval >0 Error code
*/
virtual int exec_bulk_update(uint *dup_key_found)
{
DBUG_ASSERT(FALSE);
return HA_ERR_WRONG_COMMAND;
}
/*
SYNOPSIS
/**
Perform any needed clean-up, no outstanding updates are there at the
moment.
end_bulk_update()
RETURN
Nothing
*/
virtual void end_bulk_update() { return; }
/*
SYNOPSIS
/**
Execute all outstanding deletes and close down the bulk delete.
end_bulk_delete()
RETURN
0 Success
>0 Error code
@retval 0 Success
@retval >0 Error code
*/
virtual int end_bulk_delete()
{
DBUG_ASSERT(FALSE);
return HA_ERR_WRONG_COMMAND;
}
private:
private:
virtual int index_read(uchar * buf, const uchar * key, uint key_len,
enum ha_rkey_function find_flag)
{ return HA_ERR_WRONG_COMMAND; }
public:
public:
/**
@brief
Positions an index cursor to the index specified in the handle. Fetches the
......@@ -1315,7 +1297,7 @@ public:
private:
virtual int index_read_last(uchar * buf, const uchar * key, uint key_len)
{ return (my_errno=HA_ERR_WRONG_COMMAND); }
public:
public:
/**
@brief
The following functions works like index_read, but it find the last
......@@ -1343,11 +1325,11 @@ public:
virtual int ft_read(uchar *buf) { return HA_ERR_WRONG_COMMAND; }
virtual int rnd_next(uchar *buf)=0;
virtual int rnd_pos(uchar * buf, uchar *pos)=0;
/*
one has to use this method when to find
/**
One has to use this method when to find
random position by record as the plain
position() call doesn't work for some
handlers for random position
handlers for random position.
*/
virtual int rnd_pos_by_record(uchar *record)
{
......@@ -1355,9 +1337,9 @@ public:
return rnd_pos(record, ref);
}
virtual int read_first_row(uchar *buf, uint primary_key);
/*
/**
The following function is only needed for tables that may be temporary
tables during joins
tables during joins.
*/
virtual int restart_rnd_next(uchar *buf, uchar *pos)
{ return HA_ERR_WRONG_COMMAND; }
......@@ -1374,13 +1356,13 @@ public:
virtual int extra_opt(enum ha_extra_function operation, ulong cache_size)
{ return extra(operation); }
/*
Reset state of file to after 'open'
/**
Reset state of file to after 'open'.
This function is called after every statement for all tables used
by that statement.
*/
virtual int reset() { return 0; }
/*
/**
In an UPDATE or DELETE, if the row under the cursor was locked by another
transaction, and the engine used an optimistic read of the last
committed row value under the cursor, then the engine returns 1 from this
......@@ -1393,7 +1375,7 @@ public:
engine that the next read will be a locking re-read of the row.
*/
virtual bool was_semi_consistent_read() { return 0; }
/*
/**
Tell the engine whether it should avoid unnecessary lock waits.
If yes, in an UPDATE or DELETE, if the row under the cursor was locked
by another transaction, the engine may try an optimistic read of
......@@ -1402,7 +1384,7 @@ public:
virtual void try_semi_consistent_read(bool) {}
virtual void unlock_row() {}
virtual int start_stmt(THD *thd, thr_lock_type lock_type) {return 0;}
/*
/**
This is called to delete all rows in a table
If the handler don't support this, then this function will
return HA_ERR_WRONG_COMMAND and MySQL will delete the rows one
......@@ -1438,7 +1420,7 @@ public:
next_insert_id= (prev_insert_id > 0) ? prev_insert_id :
insert_id_for_cur_row;
}
/*
/**
Reset the auto-increment counter to the given value, i.e. the next row
inserted will get the given value. This is called e.g. after TRUNCATE
is emulated by doing a 'DELETE FROM t'. HA_ERR_WRONG_COMMAND is
......@@ -1451,27 +1433,27 @@ public:
protected:
/* to be implemented in handlers */
/* admin commands - called from mysql_admin_table */
/** admin commands - called from mysql_admin_table */
virtual int check(THD* thd, HA_CHECK_OPT* check_opt)
{ return HA_ADMIN_NOT_IMPLEMENTED; }
/*
in these two methods check_opt can be modified
/**
In these two methods check_opt can be modified
to specify CHECK option to use to call check()
upon the table
upon the table.
*/
virtual int check_for_upgrade(HA_CHECK_OPT *check_opt)
{ return 0; }
public:
int ha_check_for_upgrade(HA_CHECK_OPT *check_opt);
int check_old_types();
/* to be actually called to get 'check()' functionality*/
/** to be actually called to get 'check()' functionality*/
int ha_check(THD *thd, HA_CHECK_OPT *check_opt);
virtual int backup(THD* thd, HA_CHECK_OPT* check_opt)
{ return HA_ADMIN_NOT_IMPLEMENTED; }
/*
restore assumes .frm file must exist, and that generate_table() has been
/**
Restore assumes .frm file must exist, and that generate_table() has been
called; It will just copy the data file and run repair.
*/
virtual int restore(THD* thd, HA_CHECK_OPT* check_opt)
......@@ -1512,17 +1494,15 @@ public:
virtual char *update_table_comment(const char * comment)
{ return (char*) comment;}
virtual void append_create_info(String *packet) {}
/*
SYNOPSIS
is_fk_defined_on_table_or_index()
index Index to check if foreign key uses it
RETURN VALUE
TRUE Foreign key defined on table or index
FALSE No foreign key defined
DESCRIPTION
/**
If index == MAX_KEY then a check for table is made and if index <
MAX_KEY then a check is made if the table has foreign keys and if
a foreign key uses this index (and thus the index cannot be dropped).
@param index Index to check if foreign key uses it
@retval TRUE Foreign key defined on table or index
@retval FALSE No foreign key defined
*/
virtual bool is_fk_defined_on_table_or_index(uint index)
{ return FALSE; }
......@@ -1530,18 +1510,18 @@ public:
{ return(NULL);} /* gets foreign key create string from InnoDB */
virtual char* get_tablespace_name(THD *thd, char *name, uint name_len)
{ return(NULL);} /* gets tablespace name from handler */
/* used in ALTER TABLE; 1 if changing storage engine is allowed */
/** used in ALTER TABLE; 1 if changing storage engine is allowed */
virtual bool can_switch_engines() { return 1; }
/* used in REPLACE; is > 0 if table is referred by a FOREIGN KEY */
/** used in REPLACE; is > 0 if table is referred by a FOREIGN KEY */
virtual int get_foreign_key_list(THD *thd, List<FOREIGN_KEY_INFO> *f_key_list)
{ return 0; }
virtual uint referenced_by_foreign_key() { return 0;}
virtual void init_table_handle_for_HANDLER()
{ return; } /* prepare InnoDB for HANDLER */
virtual void free_foreign_key_create_info(char* str) {}
/* The following can be called without an open handler */
/** The following can be called without an open handler */
virtual const char *table_type() const =0;
/*
/**
If frm_error() is called then we will use this to find out what file
extentions exist for the storage engine. This is also used by the default
rename_table and delete_table method in handler.cc.
......@@ -1598,7 +1578,7 @@ public:
virtual bool is_crashed() const { return 0; }
virtual bool auto_repair() const { return 0; }
/*
/**
default rename_table() and delete_table() rename/delete files with a
given name and extensions from bas_ext()
*/
......@@ -1658,7 +1638,7 @@ public:
THR_LOCK_DATA **to,
enum thr_lock_type lock_type)=0;
/* Type of table for caching query */
/** Type of table for caching query */
virtual uint8 table_cache_type() { return HA_CACHE_TBL_NONTRANSACT; }
......@@ -1704,9 +1684,9 @@ public:
/*
RETURN
true Primary key (if there is one) is clustered key covering all fields
false otherwise
@retval TRUE Primary key (if there is one) is clustered
key covering all fields
@retval FALSE otherwise
*/
virtual bool primary_key_is_clustered() { return FALSE; }
virtual int cmp_ref(const uchar *ref1, const uchar *ref2)
......@@ -1718,19 +1698,18 @@ public:
Condition pushdown to storage engines
*/
/*
/**
Push condition down to the table handler.
SYNOPSIS
cond_push()
cond Condition to be pushed. The condition tree must not be
@param cond Condition to be pushed. The condition tree must not be
modified by the by the caller.
RETURN
@return
The 'remainder' condition that caller must use to filter out records.
NULL means the handler will not return rows that do not match the
passed condition.
NOTES
@note
The pushed conditions form a stack (from which one can remove the
last pushed condition using cond_pop).
The table handler filters out rows using (pushed_cond1 AND pushed_cond2
......@@ -1742,18 +1721,17 @@ public:
condition stack.
*/
virtual const COND *cond_push(const COND *cond) { return cond; };
/*
/**
Pop the top condition from the condition stack of the handler instance.
SYNOPSIS
cond_pop()
Pops the top if condition stack, if stack is not empty
Pops the top if condition stack, if stack is not empty.
*/
virtual void cond_pop() { return; };
virtual bool check_if_incompatible_data(HA_CREATE_INFO *create_info,
uint table_changes)
{ return COMPATIBLE_DATA_NO; }
/* These are only called from sql_select for internal temporary tables */
/** These are only called from sql_select for internal temporary tables */
virtual int write_row(uchar *buf __attribute__((unused)))
{
return HA_ERR_WRONG_COMMAND;
......@@ -1769,7 +1747,7 @@ public:
{
return HA_ERR_WRONG_COMMAND;
}
/*
/**
use_hidden_primary_key() is called in case of an update/delete when
(table_flags() and HA_PRIMARY_KEY_REQUIRED_FOR_DELETE) is defined
but we don't have a primary key
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7