Doxygenized comments.

This commit is contained in:
cmiller@zippy.cornsilk.net 2007-10-16 15:37:31 -04:00
parent 2d615a6169
commit dee842e093
10 changed files with 2103 additions and 2108 deletions

View file

@ -1817,8 +1817,8 @@ static void relink_unused(TABLE *table)
/**
@brief Remove all instances of table from thread's open list and
table cache.
Remove all instances of table from thread's open list and
table cache.
@param thd Thread context
@param find Table to remove
@ -1867,7 +1867,7 @@ void unlink_open_table(THD *thd, TABLE *find, bool unlock)
/**
@brief Auxiliary routine which closes and drops open table.
Auxiliary routine which closes and drops open table.
@param thd Thread handle
@param table TABLE object for table to be dropped
@ -2039,9 +2039,9 @@ bool reopen_name_locked_table(THD* thd, TABLE_LIST* table_list, bool link_in)
/**
@brief Create and insert into table cache placeholder for table
which will prevent its opening (or creation) (a.k.a lock
table name).
Create and insert into table cache placeholder for table
which will prevent its opening (or creation) (a.k.a lock
table name).
@param thd Thread context
@param key Table cache key for name to be locked
@ -2090,8 +2090,8 @@ TABLE *table_cache_insert_placeholder(THD *thd, const char *key,
/**
@brief Obtain an exclusive name lock on the table if it is not cached
in the table cache.
Obtain an exclusive name lock on the table if it is not cached
in the table cache.
@param thd Thread context
@param db Name of database
@ -2142,8 +2142,8 @@ bool lock_table_name_if_not_cached(THD *thd, const char *db,
/**
@brief Check that table exists in table definition cache, on disk
or in some storage engine.
Check that table exists in table definition cache, on disk
or in some storage engine.
@param thd Thread context
@param table Table list element
@ -2815,8 +2815,8 @@ bool reopen_table(TABLE *table)
/**
@brief Close all instances of a table open by this thread and replace
them with exclusive name-locks.
Close all instances of a table open by this thread and replace
them with exclusive name-locks.
@param thd Thread context
@param db Database name for the table to be closed
@ -2867,7 +2867,7 @@ void close_data_files_and_morph_locks(THD *thd, const char *db,
/**
@brief Reopen all tables with closed data files.
Reopen all tables with closed data files.
@param thd Thread context
@param get_locks Should we get locks after reopening tables ?
@ -2957,8 +2957,8 @@ bool reopen_tables(THD *thd,bool get_locks,bool in_refresh)
/**
@brief Close handlers for tables in list, but leave the TABLE structure
intact so that we can re-open these quickly.
Close handlers for tables in list, but leave the TABLE structure
intact so that we can re-open these quickly.
@param thd Thread context
@param table Head of the list of TABLE objects

View file

@ -1524,7 +1524,7 @@ void Query_cache::invalidate(THD *thd, const char *key, uint32 key_length,
/**
@brief Synchronize the thread with any flushing operations.
Synchronize the thread with any flushing operations.
This helper function is called whenever a thread needs to operate on the
query cache structure (example: during invalidation). If a table flush is in
@ -1565,7 +1565,7 @@ void Query_cache::wait_while_table_flush_is_in_progress(bool *interrupt)
/**
@brief Remove all cached queries that uses the given database
Remove all cached queries that uses the given database.
*/
void Query_cache::invalidate(char *db)
@ -1675,8 +1675,8 @@ void Query_cache::flush()
/**
@brief Rearrange the memory blocks and join result in cache in 1 block (if
result length > join_limit)
Rearrange the memory blocks and join result in cache in 1 block (if
result length > join_limit)
@param[in] join_limit If the minimum length of a result block to be joined.
@param[in] iteration_limit The maximum number of packing and joining
@ -1946,7 +1946,7 @@ void Query_cache::make_disabled()
/**
@class Query_cache
@brief Free all resources allocated by the cache.
Free all resources allocated by the cache.
This function frees all resources allocated by the cache. You
have to call init_cache() before using the cache again. This function
@ -1970,7 +1970,7 @@ void Query_cache::free_cache()
/**
@brief Flush the cache.
Flush the cache.
This function will flush cache contents. It assumes we have
'structure_guard_mutex' locked. The function sets the m_cache_status flag and
@ -2516,7 +2516,7 @@ Query_cache::invalidate_table_internal(THD *thd, uchar *key, uint32 key_length)
}
/**
@brief Invalidate a linked list of query cache blocks.
Invalidate a linked list of query cache blocks.
Each block tries to aquire a block level lock before
free_query is a called. This function will in turn affect
@ -2684,7 +2684,7 @@ my_bool Query_cache::register_all_tables(Query_cache_block *block,
/**
@brief Insert used table name into the cache.
Insert used table name into the cache.
@return Error status
@retval FALSE On error
@ -3413,8 +3413,8 @@ my_bool Query_cache::ask_handler_allowance(THD *thd,
/**
@brief Rearrange all memory blocks so that free memory joins at the
'bottom' of the allocated memory block containing all cache data.
Rearrange all memory blocks so that free memory joins at the
'bottom' of the allocated memory block containing all cache data.
@see Query_cache::pack(ulong join_limit, uint iteration_limit)
*/
@ -4028,7 +4028,7 @@ void Query_cache::tables_dump()
/**
@brief Checks integrity of the various linked lists
Checks integrity of the various linked lists
@return Error status code
@retval FALSE Query cache is operational.

View file

@ -934,7 +934,7 @@ void THD::cleanup_after_query()
/**
Create a LEX_STRING in this connection
Create a LEX_STRING in this connection.
@param lex_str pointer to LEX_STRING object to be initialized
@param str initializer to be copied into lex_str

View file

@ -24,9 +24,9 @@
Declarations.
****************************************************************************/
/*
/**
Sensitive_cursor -- a sensitive non-materialized server side
cursor An instance of this class cursor has its own runtime
cursor. An instance of this class cursor has its own runtime
state -- list of used items and memory root for runtime memory,
open and locked tables, change list for the changes of the
parsed tree. This state is freed when the cursor is closed.
@ -69,7 +69,7 @@ public:
};
/*
/**
Materialized_cursor -- an insensitive materialized server-side
cursor. The result set of this cursor is saved in a temporary
table at open. The cursor itself is simply an interface for the
@ -96,7 +96,7 @@ public:
};
/*
/**
Select_materialize -- a mediator between a cursor query and the
protocol. In case we were not able to open a non-materialzed
cursor, it creates an internal temporary HEAP table, and insert
@ -107,7 +107,7 @@ public:
class Select_materialize: public select_union
{
select_result *result; /* the result object of the caller (PS or SP) */
select_result *result; /**< the result object of the caller (PS or SP) */
public:
Select_materialize(select_result *result_arg) :result(result_arg) {}
virtual bool send_fields(List<Item> &list, uint flags);
@ -116,22 +116,21 @@ public:
/**************************************************************************/
/*
/**
Attempt to open a materialized or non-materialized cursor.
SYNOPSIS
mysql_open_cursor()
thd thread handle
flags [in] create a materialized cursor or not
result [in] result class of the caller used as a destination
for the rows fetched from the cursor
pcursor [out] a pointer to store a pointer to cursor in
@param thd thread handle
@param[in] flags create a materialized cursor or not
@param[in] result result class of the caller used as a destination
for the rows fetched from the cursor
@param[out] pcursor a pointer to store a pointer to cursor in
RETURN VALUE
0 the query has been successfully executed; in this
case pcursor may or may not contain
a pointer to an open cursor.
non-zero an error, 'pcursor' has been left intact.
@retval
0 the query has been successfully executed; in this
case pcursor may or may not contain
a pointer to an open cursor.
@retval
non-zero an error, 'pcursor' has been left intact.
*/
int mysql_open_cursor(THD *thd, uint flags, select_result *result,
@ -279,6 +278,14 @@ Sensitive_cursor::Sensitive_cursor(THD *thd, select_result *result_arg)
}
/**
Save THD state into cursor.
@todo
- XXX: thd->locked_tables is not changed.
- What problems can we have with it if cursor is open?
- TODO: must be fixed because of the prelocked mode.
*/
void
Sensitive_cursor::post_open(THD *thd)
{
@ -334,6 +341,10 @@ Sensitive_cursor::post_open(THD *thd)
}
/**
bzero cursor state in THD.
*/
void
Sensitive_cursor::reset_thd(THD *thd)
{
@ -393,20 +404,13 @@ Sensitive_cursor::open(JOIN *join_arg)
}
/*
SYNOPSIS
Sensitive_cursor::fetch()
num_rows fetch up to this number of rows (maybe less)
/**
Fetch next num_rows rows from the cursor and send them to the client.
DESCRIPTION
Fetch next num_rows rows from the cursor and send them to the client
Precondition:
- Sensitive_cursor is open
Precondition:
Sensitive_cursor is open
RETURN VALUES:
none, this function will send OK to the clinet or set an error
message in THD
@param num_rows fetch up to this number of rows (maybe less)
*/
void
@ -478,6 +482,11 @@ Sensitive_cursor::fetch(ulong num_rows)
}
/**
@todo
Another hack: we need to set THD state as if in a fetch to be
able to call stmt close.
*/
void
Sensitive_cursor::close()
{
@ -579,10 +588,9 @@ int Materialized_cursor::open(JOIN *join __attribute__((unused)))
}
/*
/**
Fetch up to the given number of rows from a materialized cursor.
DESCRIPTION
Precondition: the cursor is open.
If the cursor points after the last row, the fetch will automatically
@ -590,10 +598,6 @@ int Materialized_cursor::open(JOIN *join __attribute__((unused)))
with SERVER_STATUS_LAST_ROW_SENT). This is an extra round trip
and probably should be improved to return
SERVER_STATUS_LAST_ROW_SENT along with the last row.
RETURN VALUE
none, in case of success the row is sent to the client, otherwise
an error message is set in THD
*/
void Materialized_cursor::fetch(ulong num_rows)

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

