From 9a55e974290cd8c5a883184d114e7ce410c2ebcc Mon Sep 17 00:00:00 2001 From: Rene Cannao Date: Tue, 25 Nov 2025 16:34:36 +0000 Subject: [PATCH] docs: Add comprehensive Doxygen documentation for GTID refactoring - Document addGtidInterval() function with parameter details and reconnection behavior - Add documentation for readall() method explaining robust error handling - Document connect_cb() and reader_cb() callbacks with resource management details - Document generate_mysql_gtid_executed_tables() with multi-phase process explanation - Focus on functionality, thread safety, and performance improvements - Provide clear parameter descriptions and return value semantics --- lib/GTID_Server_Data.cpp | 87 ++++++++++++++++++++++++++++++++ lib/MySQL_HostGroups_Manager.cpp | 24 +++++++++ 2 files changed, 111 insertions(+) diff --git a/lib/GTID_Server_Data.cpp b/lib/GTID_Server_Data.cpp index 0e8146fb1..6fdb3ebc2 100644 --- a/lib/GTID_Server_Data.cpp +++ b/lib/GTID_Server_Data.cpp @@ -41,6 +41,29 @@ static void gtid_timer_cb (struct ev_loop *loop, struct ev_timer *timer, int rev return; } +/** + * @brief Data reception callback for established GTID server connections + * + * This callback handles reading GTID data from established connections to binlog readers. + * It processes incoming GTID information and manages connection failures gracefully. + * + * On successful read: + * - Processes the received GTID data + * - Calls dump() to parse and update GTID sets + * + * On read failure: + * - Marks the server connection as inactive + * - Sets gtid_missing_nodes flag to trigger reconnection + * - Performs proper cleanup of socket and watcher resources + * - Clears the watcher reference to maintain clean state + * + * @param loop The event loop (unused in this implementation) + * @param w The I/O watcher for data reception + * @param revents The events that triggered this callback + * + * @note This function is critical for maintaining GTID synchronization stability + * @note Proper resource cleanup prevents memory leaks and maintains system stability + */ void reader_cb(struct ev_loop *loop, struct ev_io *w, int revents) { pthread_mutex_lock(&ev_loop_mutex); if (revents & EV_READ) { @@ -63,6 +86,30 @@ void reader_cb(struct ev_loop *loop, struct ev_io *w, int revents) { pthread_mutex_unlock(&ev_loop_mutex); } +/** + * @brief Connection establishment callback for GTID server connections + * + * This callback is triggered when a non-blocking connect() operation completes. + * It handles both successful connections and connection failures with proper + * resource cleanup and state management. + * + * On successful connection: + * - Stops and frees the connect watcher + * - Creates a new read watcher for data reception + * - Starts the read watcher to begin GTID data processing + * + * On connection failure: + * - Marks server as inactive + * - Logs appropriate warning messages + * - Performs proper cleanup of socket and watcher resources + * + * @param loop The event loop (unused in this implementation) + * @param w The I/O watcher for the connection + * @param revents The events that triggered this callback + * + * @note This function ensures proper resource management to prevent memory leaks + * @note Takes ev_loop_mutex to ensure thread-safe operations + */ void connect_cb(EV_P_ ev_io *w, int revents) { pthread_mutex_lock(&ev_loop_mutex); if (revents & EV_WRITE) { @@ -166,6 +213,23 @@ GTID_Server_Data::~GTID_Server_Data() { free(data); } +/** + * @brief Reads data from the GTID server connection socket + * + * Reads available data from the socket connection to the binlog reader. + * Handles different read conditions to provide robust connection management: + * - Successful read: Data is appended to internal buffer + * - EOF (rc == 0): Connection was gracefully closed by peer + * - Error conditions: Distinguishes between transient (EINTR/EAGAIN) and fatal errors + * + * This function is critical for maintaining stable GTID synchronization and + * properly detecting connection failures for reconnection handling. + * + * @return bool True if read was successful or should be retried, false on fatal errors + * + * @note Expands buffer automatically when full to prevent data loss + * @note EINTR and EAGAIN are not treated as errors for non-blocking sockets + */ bool GTID_Server_Data::readall() { if (size == len) { // buffer is full, expand @@ -412,6 +476,29 @@ void addGtid(const gtid_t& gtid, gtid_set_t& gtid_executed) { } } +/** + * @brief Adds or updates a GTID interval in the executed set + * + * This function intelligently merges GTID intervals to prevent events_count reset + * when a binlog reader reconnects and provides updated GTID sets. It handles + * reconnection scenarios where the server provides updated transaction ID ranges. + * + * For example, during reconnection: + * - Before disconnection: server_UUID:1-10 + * - After reconnection: server_UUID:1-19 + * + * This function will update the existing interval rather than replacing it, + * preserving the events_count metric accuracy. + * + * @param gtid_executed Reference to the GTID set to update + * @param server_uuid The server UUID string + * @param txid_start Starting transaction ID of the interval + * @param txid_end Ending transaction ID of the interval + * @return bool True if the GTID set was updated, false if interval already existed + * + * @note This function is critical for maintaining accurate GTID metrics across + * binlog reader reconnections and preventing events_count resets. + */ bool addGtidInterval(gtid_set_t& gtid_executed, std::string server_uuid, int64_t txid_start, int64_t txid_end) { bool updated = true; diff --git a/lib/MySQL_HostGroups_Manager.cpp b/lib/MySQL_HostGroups_Manager.cpp index 4e5e2b136..27244a7c9 100644 --- a/lib/MySQL_HostGroups_Manager.cpp +++ b/lib/MySQL_HostGroups_Manager.cpp @@ -1680,6 +1680,30 @@ bool MySQL_HostGroups_Manager::gtid_exists(MySrvC *mysrvc, char * gtid_uuid, uin return ret; } +/** + * @brief Generates and manages GTID connection tables for all MySQL servers + * + * This function synchronizes the GTID server connections with the current MySQL server + * configuration. It handles server additions, removals, and reconnections with improved + * lifecycle management for stable operation. + * + * The function operates in several phases: + * 1. Mark all existing GTID connections as potentially stale + * 2. Iterate through configured MySQL servers to validate existing connections + * 3. Establish new connections for servers that don't have active GTID connections + * 4. Clean up stale connections for servers that are no longer configured + * + * Key improvements in this implementation: + * - Uses stale_server tracking for efficient cleanup + * - Maintains proper lock ordering (gtid_rwlock → wrlock) + * - Reuses existing GTID_Server_Data objects when possible + * - Proper cleanup of ev_io watchers and socket resources + * + * @note This function must be called with appropriate locking to prevent race conditions + * @note Servers with OFFLINE_HARD status are skipped for connection establishment + * + * @thread_safety Thread-safe when called with proper external synchronization + */ void MySQL_HostGroups_Manager::generate_mysql_gtid_executed_tables() { // NOTE: We are required to lock while iterating over 'MyHostGroups'. Otherwise race conditions could take place, // e.g. servers could be purged by 'purge_mysql_servers_table' and invalid memory be accessed.