dev upgrade doc.md

2023-10-27 15:31:41 +08:00 · 2023-10-27 15:31:41 +08:00 · 71579fb90e
commit 71579fb90e
parent a59a9e3278
3 changed files with 247 additions and 3 deletions
--- a/README.txt
+++ b/README.txt
@ -5,9 +5,10 @@

 测试用例:
 	所有test用例使用cmake构建
+	(server测试用例属于线程不安全程序(仅用于测试ssocket.h),不可用实际项目)

 函数文档:
-	(函数文档全部采用markdown格式即*.md,可以使用VS打开)
+	(函数文档全部采用markdown格式即*.md,可以使用VS打开,推荐使用专用markdown编辑器打开,不推荐以文本类型(.txt)打开)
 	函数文档见doc.md

 案例讲解:
@ -36,5 +37,33 @@
 	sock_connect()用于改变连接到服务器的地址，同样用于和服务器通信

 	线程函数伪代码解释:
-	thread_create
-	thread_mutex_init()
+	1.thread_create()用于创建线程函数其中start_routine为返回类型void,参数为void*的函数指针
+		arg用于将参数传递进start_routine函数内
+
+	2.thread_mutex_init()该类型函数使用thread_mutex_lock(),thread_mutex_unlock()实现
+		对于一块代码的加锁访问,以实现线程同步 (WARNING注意thread_mutex_unlock及时释放锁防止线程死锁)
+
+	3.thread_cond_init()该类型函数与thread_mutex_init()等配合使用,常用于同步线程
+	
+	示例:
+		MUTEX mutex;
+		COND cond;
+
+		//初始化相关资源
+		thread_mutex_init(&mutex);
+		thread_cond_init(&cond);
+
+		//进入线程同步区域
+		thread_mutex_lock(&mutex);
+		...
+		//进入该函数会阻塞于此直到调用
+		//thread_cond_singal(唤醒一个),thread_cond_broadcast(唤醒所有)
+		//唤醒才可以返回,以取消阻塞
+		thread_cond_wait(&cond, &mutex);
+		...
+		thread_mutex_unlock(&mutex);
+		//离开线程同步区域
+
+	4.tprintf()等类型输出函数格式为 t*()
+		eg. t + printf => tprintf
+		这类函数须在第一个参数前添加有效的mutex,用于实现线程同步,保证线程安全(我也不知道属不属于可重入函数)
--- a/doc.md
+++ b/doc.md
@ -0,0 +1,211 @@
+[TOC]
+
+# 函数列表
+
+## 注意事项
+
+具体函数请点击链接或打开doc文件夹直接查找
+
+## 套接字函数 ssocket.h
+
+#### socket套接字相关
+
+###### [`static inline int sock_accpet(SOCKET sock,SOCKET* client, char** accept_ip, unsigned short* port);`](./doc/document.md)
+
+将有效的套接字绑定并监听网络以提供套接字服务,返回0表示成功
+
+
+
+###### [`static inline int make_server_sock(SOCKET* sock, const char* server_ip, unsigned short port);`](./doc/document.md)
+
+
+
+###### [`static inline int make_client_sock(SOCKET* sock, const char* connect_ip, unsigned short port);`](./doc/document.md)
+
+
+
+###### [`static inline void close_sock(SOCKET sock);`](./doc/document.md)
+
+
+
+###### [`static inline int make_server_sock_ex(SOCKET* sock, const char* server_ip, unsigned short port, struct addrinfo** resaddr);`](./doc/document.md)
+
+
+
+###### [`static inline int make_client_sock_ex(SOCKET* sock, const char* connect_ip, unsigned short port, struct addrinfo** resaddr);`](./doc/document.md)
+
+
+
+#### 错误处理(暂时未启用)
+
+###### [`static inline void out_sock_err(FILE* output, int errcode);`](./doc/document.md)
+
+
+
+###### [`static inline void get_sock_err(char* buff_128, size_t buff_len, int errcode);`](./doc/document.md)
+
+
+
+#### 内置函数
+
+###### [`static inline int _getaddrinfo(struct addrinfo* inf, struct addrinfo** resaddr, const char* ip, const char* port);`](./doc/document.md)
+
+
+
+###### [`static inline int _socket(SOCKET* sock, struct addrinfo* resaddr);`](./doc/document.md)
+
+
+
+###### [`static inline int _connect(SOCKET sock, struct addrinfo* resaddr);`](./doc/document.md)
+
+
+
+###### [`static inline int _bind(SOCKET sock, struct addrinfo* resaddr);`](./doc/document.md)
+
+
+
+###### [`static inline int _bindlisten(SOCKET sock, struct addrinfo* resaddr);`](./doc/document.md)
+
+
+
+###### [`static inline int _accept(SOCKET sock, SOCKET* client, struct addrinfo* inf);`](./doc/document.md)
+
+
+
+###### [`static inline int _sock(SOCKET* sock, int af, int type);`](./doc/document.md)
+
+
+
+#### 手动创建socket
+
+###### [`static inline int make_sock_tcp4(SOCKET* sock);`](./doc/document.md)
+
+
+
+###### [`static inline int make_sock_tcp6(SOCKET* sock);`](./doc/document.md)
+
+
+
+###### [`static inline int make_sock_udp4(SOCKET* sock);`](./doc/document.md)
+
+
+
+###### [`static inline int make_sock_udp6(SOCKET* sock);`](./doc/document.md)
+
+
+
+###### [`static inline int make_sock(SOCKET* sock);`](./doc/document.md)
+
+初始化套接字接口,返回0表示成功
+
+不推荐,仅用于测试,将在未来版本删除
+
+
+
+###### [`static inline int sock_connect(SOCKET sock, const char* connect_ip, unsigned short port);`](./doc/document.md)
+
+将有效的套接字连接到相应的套接字服务,返回0表示成功
+
+
+
+###### [`static inline int sock_bindlisten(SOCKET sock, const char* server_ip, unsigned short port);`](./doc/document.md)
+
+将有效的套接字绑定并监听网络以提供套接字服务,返回0表示成功
+
+###### 
+
+### 线程函数 tthread.h
+
+#### thread线程相关
+
+###### [`static inline int thread_create(TID* tid, void(*start_routine)(void*), void* arg);`](./doc/document.md)
+
+
+
+###### [`static inline void thread_exit(void);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_join(TID tid);`](./doc/document.md)
+
+
+
+###### [`static inline TID thread_self(void);`](./doc/document.md)
+
+
+
+#### mutex互斥锁相关
+
+###### [`static inline int thread_mutex_init(MUTEX* mutex);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_mutex_destroy(MUTEX* mutex);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_mutex_lock(MUTEX* mutex);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_mutex_unlock(MUTEX* mutex);`](./doc/document.md)
+
+
+
+#### cond信号量相关
+
+###### [`static inline int thread_cond_init(COND* cond);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_cond_destroy(COND* cond);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_cond_singal(COND* cond);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_cond_broadcast(COND* cond);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_cond_wait(COND* cond, MUTEX* mutex);`](./doc/document.md)
+
+
+
+###### [`static inline int thread_cond_timedwait(COND* cond, MUTEX* mutex, int ms);`](./doc/document.md)
+
+
+
+#### stdio标准函数的线程安全
+
+###### [`static inline int tprintf(MUTEX* mutex, const char* format, ...);`](./doc/document.md)
+
+
+
+###### [`static inline int tfprintf(MUTEX* mutex, FILE* const stream, const char* format, ...);`](./doc/document.md)
+
+
+
+###### [`static inline int tsprintf(MUTEX* mutex, char* const buffer, const char* format, ...);`](./doc/document.md)
+
+
+
+###### [`static inline int tsnprintf(MUTEX* mutex, char* const buffer, const size_t buffer_count, const char* format, ...);`](./doc/document.md)
+
+
+
+###### [`static inline int tvprintf(MUTEX* mutex, const char* format, va_list arglist);`](./doc/document.md)
+
+
+
+###### [`static inline int tvfprintf(MUTEX* mutex, FILE* const stream, const char* format, va_list arglist);`](./doc/document.md)
+
+
+
+###### [`static inline int tvsprintf(MUTEX* mutex, char* const buffer, const char* format, va_list arglist);`](./doc/document.md)
+
+
+
+###### [`static inline int tvsnprintf(MUTEX* mutex, char* const buffer, const size_t buffer_count, const char* format, va_list arglist);`](./doc/document.md)
--- a/doc/document.md
+++ b/doc/document.md
@ -0,0 +1,4 @@
+
+
+###### sock_connect
+