From 8576423de864d532e82bfabbd314d040852fd56b Mon Sep 17 00:00:00 2001 From: Sven Sandberg Date: Fri, 9 Jan 2009 13:49:24 +0100 Subject: BUG#41924: high-level replication functions are not commented Adding comments to some of the high-level functions in replication. sql/log_event.h: Fixed some mistakes in comments. sql/repl_failsafe.cc: Added comment for show_slave_hosts() sql/slave.cc: Added comment for show_master_info(), handle_slave_[sql|io](), and next_event() sql/sql_binlog.cc: Added @param comment. sql/sql_lex.h: Added comment for st_lex_master_info. sql/sql_repl.cc: Added comments for functions executing a statement: PURGE BINARY LOGS START SLAVE STOP SLAVE RESET SLAVE CHANGE MASTER RESET MASTER SHOW BINLOG EVENTS SHOW MASTER STATUS SHOW BINARY LOGS --- sql/log_event.h | 22 +++++---- sql/repl_failsafe.cc | 10 +++++ sql/slave.cc | 39 ++++++++++++++-- sql/sql_binlog.cc | 5 ++- sql/sql_lex.h | 9 ++++ sql/sql_repl.cc | 123 ++++++++++++++++++++++++++++++++++++++++++--------- 6 files changed, 172 insertions(+), 36 deletions(-) diff --git a/sql/log_event.h b/sql/log_event.h index 185d2d21a02..e546cff8b7b 100644 --- a/sql/log_event.h +++ b/sql/log_event.h @@ -327,18 +327,16 @@ struct sql_ex_info #define Q_CHARSET_DATABASE_CODE 8 #define Q_TABLE_MAP_FOR_UPDATE_CODE 9 -/* Intvar event post-header */ +/* Intvar event data */ #define I_TYPE_OFFSET 0 #define I_VAL_OFFSET 1 -/* Rand event post-header */ - +/* Rand event data */ #define RAND_SEED1_OFFSET 0 #define RAND_SEED2_OFFSET 8 -/* User_var event post-header */ - +/* User_var event data */ #define UV_VAL_LEN_SIZE 4 #define UV_VAL_IS_NULL 1 #define UV_VAL_TYPE_SIZE 1 @@ -346,7 +344,6 @@ struct sql_ex_info #define UV_CHARSET_NUMBER_SIZE 4 /* Load event post-header */ - #define L_THREAD_ID_OFFSET 0 #define L_EXEC_TIME_OFFSET 4 #define L_SKIP_LINES_OFFSET 8 @@ -357,7 +354,6 @@ struct sql_ex_info #define L_DATA_OFFSET LOAD_HEADER_LEN /* Rotate event post-header */ - #define R_POS_OFFSET 0 #define R_IDENT_OFFSET 8 @@ -2214,10 +2210,11 @@ protected: @section Intvar_log_event_binary_format Binary Format - The Post-Header has two components: + The Post-Header for this event type is empty. The Body has two + components: - + @@ -2291,11 +2288,12 @@ private: which are stored internally as two 64-bit numbers. @section Rand_log_event_binary_format Binary Format - This event type has no Post-Header. The Body of this event type has - two components: + + The Post-Header for this event type is empty. The Body has two + components:
Post-Header for Intvar_log_eventBody for Intvar_log_event
Name
- + diff --git a/sql/repl_failsafe.cc b/sql/repl_failsafe.cc index d7e783f534f..582348608de 100644 --- a/sql/repl_failsafe.cc +++ b/sql/repl_failsafe.cc @@ -644,6 +644,16 @@ err: } #endif + +/** + Execute a SHOW SLAVE HOSTS statement. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @retval FALSE success + @retval TRUE failure +*/ bool show_slave_hosts(THD* thd) { List field_list; diff --git a/sql/slave.cc b/sql/slave.cc index 43b70f29a68..22c61b3ec6c 100644 --- a/sql/slave.cc +++ b/sql/slave.cc @@ -1357,6 +1357,17 @@ int register_slave_on_master(MYSQL* mysql, Master_info *mi, } +/** + Execute a SHOW SLAVE STATUS statement. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @param mi Pointer to Master_info object for the IO thread. + + @retval FALSE success + @retval TRUE failure +*/ bool show_master_info(THD* thd, Master_info* mi) { // TODO: fix this for multi-master @@ -2062,7 +2073,7 @@ int apply_event_and_update_pos(Log_event* ev, THD* thd, Relay_log_info* rli, fewer times, 0 is returned. - init_master_info or init_relay_log_pos failed. (These are called - if a failure occurs when applying the event.) + if a failure occurs when applying the event.) - An error occurred when updating the binlog position. @@ -2307,8 +2318,14 @@ static int try_to_reconnect(THD *thd, MYSQL *mysql, Master_info *mi, } -/* Slave I/O Thread entry point */ +/** + Slave IO thread entry point. + + @param arg Pointer to Master_info struct that holds information for + the IO thread. + @return Always 0. +*/ pthread_handler_t handle_slave_io(void *arg) { THD *thd; // needs to be first for thread_stack @@ -2616,8 +2633,14 @@ err: } -/* Slave SQL Thread entry point */ +/** + Slave SQL thread entry point. + + @param arg Pointer to Relay_log_info object that holds information + for the SQL thread. + @return Always 0. +*/ pthread_handler_t handle_slave_sql(void *arg) { THD *thd; /* needs to be first for thread_stack */ @@ -3710,6 +3733,16 @@ static IO_CACHE *reopen_relay_log(Relay_log_info *rli, const char **errmsg) } +/** + Reads next event from the relay log. Should be called from the + slave IO thread. + + @param rli Relay_log_info structure for the slave IO thread. + + @return The event read, or NULL on error. If an error occurs, the + error is reported through the sql_print_information() or + sql_print_error() functions. +*/ static Log_event* next_event(Relay_log_info* rli) { Log_event* ev; diff --git a/sql/sql_binlog.cc b/sql/sql_binlog.cc index 7ca7bef3a56..96e99b57e3c 100644 --- a/sql/sql_binlog.cc +++ b/sql/sql_binlog.cc @@ -18,7 +18,7 @@ #include "base64.h" /** - Execute a BINLOG statement + Execute a BINLOG statement. To execute the BINLOG command properly the server needs to know which format the BINLOG command's event is in. Therefore, the first @@ -26,6 +26,9 @@ Format_description_log_event, as outputted by mysqlbinlog. This Format_description_log_event is cached in rli->description_event_for_exec. + + @param thd Pointer to THD object for the client thread executing the + statement. */ void mysql_client_binlog_statement(THD* thd) diff --git a/sql/sql_lex.h b/sql/sql_lex.h index 26bd8d18750..ed6b9e7d8df 100644 --- a/sql/sql_lex.h +++ b/sql/sql_lex.h @@ -190,6 +190,15 @@ typedef struct st_lex_server_options char *server_name, *host, *db, *username, *password, *scheme, *socket, *owner; } LEX_SERVER_OPTIONS; + +/** + Structure to hold parameters for CHANGE MASTER or START/STOP SLAVE + or SHOW NEW MASTER. + + Remark: this should not be confused with Master_info (and perhaps + would better be renamed to st_lex_replication_info). Some fields, + e.g., delay, are saved in Relay_log_info, not in Master_info. +*/ typedef struct st_lex_master_info { char *host, *user, *password, *log_file_name; diff --git a/sql/sql_repl.cc b/sql/sql_repl.cc index eac7a50417a..646bfdaefe8 100644 --- a/sql/sql_repl.cc +++ b/sql/sql_repl.cc @@ -257,6 +257,17 @@ bool purge_error_message(THD* thd, int res) } +/** + Execute a PURGE BINARY LOGS TO command. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @param to_log Name of the last log to purge. + + @retval FALSE success + @retval TRUE failure +*/ bool purge_master_logs(THD* thd, const char* to_log) { char search_file_name[FN_REFLEN]; @@ -273,6 +284,17 @@ bool purge_master_logs(THD* thd, const char* to_log) } +/** + Execute a PURGE BINARY LOGS BEFORE command. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @param purge_time Date before which logs should be purged. + + @retval FALSE success + @retval TRUE failure +*/ bool purge_master_logs_before_date(THD* thd, time_t purge_time) { if (!mysql_bin_log.is_open()) @@ -765,6 +787,20 @@ err: DBUG_VOID_RETURN; } + +/** + Execute a START SLAVE statement. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @param mi Pointer to Master_info object for the slave's IO thread. + + @param net_report If true, saves the exit status into thd->main_da. + + @retval 0 success + @retval 1 error +*/ int start_slave(THD* thd , Master_info* mi, bool net_report) { int slave_errno= 0; @@ -890,6 +926,19 @@ int start_slave(THD* thd , Master_info* mi, bool net_report) } +/** + Execute a STOP SLAVE statement. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @param mi Pointer to Master_info object for the slave's IO thread. + + @param net_report If true, saves the exit status into thd->main_da. + + @retval 0 success + @retval 1 error +*/ int stop_slave(THD* thd, Master_info* mi, bool net_report ) { DBUG_ENTER("stop_slave"); @@ -942,20 +991,17 @@ int stop_slave(THD* thd, Master_info* mi, bool net_report ) } -/* - Remove all relay logs and start replication from the start - - SYNOPSIS - reset_slave() - thd Thread handler - mi Master info for the slave +/** + Execute a RESET SLAVE statement. - RETURN - 0 ok - 1 error -*/ + @param thd Pointer to THD object of the client thread executing the + statement. + @param mi Pointer to Master_info object for the slave. + @retval 0 success + @retval 1 error +*/ int reset_slave(THD *thd, Master_info* mi) { MY_STAT stat_area; @@ -1070,6 +1116,18 @@ void kill_zombie_dump_threads(uint32 slave_server_id) } +/** + Execute a CHANGE MASTER statement. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @param mi Pointer to Master_info object belonging to the slave's IO + thread. + + @retval FALSE success + @retval TRUE error +*/ bool change_master(THD* thd, Master_info* mi) { int thread_mask; @@ -1283,6 +1341,16 @@ bool change_master(THD* thd, Master_info* mi) DBUG_RETURN(FALSE); } + +/** + Execute a RESET MASTER statement. + + @param thd Pointer to THD object of the client thread executing the + statement. + + @retval 0 success + @retval 1 error +*/ int reset_master(THD* thd) { if (!mysql_bin_log.is_open()) @@ -1312,6 +1380,15 @@ int cmp_master_pos(const char* log_file_name1, ulonglong log_pos1, } +/** + Execute a SHOW BINLOG EVENTS statement. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @retval FALSE success + @retval TRUE failure +*/ bool mysql_show_binlog_events(THD* thd) { Protocol *protocol= thd->protocol; @@ -1462,6 +1539,15 @@ err: } +/** + Execute a SHOW MASTER STATUS statement. + + @param thd Pointer to THD object for the client thread executing the + statement. + + @retval FALSE success + @retval TRUE failure +*/ bool show_binlog_info(THD* thd) { Protocol *protocol= thd->protocol; @@ -1495,18 +1581,15 @@ bool show_binlog_info(THD* thd) } -/* - Send a list of all binary logs to client +/** + Execute a SHOW BINARY LOGS statement. - SYNOPSIS - show_binlogs() - thd Thread specific variable + @param thd Pointer to THD object for the client thread executing the + statement. - RETURN VALUES - FALSE OK - TRUE error + @retval FALSE success + @retval TRUE failure */ - bool show_binlogs(THD* thd) { IO_CACHE *index_file; -- cgit v1.2.1
Post-Header for Intvar_log_eventBody for Rand_log_event
Name