View file

@ -168,7 +168,7 @@ static const LEX_STRING triggers_file_type=
const char * const TRG_EXT= ".TRG";
/*
/**
Table of .TRG file field descriptors.
We have here only one field now because in nearest future .TRG
files will be merged into .FRM files (so we don't need something
@ -216,7 +216,7 @@ File_option sql_modes_parameters=
FILE_OPTIONS_ULLLIST
};
/*
/**
This must be kept up to date whenever a new option is added to the list
above, as it specifies the number of required parameters of the trigger in
.trg file.
@ -292,23 +292,27 @@ private:
};
/*
/**
Create or drop trigger for table.
SYNOPSIS
mysql_create_or_drop_trigger()
thd - current thread context (including trigger definition in LEX)
tables - table list containing one table for which trigger is created.
create - whenever we create (TRUE) or drop (FALSE) trigger
@param thd current thread context (including trigger definition in LEX)
@param tables table list containing one table for which trigger is created.
@param create whenever we create (TRUE) or drop (FALSE) trigger
NOTE
@note
This function is mainly responsible for opening and locking of table and
invalidation of all its instances in table cache after trigger creation.
Real work on trigger creation/dropping is done inside Table_triggers_list
methods.
RETURN VALUE
@todo
TODO: We should check if user has TRIGGER privilege for table here.
Now we just require SUPER privilege for creating/dropping because
we don't have proper privilege checking for triggers in place yet.
@retval
FALSE Success
@retval
TRUE error
*/
bool mysql_create_or_drop_trigger(THD *thd, TABLE_LIST *tables, bool create)
@ -479,29 +483,28 @@ end:
}
/*
/**
Create trigger for table.
SYNOPSIS
create_trigger()
thd - current thread context (including trigger definition in
LEX)
tables - table list containing one open table for which the
trigger is created.
stmt_query - [OUT] after successful return, this string contains
well-formed statement for creating this trigger.
@param thd current thread context (including trigger definition in
LEX)
@param tables table list containing one open table for which the
trigger is created.
@param[out] stmt_query after successful return, this string contains
well-formed statement for creation this trigger.
NOTE
@note
- Assumes that trigger name is fully qualified.
- NULL-string means the following LEX_STRING instance:
{ str = 0; length = 0 }.
{ str = 0; length = 0 }.
- In other words, definer_user and definer_host should contain
simultaneously NULL-strings (non-SUID/old trigger) or valid strings
(SUID/new trigger).
simultaneously NULL-strings (non-SUID/old trigger) or valid strings
(SUID/new trigger).
RETURN VALUE
False - success
True - error
@retval
False success
@retval
True error
*/
bool Table_triggers_list::create_trigger(THD *thd, TABLE_LIST *tables,
String *stmt_query)
@ -767,19 +770,18 @@ err_with_cleanup:
}
/*
Deletes the .TRG file for a table
/**
Deletes the .TRG file for a table.
SYNOPSIS
rm_trigger_file()
path - char buffer of size FN_REFLEN to be used
for constructing path to .TRG file.
db - table's database name
table_name - table's name
@param path char buffer of size FN_REFLEN to be used
for constructing path to .TRG file.
@param db table's database name
@param table_name table's name
RETURN VALUE
False - success
True - error
@retval
False success
@retval
True error
*/
static bool rm_trigger_file(char *path, const char *db,
@ -790,19 +792,18 @@ static bool rm_trigger_file(char *path, const char *db,
}
/*
Deletes the .TRN file for a trigger
/**
Deletes the .TRN file for a trigger.
SYNOPSIS
rm_trigname_file()
path - char buffer of size FN_REFLEN to be used
for constructing path to .TRN file.
db - trigger's database name
table_name - trigger's name
@param path char buffer of size FN_REFLEN to be used
for constructing path to .TRN file.
@param db trigger's database name
@param table_name trigger's name
RETURN VALUE
False - success
True - error
@retval
False success
@retval
True error
*/
static bool rm_trigname_file(char *path, const char *db,
@ -813,17 +814,16 @@ static bool rm_trigname_file(char *path, const char *db,
}
/*
/**
Helper function that saves .TRG file for Table_triggers_list object.
SYNOPSIS
save_trigger_file()
triggers Table_triggers_list object for which file should be saved
db Name of database for subject table
table_name Name of subject table
@param triggers Table_triggers_list object for which file should be saved
@param db Name of database for subject table
@param table_name Name of subject table
RETURN VALUE
@retval
FALSE Success
@retval
TRUE Error
*/
@ -842,21 +842,26 @@ static bool save_trigger_file(Table_triggers_list *triggers, const char *db,
}
/*
/**
Drop trigger for table.
SYNOPSIS
drop_trigger()
thd - current thread context
(including trigger definition in LEX)
tables - table list containing one open table for which trigger
is dropped.
stmt_query - [OUT] after successful return, this string contains
well-formed statement for deleting this trigger.
@param thd current thread context
(including trigger definition in LEX)
@param tables table list containing one open table for which trigger
is dropped.
@param[out] stmt_query after successful return, this string contains
well-formed statement for creation this trigger.
RETURN VALUE
False - success
True - error
@todo
Probably instead of removing .TRG file we should move
to archive directory but this should be done as part of
parse_file.cc functionality (because we will need it
elsewhere).
@retval
False success
@retval
True error
*/
bool Table_triggers_list::drop_trigger(THD *thd, TABLE_LIST *tables,
String *stmt_query)
@ -939,18 +944,17 @@ Table_triggers_list::~Table_triggers_list()
}
/*
/**
Prepare array of Field objects referencing to TABLE::record[1] instead
of record[0] (they will represent OLD.* row values in ON UPDATE trigger
and in ON DELETE trigger which will be called during REPLACE execution).
SYNOPSIS
prepare_record1_accessors()
table - pointer to TABLE object for which we are creating fields.
@param table pointer to TABLE object for which we are creating fields.
RETURN VALUE
False - success
True - error
@retval
False success
@retval
True error
*/
bool Table_triggers_list::prepare_record1_accessors(TABLE *table)
{
@ -979,12 +983,10 @@ bool Table_triggers_list::prepare_record1_accessors(TABLE *table)
}
/*
/**
Adjust Table_triggers_list with new TABLE pointer.
SYNOPSIS
set_table()
new_table - new pointer to TABLE instance
@param new_table new pointer to TABLE instance
*/
void Table_triggers_list::set_table(TABLE *new_table)
@ -998,20 +1000,26 @@ void Table_triggers_list::set_table(TABLE *new_table)
}
/*
/**
Check whenever .TRG file for table exist and load all triggers it contains.
SYNOPSIS
check_n_load()
thd - current thread context
db - table's database name
table_name - table's name
table - pointer to table object
names_only - stop after loading trigger names
@param thd current thread context
@param db table's database name
@param table_name table's name
@param table pointer to table object
@param names_only stop after loading trigger names
RETURN VALUE
False - success
True - error
@todo
A lot of things to do here e.g. how about other funcs and being
more paranoical ?
@todo
This could be avoided if there is no triggers for UPDATE and DELETE.
@retval
False success
@retval
True error
*/
bool Table_triggers_list::check_n_load(THD *thd, const char *db,
@ -1394,24 +1402,23 @@ err_with_lex_cleanup:
}
/*
Obtains and returns trigger metadata
/**
Obtains and returns trigger metadata.
SYNOPSIS
get_trigger_info()
thd - current thread context
event - trigger event type
time_type - trigger action time
name - returns name of trigger
stmt - returns statement of trigger
sql_mode - returns sql_mode of trigger
definer_user - returns definer/creator of trigger. The caller is
responsible to allocate enough space for storing definer
information.
@param thd current thread context
@param event trigger event type
@param time_type trigger action time
@param trigger_name returns name of trigger
@param trigger_stmt returns statement of trigger
@param sql_mode returns sql_mode of trigger
@param definer returns definer/creator of trigger. The caller is
responsible to allocate enough space for storing
definer information.
RETURN VALUE
False - success
True - error
@retval
False success
@retval
True error
*/
bool Table_triggers_list::get_trigger_info(THD *thd, trg_event_type event,
@ -1577,21 +1584,20 @@ bool add_table_for_trigger(THD *thd,
}
/*
/**
Drop all triggers for table.
SYNOPSIS
drop_all_triggers()
thd - current thread context
db - schema for table
name - name for table
@param thd current thread context
@param db schema for table
@param name name for table
NOTE
@note
The calling thread should hold the LOCK_open mutex;
RETURN VALUE
False - success
True - error
@retval
False success
@retval
True error
*/
bool Table_triggers_list::drop_all_triggers(THD *thd, char *db, char *name)
@ -1641,19 +1647,18 @@ end:
}
/*
/**
Update .TRG file after renaming triggers' subject table
(change name of table in triggers' definitions).
SYNOPSIS
change_table_name_in_triggers()
thd Thread context
db_name Database of subject table
old_table_name Old subject table's name
new_table_name New subject table's name
@param thd Thread context
@param db_name Database of subject table
@param old_table_name Old subject table's name
@param new_table_name New subject table's name
RETURN VALUE
@retval
FALSE Success
@retval
TRUE Failure
*/
@ -1723,21 +1728,20 @@ Table_triggers_list::change_table_name_in_triggers(THD *thd,
}
/*
Iterate though Table_triggers_list::names_list list and update .TRN files
after renaming triggers' subject table.
/**
Iterate though Table_triggers_list::names_list list and update
.TRN files after renaming triggers' subject table.
SYNOPSIS
change_table_name_in_trignames()
db_name Database of subject table
new_table_name New subject table's name
stopper Pointer to Table_triggers_list::names_list at
which we should stop updating.
@param db_name Database of subject table
@param new_table_name New subject table's name
@param stopper Pointer to Table_triggers_list::names_list at
which we should stop updating.
RETURN VALUE
@retval
0 Success
@retval
non-0 Failure, pointer to Table_triggers_list::names_list element
for which update failed.
for which update failed.
*/
LEX_STRING*
@ -1771,7 +1775,7 @@ Table_triggers_list::change_table_name_in_trignames(const char *db_name,
/**
@brief Update .TRG and .TRN files after renaming triggers' subject table.
Update .TRG and .TRN files after renaming triggers' subject table.
@param[in,out] thd Thread context
@param[in] db Old database of subject table
@ -1933,19 +1937,17 @@ bool Table_triggers_list::process_triggers(THD *thd,
}
/*
Mark fields of subject table which we read/set in its triggers as such.
/**
Mark fields of subject table which we read/set in its triggers
as such.
SYNOPSIS
mark_fields_used()
thd Current thread context
event Type of event triggers for which we are going to ins
This method marks fields of subject table which are read/set in its
triggers as such (by properly updating TABLE::read_set/write_set)
and thus informs handler that values for these fields should be
retrieved/stored during execution of statement.
DESCRIPTION
This method marks fields of subject table which are read/set in its
triggers as such (by properly updating TABLE::read_set/write_set)
and thus informs handler that values for these fields should be
retrieved/stored during execution of statement.
@param thd Current thread context
@param event Type of event triggers for which we are going to inspect
*/
void Table_triggers_list::mark_fields_used(trg_event_type event)
@ -1971,23 +1973,23 @@ void Table_triggers_list::mark_fields_used(trg_event_type event)
}
/*
Trigger BUG#14090 compatibility hook
/**
Trigger BUG#14090 compatibility hook.
SYNOPSIS
Handle_old_incorrect_sql_modes_hook::process_unknown_string()
unknown_key [in/out] reference on the line with unknown
parameter and the parsing point
base [in] base address for parameter writing (structure
like TABLE)
mem_root [in] MEM_ROOT for parameters allocation
end [in] the end of the configuration
@param[in,out] unknown_key reference on the line with unknown
parameter and the parsing point
@param[in] base base address for parameter writing
(structure like TABLE)
@param[in] mem_root MEM_ROOT for parameters allocation
@param[in] end the end of the configuration
NOTE: this hook process back compatibility for incorrectly written
sql_modes parameter (see BUG#14090).
@note
NOTE: this hook process back compatibility for incorrectly written
sql_modes parameter (see BUG#14090).
RETURN
@retval
FALSE OK
@retval
TRUE Error
*/
@ -2029,13 +2031,12 @@ Handle_old_incorrect_sql_modes_hook::process_unknown_string(char *&unknown_key,
DBUG_RETURN(FALSE);
}
/*
#define INVALID_TRIGGER_TABLE_LENGTH 15
/**
Trigger BUG#15921 compatibility hook. For details see
Handle_old_incorrect_sql_modes_hook::process_unknown_string().
*/
#define INVALID_TRIGGER_TABLE_LENGTH 15
bool
Handle_old_incorrect_trigger_table_hook::
process_unknown_string(char *&unknown_key, uchar* base, MEM_ROOT *mem_root,
@ -2074,9 +2075,9 @@ process_unknown_string(char *&unknown_key, uchar* base, MEM_ROOT *mem_root,
/**
Contruct path to TRN-file.
@param[in] thd Thread context.
@param[in] trg_name Trigger name.
@param[out] trn_path Variable to store constructed path
@param thd[in] Thread context.
@param trg_name[in] Trigger name.
@param trn_path[out] Variable to store constructed path
*/
void build_trn_path(THD *thd, const sp_name *trg_name, LEX_STRING *trn_path)
@ -2109,10 +2110,10 @@ bool check_trn_exists(const LEX_STRING *trn_path)
/**
Retrieve table name for given trigger.
@param[in] thd Thread context.
@param[in] trg_name Trigger name.
@param[in] trn_path Path to the corresponding TRN-file.
@param[out] tbl_name Variable to store retrieved table name.
@param thd[in] Thread context.
@param trg_name[in] Trigger name.
@param trn_path[in] Path to the corresponding TRN-file.
@param tbl_name[out] Variable to store retrieved table name.
@return Error status.
@retval FALSE on success.

View file

@ -84,7 +84,7 @@ static bool check_fields(THD *thd, List<Item> &items)
/**
@brief Re-read record if more columns are needed for error message.
Re-read record if more columns are needed for error message.
If we got a duplicate key error, we want to write an error
message containing the value of the duplicate key. If we do not have

View file

@ -206,7 +206,7 @@ fill_defined_view_parts (THD *thd, TABLE_LIST *view)
/**
@brief Creating/altering VIEW procedure
Creating/altering VIEW procedure
@param thd thread handler
@param views views to create