Add doc.go

2019-10-13 22:38:15 +08:00 · 2019-10-13 22:38:15 +08:00 · 023672e877
parent 4db04ca4a6
commit 023672e877
3 changed files with 53 additions and 41 deletions
--- 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)
--- 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,7 +252,7 @@ func WithPanicHandler(panicHandler func(interface{})) Option {
 通过在调用`NewPool`/`NewPoolWithFunc`之时使用各种 optional function，可以设置`ants.Options`中各个配置项的值，然后用它来定制化 goroutine pool.


-## 自定义池
+### 自定义池
 `ants`支持实例化使用者自己的一个 Pool ，指定具体的池容量；通过调用 `NewPool` 方法可以实例化一个新的带有指定容量的 Pool ，如下：

 ``` go
@ -258,14 +260,14 @@ func WithPanicHandler(panicHandler func(interface{})) Option {
 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)
--- 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