Merge pull request #294 from chdb-io/patchset-3.0

Patchset 3.0

Author: auxten

README-zh.md

@@ -30,7 +30,7 @@
 
 ## 架构
 <div align="center">
-  <img src="docs/_static/arch-chdb2.png" width="450">
+  <img src="docs/_static/arch-chdb3.png" width="450">
 </div>
 
 ## 安装方式

README.md

@@ -33,7 +33,7 @@
 
 ## Arch
 <div align="center">
-  <img src="https://github.com/chdb-io/chdb/raw/main/docs/_static/arch-chdb2.png" width="450">
+  <img src="https://github.com/chdb-io/chdb/raw/main/docs/_static/arch-chdb3.png" width="450">
 </div>
 
 ## Get Started

docs/_static/arch-chdb3.png

@@ -66,7 +66,7 @@ struct query_queue
 {
     std::mutex mutex;
     std::condition_variable query_cv; // For query submission
-    std::condition_variable result_cv;
+    std::condition_variable result_cv; // For query result retrieval
     query_request current_query;
     local_result_v2 * current_result = nullptr;
     bool has_query = false;
@@ -75,15 +75,47 @@ struct query_queue
 };
 #endif
 
+/**
+ * Connection structure for chDB
+ * Contains server instance, connection state, and query processing queue
+ */
 struct chdb_conn
 {
-    void * server; // LocalServer * server;
-    bool connected;
-    void * queue; // query_queue*
+    void * server; /* ClickHouse LocalServer instance */
+    bool connected; /* Connection state flag */
+    void * queue; /* Query processing queue */
 };
 
+/**
+ * Creates a new chDB connection.
+ * Only one active connection is allowed per process.
+ * Creating a new connection with different path requires closing existing connection.
+ * 
+ * @param argc Number of command-line arguments
+ * @param argv Command-line arguments array (--path=<db_path> to specify database location)
+ * @return Pointer to connection pointer, or NULL on failure
+ * @note Default path is ":memory:" if not specified
+ */
 CHDB_EXPORT struct chdb_conn ** connect_chdb(int argc, char ** argv);
+
+/**
+ * Closes an existing chDB connection and cleans up resources.
+ * Thread-safe function that handles connection shutdown and cleanup.
+ * 
+ * @param conn Pointer to connection pointer to close
+ */
 CHDB_EXPORT void close_conn(struct chdb_conn ** conn);
+
+/**
+ * Executes a query on the given connection.
+ * Thread-safe function that handles query execution in a separate thread.
+ * 
+ * @param conn Connection to execute query on
+ * @param query SQL query string to execute
+ * @param format Output format string (e.g., "CSV", default format)
+ * @return Query result structure containing output or error message
+ * @note Returns error result if connection is invalid or closed
+ */
 CHDB_EXPORT struct local_result_v2 * query_conn(struct chdb_conn * conn, const char * query, const char * format);
 
 #ifdef __cplusplus