Some documentation

include/PgSQL_Backend.h

@@ -3,23 +3,25 @@
 #include "proxysql.h"
 #include "cpp.h"
 
-
+/*
+ * @brief A backend class handling connections and data streams for PostgreSQL clients.
+ */
 class PgSQL_Backend
 {
 	public:
 	void * operator new(size_t);
 	void operator delete(void *);
-	int hostgroup_id;
-	char gtid_uuid[128];
-	uint64_t gtid_trxid;
+	int hostgroup_id; //< The ID of the host group this connection belongs to. Set to -1 if uninitialized
+	char gtid_uuid[128]; //< An array to store a unique identifier for each transaction : for now unused
+	uint64_t gtid_trxid; //< The ID of the current transaction : for now unused
 	PgSQL_Data_Stream *server_myds;
 	//  mysql_cp_entry_t *server_mycpe;
-	bytes_stats_t server_bytes_at_cmd;
+	bytes_stats_t server_bytes_at_cmd; //< A structure storing the number of bytes received and sent
 	//MySQL_Hostgroup_Entry *mshge;
 	//MySQL_Connection *myconn;
 	PgSQL_Backend();
 	~PgSQL_Backend();
-	void reset();
+	void reset(); //< A method that resets and releases resources associated with this backend instance
 };
 
 #endif /* __CLASS_POSTGRESQL_BACKEND_H */

lib/PgSQL_Protocol.cpp

@@ -433,6 +433,16 @@ bool PgSQL_Protocol::generate_pkt_initial_handshake(bool send, void** _ptr, unsi
 	return true;
 }
 
+/*
+ * @brief Reads and converts a big endian 32-bit unsigned integer from the provided packet buffer into the destination pointer.
+ *
+ * This function is used to extract the big endian 32-bit unsigned integer value at the specified position in a given
+ * packet buffer, and stores it in the destination pointer passed as an argument.
+ *
+ * @param[in] pkt A pointer to the start of the input packet buffer from which to read the 32-bit integer.
+ *
+ * @param[out] dst_p A pointer where the extracted big endian 32-bit unsigned integer value will be stored.
+ */
 static inline bool get_uint32be(unsigned char* pkt, uint32_t* dst_p)
 {
 	int read_pos = 0;
@@ -447,13 +457,31 @@ static inline bool get_uint32be(unsigned char* pkt, uint32_t* dst_p)
 }
 
 
+/**
+ * @brief Extracts a 16-bit unsigned integer from a packet and stores it in the provided destination pointer.
+ *
+ * This function reads two bytes from the packet `pkt` starting from the beginning, interprets them as a big-endian unsigned 16-bit integer,
+ * and stores the result into the memory location pointed to by `dst_p`. It consistently returns true to indicate successful execution.
+ *
+ * @param pkt Pointer to the packet data (array of unsigned chars) from which the 16-bit integer will be extracted.
+ *             The caller must ensure this pointer is valid and points to at least two bytes of data.
+ * @param dst_p Pointer to a uint16_t variable where the extracted integer will be stored. The caller must ensure that
+ *             this pointer is valid and points to a uint16_t variable.
+ *
+ * @return Always returns true to indicate success.
+ *
+ * @note This function uses big-endian byte order (network byte order) for interpreting the packet data.
+ *       It is assumed that the packet buffer `pkt` contains at least two bytes (the size of a uint16_t).
+ *       The function uses post-increment to move the reading position after extracting each byte.
+ */
 static inline bool get_uint16be(unsigned char* pkt, uint16_t* dst_p)
 {
-	int read_pos = 0;
+	int read_pos = 0; ///< Current read position in the buffer.
 	unsigned a, b;
 
-	a = pkt[read_pos++];
-	b = pkt[read_pos++];
+	// Read the two bytes from the buffer
+	a = pkt[read_pos++]; ///< First byte read from the buffer.
+	b = pkt[read_pos++]; ///< Second byte read from the buffer.
 	*dst_p = (a << 8) | b;
 	return true;
 }
@@ -1187,4 +1215,4 @@ bool PgSQL_Protocol::generate_ok_packet(bool send, bool ready, const char* msg,
 
 	free(tag);
 	return true;
-}
+}

lib/ProxySQL_Admin.cpp

@@ -13531,7 +13531,8 @@ void ProxySQL_Admin::__refresh_pgsql_users(
 	);
 }
 
-/* @brief Sends an OK message to a client based on the connection type.
+/*
+ * @brief Sends an OK message to a client based on the connection type.
  *
  * This function is used to send an OK message and some additional data
  * (number of rows or query) to the client depending on its database
@@ -13563,17 +13564,18 @@ void ProxySQL_Admin::send_ok_msg_to_client(Client_Session<T>& sess, const char*
 		assert(0);
 }
 
-/* @brief Sends an error message to a client based on its database management system.
-*
-* This function is used to send an error message with a given code and message
-* (if applicable) to the client depending on its database management system
-* (MySQL or PostgreSQL).
-*
-* @tparam T The type of the Client_Session object passed as argument.
-* @param[in, out] sess A reference to a valid Client_Session object.
-* @param msg An error message that will be sent to the client.
-* @param mysqlerrcode (For MySQL clients) The error code associated with this
-* error message.
+/*
+ * @brief Sends an error message to a client based on its database management system.
+ *
+ * This function is used to send an error message with a given code and message
+ * (if applicable) to the client depending on its database management system
+ * (MySQL or PostgreSQL).
+ *
+ * @tparam T The type of the Client_Session object passed as argument.
+ * @param[in, out] sess A reference to a valid Client_Session object.
+ * @param msg An error message that will be sent to the client.
+ * @param mysqlerrcode (For MySQL clients) The error code associated with this
+ * error message.
 */
 template <class T>
 void ProxySQL_Admin::send_error_msg_to_client(Client_Session<T>& sess, const char *msg, uint16_t mysql_err_code /*, bool fatal*/ ) {