Add doc.go

panjf2000 · Oct 13, 2019 · 023672e · 023672e
1 parent 4db04ca
commit 023672e
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# ants
+<h1 align='center'>ants</h1>
 <p align="center">
 <img src="https://raw.githubusercontent.com/panjf2000/logos/master/ants/logo.png"/>
 <b>A goroutine pool for Go</b>
@@ -14,11 +14,13 @@
 <a title="Mentioned in Awesome Go" target="_blank" href="https://github.com/avelino/awesome-go"><img src="https://awesome.re/mentioned-badge-flat.svg"></a>
 </p>
 
-# [[中文](README_ZH.md)]
+English | [🇨🇳中文](README_ZH.md)
+
+## 📖 Introduction
 
 Library `ants` implements a goroutine pool with fixed capacity, managing and recycling a massive number of goroutines, allowing developers to limit the number of goroutines in your concurrent programs.
 
-## Features:
+## 🚀 Features:
 
 - Managing and recycling a massive number of goroutines automatically
 - Purging overdue goroutines periodically
@@ -27,7 +29,7 @@ Library `ants` implements a goroutine pool with fixed capacity, managing and rec
 - Efficient in memory usage and it even achieves higher performance than unlimited goroutines in Golang
 - Nonblocking mechanism
 
-## Tested in the following Golang versions:
+## ⚔️ Tested in the following Golang versions:
 
 - 1.8.x
 - 1.9.x
@@ -36,13 +38,13 @@ Library `ants` implements a goroutine pool with fixed capacity, managing and rec
 - 1.12.x
 - 1.13.x
 
-## `ants` works as the flowing flowchart
+## 💡 `ants` works as the flowing flowchart
 
 <p align="center">
 <img width="1011" alt="ants-flowchart-en" src="https://user-images.githubusercontent.com/7496278/66396509-7b42e700-ea0c-11e9-8612-b71a4b734683.png">
 </p>
 
-## How to install
+## 🧰 How to install
 
 ### For `ants` v1
 
@@ -56,7 +58,7 @@ go get -u github.com/panjf2000/ants
 go get -u github.com/panjf2000/ants/v2
 ```
 
-## How to use
+## 🛠 How to use
 Just take a imagination that your program starts a massive number of goroutines, resulting in a huge consumption of memory. To mitigate that kind of situation, all you need to do is to import `ants` package and submit all your tasks to a default pool with fixed capacity, activated when package `ants` is imported:
 
 ``` go
@@ -121,7 +123,7 @@ func main() {
 }
 ```
 
-## Integrate with http server
+### Integrate with http server
 ```go
 package main
 
@@ -176,7 +178,7 @@ func main() {
 }
 ```
 
-## Functional options for ants pool
+###  Functional options for ants pool
 
 ```go
 // Option represents the optional function.
