update docs

lxzan · Dec 26, 2023 · e55dcc3 · e55dcc3
1 parent d1a5d3b
commit e55dcc3
Show file tree

Hide file tree

Showing 2 changed files with 62 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ GOMAXPROCS=4, Connection=1000, CompressEnabled=false
 
 ![performance](assets/performance-compress-disabled.png)
 
-> gorilla and nhooyr not using streaming api
+> gorilla and nhooyr not using stream api
 
 #### GoBench
 
@@ -69,8 +69,8 @@ PASS
 - [Introduction](#introduction)
 - [Why GWS](#why-gws)
 - [Benchmark](#benchmark)
-  - [IOPS (Echo Server)](#iops-echo-server)
-  - [GoBench](#gobench)
+	- [IOPS (Echo Server)](#iops-echo-server)
+	- [GoBench](#gobench)
 - [Index](#index)
 - [Feature](#feature)
 - [Attention](#attention)
@@ -79,10 +79,11 @@ PASS
 - [Quick Start](#quick-start)
 - [Best Practice](#best-practice)
 - [More Examples](#more-examples)
-  - [KCP](#kcp)
-  - [Proxy](#proxy)
-  - [Broadcast](#broadcast)
-  - [Pub / Sub](#pub--sub)
+	- [KCP](#kcp)
+	- [Proxy](#proxy)
+	- [Broadcast](#broadcast)
+	- [WriteWithTimeout](#writewithtimeout)
+	- [Pub / Sub](#pub--sub)
 - [Autobahn Test](#autobahn-test)
 - [Communication](#communication)
 - [Acknowledgments](#acknowledgments)
@@ -113,7 +114,7 @@ go get -v github.com/lxzan/gws@latest
 ```go
 type Event interface {
     OnOpen(socket *Conn)                        // connection is established
-    OnClose(socket *Conn, err error)            // received a close frame or I/O error occurs
+    OnClose(socket *Conn, err error)            // received a close frame or input/output error occurs
     OnPing(socket *Conn, payload []byte)        // received a ping frame
     OnPong(socket *Conn, payload []byte)        // received a pong frame
     OnMessage(socket *Conn, message *Message)   // received a text/binary frame
@@ -122,10 +123,6 @@ type Event interface {
 
 ### Quick Start
 
-Very, very, very simple example.
-
-The example let you know how to use the `gws` package without any other dependencies.
-
 ```go
 package main
 
@@ -289,6 +286,27 @@ func Broadcast(conns []*gws.Conn, opcode gws.Opcode, payload []byte) {
 }
 ```
 
+#### WriteWithTimeout
+
+`SetDeadline` covers most of the scenarios, but if you want to control the timeout for each write, you need to
+encapsulate the `WriteWithTimeout` function, the creation and destruction of the `timer` will incur some overhead.
+
+```go
+func WriteWithTimeout(socket *gws.Conn, p []byte, timeout time.Duration) error {
+	var sig = atomic.Uint32{}
+	var timer = time.AfterFunc(timeout, func() {
+		if sig.CompareAndSwap(0, 1) {
+			socket.WriteClose(1000, []byte("write timeout"))
+		}
+	})
+	var err = socket.WriteMessage(gws.OpcodeText, p)
+	if sig.CompareAndSwap(0, 1) {
+		timer.Stop()
+	}
+	return err
+}
+```
+
 #### Pub / Sub
 
 Use the event_emitter package to implement the publish-subscribe model. Wrap `gws.Conn` in a structure and implement the GetSubscriberID method to get the subscription ID, which must be unique. The subscription ID is used to identify the subscriber, who can only receive messages on the subject of his subscription.
@@ -341,7 +359,7 @@ docker run -it --rm \
 
 ### Communication
 
-> 微信需要先添加好友, 然后拉人入群, 请注明来意.
+> 微信需要先添加好友再拉群, 请注明来自 GitHub
 
 <div>
 <img src="assets/wechat.png" alt="WeChat" width="300" height="300" style="display: inline-block;"/>

diff --git a/README_CN.md b/README_CN.md
@@ -40,7 +40,7 @@ GOMAXPROCS=4, Connection=1000, CompressEnabled=false
 
 ![performance](assets/performance-compress-disabled.png)
 
-> gorilla 和 nhooyr 未使用流式 API
+> Gorilla 和 Nhooyr 未使用 Stream API
 
 #### GoBench
 
@@ -61,8 +61,8 @@ PASS
 - [介绍](#介绍)
 - [为什么选择 GWS](#为什么选择-gws)
 - [基准测试](#基准测试)
-  - [IOPS (Echo Server)](#iops-echo-server)
-  - [GoBench](#gobench)
+	- [IOPS (Echo Server)](#iops-echo-server)
+	- [GoBench](#gobench)
 - [Index](#index)
 - [特性](#特性)
 - [注意](#注意)
@@ -71,10 +71,11 @@ PASS
 - [快速上手](#快速上手)
 - [最佳实践](#最佳实践)
 - [更多用例](#更多用例)
-  - [KCP](#kcp)
-  - [代理](#代理)
-  - [广播](#广播)
-  - [发布/订阅](#发布订阅)
+	- [KCP](#kcp)
+	- [代理](#代理)
+	- [广播](#广播)
+	- [写入超时](#写入超时)
+	- [发布/订阅](#发布订阅)
 - [Autobahn 测试](#autobahn-测试)
 - [交流](#交流)
 - [致谢](#致谢)
@@ -105,7 +106,7 @@ go get -v github.com/lxzan/gws@latest
 ```go
 type Event interface {
     OnOpen(socket *Conn)                        // connection is established
-    OnClose(socket *Conn, err error)            // received a close frame or I/O error occurs
+    OnClose(socket *Conn, err error)            // received a close frame or input/output error occurs
     OnPing(socket *Conn, payload []byte)        // received a ping frame
     OnPong(socket *Conn, payload []byte)        // received a pong frame
     OnMessage(socket *Conn, message *Message)   // received a text/binary frame
@@ -114,10 +115,6 @@ type Event interface {
 
 ### 快速上手
 
-非常、非常、非常简单的例子。
-
-这个例子让你知道如何在没有任何其他依赖的情况下使用 `gws` 软件包。
-
 ```go
 package main
 
@@ -281,6 +278,27 @@ func Broadcast(conns []*gws.Conn, opcode gws.Opcode, payload []byte) {
 }
 ```
 
+#### 写入超时
+
+`SetDeadline` 可以覆盖大部分使用场景, 想要精细地控制每一次写入的超时时间, 则需要自行封装下 `WriteWithTimeout`
+函数, `timer` 的创建和销毁会有一定额外开销.
+
+```go
+func WriteWithTimeout(socket *gws.Conn, p []byte, timeout time.Duration) error {
+	var sig = atomic.Uint32{}
+	var timer = time.AfterFunc(timeout, func() {
+		if sig.CompareAndSwap(0, 1) {
+			socket.WriteClose(1000, []byte("write timeout"))
+		}
+	})
+	var err = socket.WriteMessage(gws.OpcodeText, p)
+	if sig.CompareAndSwap(0, 1) {
+		timer.Stop()
+	}
+	return err
+}
+```
+
 #### 发布/订阅
 
 使用 event_emitter 包实现发布订阅模式。用结构体包装 `gws.Conn`，并实现 GetSubscriberID 方法以获取订阅 ID，该 ID 必须是唯一的。订阅 ID 用于识别订阅者，订阅者只能接收其订阅主题的消息。
@@ -333,7 +351,7 @@ docker run -it --rm \
 
 ### 交流
 
-> 微信需要先添加好友, 然后拉人入群, 请注明来意.
+> 微信需要先添加好友再拉群, 请注明来自 GitHub
 
 <div>
 <img src="assets/wechat.png" alt="WeChat" width="300" height="300" style="display: inline-block;"/>