@@ -249,7 +251,7 @@ func WithPanicHandler(panicHandler func(interface{})) Option {
 
 `ants.Options`contains all optional configurations of ants pool, which allows you to customize the goroutine pool by invoking option functions to set up each configuration in `NewPool`/`NewPoolWithFunc`method.
 
-## Customize limited pool
+### Customize limited pool
 
 `ants` also supports customizing the capacity of pool. You can invoke the `NewPool` method to instantiate a pool with a given capacity, as following:
 
@@ -258,13 +260,13 @@ func WithPanicHandler(panicHandler func(interface{})) Option {
 p, _ := ants.NewPool(10000)
 ```
 
-## Submit tasks
+### Submit tasks
 Tasks can be submitted by calling `ants.Submit(func())`
 ```go
 ants.Submit(func(){})
 ```
 
-## Tune pool capacity in runtime
+### Tune pool capacity in runtime
 You can tune the capacity of  `ants` pool in runtime with `Tune(int)`:
 
 ``` go
@@ -274,7 +276,7 @@ pool.Tune(100000) // Tune its capacity to 100000
 
 Don't worry about the synchronous problems in this case, the method here is thread-safe (or should be called goroutine-safe).
 
-## Pre-malloc goroutine queue in pool
+### Pre-malloc goroutine queue in pool
 
 `ants` allows you to pre-allocate memory of goroutine queue in pool, which may get a performance enhancement under some special certain circumstances such as the scenario that requires a pool with ultra-large capacity, meanwhile each task in goroutine lasts for a long time, in this case, pre-mallocing will reduce a lot of costs when re-slicing goroutine queue.
 
@@ -283,16 +285,16 @@ Don't worry about the synchronous problems in this case, the method here is thre
 p, _ := ants.NewPool(100000, ants.WithPreAlloc(true))
 ```
 
-## Release Pool
+### Release Pool
 
 ```go
 pool.Release()
 ```
 
-## About sequence
+## ⚙️ About sequence
 All tasks submitted to `ants` pool will not be guaranteed to be addressed in order, because those tasks scatter among a series of concurrent workers, thus those tasks would be executed concurrently.
 
-## Benchmarks
+## 🧲 Benchmarks
 
 <div align="center"><img src="https://user-images.githubusercontent.com/7496278/51515466-c7ce9e00-1e4e-11e9-89c4-bd3785b3c667.png"/></div>
  In this benchmark result, the first and second benchmarks performed test cases with 1M tasks and the rest of benchmarks performed test cases with 10M tasks, both in unlimited goroutines and `ants` pool, and the capacity of this `ants` goroutine-pool was limited to 50K.
@@ -327,20 +329,20 @@ In above benchmark result, the first and second benchmarks performed test cases
 
 ![](https://user-images.githubusercontent.com/7496278/52987732-537c2000-3437-11e9-86a6-177f00d7a1d6.png)
 
-### Performance Summary
+## 📊 Performance Summary
 
 ![](https://user-images.githubusercontent.com/7496278/63449727-3ae6d400-c473-11e9-81e3-8b3280d8288a.gif)
 
 **In conclusion, `ants` performs 2~6 times faster than goroutines without a pool and the memory consumption is reduced by 10 to 20 times.**
 
-# License
+## 📄 License
 
 Source code in `gnet` is available under the MIT [License](/LICENSE).
 
-# Relevant Articles
+## 📚 Relevant Articles
 
 -  [Goroutine 并发调度模型深度解析之手撸一个高性能协程池](https://taohuawu.club/high-performance-implementation-of-goroutine-pool)
 
-# Users of ants (please feel free to add your projects here ~~)
+## 👨‍👨‍👧‍👦 Users of ants (please feel free to add your projects here ~~)
 
 [![](https://raw.githubusercontent.com/panjf2000/logos/master/gnet/logo.png)](https://github.com/panjf2000/gnet)
diff --git a/README_ZH.md b/README_ZH.md
@@ -1,4 +1,4 @@
-# ants
+<h1 align='center'>ants</h1>
 <p align="center">
 <img src="https://raw.githubusercontent.com/panjf2000/logos/master/ants/logo.png"/>
 <b>A goroutine pool for Go</b>
@@ -14,11 +14,13 @@
 <a title="Mentioned in Awesome Go" target="_blank" href="https://github.com/avelino/awesome-go"><img src="https://awesome.re/mentioned-badge-flat.svg"></a>
 </p>
 
-# [[英文](README.md)]
+[英文](README.md) | 🇨🇳中文
+
+## 📖 简介
 
 `ants`是一个高性能的协程池，实现了对大规模 goroutine 的调度管理、goroutine 复用，允许使用者在开发并发程序的时候限制协程数量，复用资源，达到更高效执行任务的效果。
 
-## 功能：
+## 🚀 功能：
 
 - 自动调度海量的 goroutines，复用 goroutines
 - 定时清理过期的 goroutines，进一步节省资源
@@ -27,7 +29,7 @@
 - 资源复用，极大节省内存使用量；在大规模批量并发任务场景下比原生 goroutine 并发具有更高的性能
 - 非阻塞机制
 
-## 目前测试通过的Golang版本：
+## ⚔️ 目前测试通过的Golang版本：
 
 - 1.8.x
 - 1.9.x
@@ -36,13 +38,13 @@
 - 1.12.x
 - 1.13.x
 
-## `ants` 运行时的流程图如下
+## 💡 `ants` 运行时的流程图如下
 
 <p align="center">
 <img width="845" alt="ants-flowchart-cn" src="https://user-images.githubusercontent.com/7496278/66396519-7ed66e00-ea0c-11e9-9c1a-5ca54bbd61eb.png">
 </p>
 
-## 安装
+## 🧰 安装
 
 ### 使用 `ants` v1 版本:
 
@@ -56,7 +58,7 @@ go get -u github.com/panjf2000/ants
 go get -u github.com/panjf2000/ants/v2
 ```
 
-## 使用
+## 🛠 使用
 写 go 并发程序的时候如果程序会启动大量的 goroutine ，势必会消耗大量的系统资源（内存，CPU），通过使用 `ants`，可以实例化一个协程池，复用 goroutine ，节省资源，提升性能：
 
 ``` go
@@ -121,7 +123,7 @@ func main() {
 }
 ```
 
-## 与 http server 集成
+### 与 http server 集成
 ```go
 package main
 
@@ -176,7 +178,7 @@ func main() {
 }
 ```
 
-## Pool 配置
+### Pool 配置
 
 ```go
 // Option represents the optional function.
@@ -250,22 +252,22 @@ func WithPanicHandler(panicHandler func(interface{})) Option {
 通过在调用`NewPool`/`NewPoolWithFunc`之时使用各种 optional function，可以设置`ants.Options`中各个配置项的值，然后用它来定制化 goroutine pool.
 
 
-## 自定义池
+### 自定义池
 `ants`支持实例化使用者自己的一个 Pool ，指定具体的池容量；通过调用 `NewPool` 方法可以实例化一个新的带有指定容量的 Pool ，如下：
 
 ``` go
 // Set 10000 the size of goroutine pool
 p, _ := ants.NewPool(10000)
 ```
 
-## 任务提交
+### 任务提交
 
 提交任务通过调用 `ants.Submit(func())`方法：
 ```go
 ants.Submit(func(){})
 ```
 
-## 动态调整协程池容量
+### 动态调整协程池容量
 需要动态调整协程池容量可以通过调用`Tune(int)`：
 
 ``` go
@@ -275,7 +277,7 @@ pool.Tune(100000) // Tune its capacity to 100000
 
 该方法是线程安全的。
 
-## 预先分配 goroutine 队列内存
+### 预先分配 goroutine 队列内存
 
 `ants`允许你预先把整个池的容量分配内存， 这个功能可以在某些特定的场景下提高协程池的性能。比如， 有一个场景需要一个超大容量的池，而且每个 goroutine 里面的任务都是耗时任务，这种情况下，预先分配 goroutine 队列内存将会减少 re-slice 时的复制内存损耗。
 
@@ -284,15 +286,13 @@ pool.Tune(100000) // Tune its capacity to 100000
 p, _ := ants.NewPool(100000, ants.WithPreAlloc(true))
 ```
 
-
-
-## 销毁协程池
+### 销毁协程池
 
 ```go
 pool.Release()
 ```
 
-## Benchmarks
+## 🧲 Benchmarks
 
 <div align="center"><img src="https://user-images.githubusercontent.com/7496278/51515466-c7ce9e00-1e4e-11e9-89c4-bd3785b3c667.png"/></div>
 上图中的前两个 benchmark 测试结果是基于100w 任务量的条件，剩下的几个是基于 1000w 任务量的测试结果，`ants` 的默认池容量是 5w。
@@ -327,20 +327,20 @@ pool.Release()
 
 ![](https://user-images.githubusercontent.com/7496278/52987732-537c2000-3437-11e9-86a6-177f00d7a1d6.png)
 
-### 性能小结
+## 📊 性能小结
 
 ![](https://user-images.githubusercontent.com/7496278/63449727-3ae6d400-c473-11e9-81e3-8b3280d8288a.gif)
 
 **从该 demo 测试吞吐性能对比可以看出，使用`ants`的吞吐性能相较于原生 goroutine 可以保持在 2-6 倍的性能压制，而内存消耗则可以达到 10-20 倍的节省优势。** 
 
-# 证书
+## 📄 证书
 
 `gnet` 的源码允许用户在遵循 MIT [开源证书](/LICENSE) 规则的前提下使用。
 
-# 相关文章 
+## 📚 相关文章
 
 -  [Goroutine 并发调度模型深度解析之手撸一个高性能协程池](https://taohuawu.club/high-performance-implementation-of-goroutine-pool)
 
-# 谁在使用 ants（欢迎补充 ~~）
+## 👨‍👨‍👧‍👦 谁在使用 ants（欢迎补充 ~~）
 
 [![](https://raw.githubusercontent.com/panjf2000/logos/master/gnet/logo.png)](https://github.com/panjf2000/gnet)
diff --git a/doc.go b/doc.go
@@ -0,0 +1,10 @@
+// Copyright 2019 Andy Pan. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+/*
+Library ants implements a goroutine pool with fixed capacity, managing and recycling a massive number of goroutines,
+allowing developers to limit the number of goroutines in your concurrent programs.
+*/
+
+package ants