add docs

Author: alphadose

README.md

@@ -0,0 +1,121 @@
+# Itogami
+
+> The best goroutine pool till date
+
+Saves a lot of memory and is the fastest among all existing golang threadpool implementations
+
+Benchmarks to support the above claims [here](#benchmarks)
+
+## Installation
+
+You need Golang [1.18.x](https://go.dev/dl/) or above since this package uses generics
+
+```bash
+$ go get github.com/alphadose/[email protected]
+```
+
+## Usage
+
+```go
+package main
+
+import (
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/alphadose/itogami"
+)
+
+const runTimes uint32 = 1000
+
+var sum uint32
+
+func myFunc(i uint32) {
+	atomic.AddUint32(&sum, i)
+	fmt.Printf("run with %d\n", i)
+}
+
+func demoFunc() {
+	time.Sleep(10 * time.Millisecond)
+	println("Hello World")
+}
+
+func examplePool() {
+	var wg sync.WaitGroup
+	// Use the common pool
+	pool := itogami.NewPool(10)
+
+	syncCalculateSum := func() {
+		demoFunc()
+		wg.Done()
+	}
+	for i := uint32(0); i < runTimes; i++ {
+		wg.Add(1)
+		// Submit task to the pool
+		pool.Submit(syncCalculateSum)
+	}
+	wg.Wait()
+	println("finished all tasks")
+}
+
+func examplePoolWithFunc() {
+	var wg sync.WaitGroup
+	// Use the pool with a pre-defined function
+	pool := itogami.NewPoolWithFunc(10, func(i uint32) {
+		myFunc(i)
+		wg.Done()
+	})
+	for i := uint32(0); i < runTimes; i++ {
+		wg.Add(1)
+		// Invoke the function with a value
+		pool.Invoke(i)
+	}
+	wg.Wait()
+	fmt.Printf("finish all tasks, result is %d\n", sum)
+}
+
+func main() {
+	examplePool()
+	examplePoolWithFunc()
+}
+```
+
+## Benchmarks
+
+Benchmarking was performed against existing golang threadpool implementations [Ants](https://github.com/panjf2000/ants) and [Gamma-Zero-Worker-Pool](https://github.com/gammazero/workerpool) and unlimited goroutines
+
+Thread pool size -> 50k
+
+CPU -> M1, arm64, 8 cores, 3.2 GHz
+
+OS -> darwin
+
+Results were computed from [benchstat](https://pkg.go.dev/golang.org/x/perf/cmd/benchstat) of 30 cases
+```
+name                   time/op
+UnlimitedGoroutines-8   291ms ± 2%
+AntsPool-8              512ms ± 6%
+GammaZeroPool-8         713ms ±10%
+ItogamiPool-8           319ms ± 1%
+
+name                   alloc/op
+UnlimitedGoroutines-8  96.2MB ± 0%
+AntsPool-8             21.8MB ± 9%
+GammaZeroPool-8        18.8MB ± 1%
+ItogamiPool-8          25.8MB ± 3%
+
+name                   allocs/op
+UnlimitedGoroutines-8   2.00M ± 0%
+AntsPool-8              1.09M ± 3%
+GammaZeroPool-8         1.05M ± 0%
+ItogamiPool-8           1.05M ± 0%
+```
+
+The following conclusions can be drawn from the above results:-
+
+1. Itogami is the fastest among all threadpool implementations and slower only than unlimited goroutines
+2. Itogami has the least `allocs/op` and hence the memory usage scales really well with high load
+3. The memory used per operation is in the acceptable range of other threadpools and drastically lower than unlimited goroutines
+4. The tolerance (± %) for Itogami is quite low for all 3 metrics indicating that the algorithm is quite stable overall

benchmarks/constants.go

@@ -5,6 +5,6 @@ import "time"
 const (
 	RunTimes           = 1e6
 	BenchParam         = 10
-	PoolSize           = 2e5
+	PoolSize           = 5e4
 	DefaultExpiredTime = 10 * time.Second
 )

benchmarks/general_test.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"github.com/alphadose/itogami"
+	"github.com/gammazero/workerpool"
 	"github.com/panjf2000/ants/v2"
 )
 
@@ -51,6 +52,25 @@ func BenchmarkAntsPool(b *testing.B) {
 	b.StopTimer()
 }
 
+func BenchmarkGammaZeroPool(b *testing.B) {
+	var wg sync.WaitGroup
+	p := workerpool.New(PoolSize)
+
+	b.ResetTimer()
+	b.StartTimer()
+	for i := 0; i < b.N; i++ {
+		wg.Add(RunTimes)
+		for j := 0; j < RunTimes; j++ {
+			p.Submit(func() {
+				demoFunc()
+				wg.Done()
+			})
+		}
+		wg.Wait()
+	}
+	b.StopTimer()
+}
+
 func BenchmarkItogamiPool(b *testing.B) {
 	var wg sync.WaitGroup
 	p := itogami.NewPool(PoolSize)

examples/main.go

@@ -9,45 +9,55 @@ import (
 	"github.com/alphadose/itogami"
 )
 
-var sum int32
+const runTimes uint32 = 1000
 
-func myFunc(i int32) {
-	atomic.AddInt32(&sum, i)
+var sum uint32
+
+func myFunc(i uint32) {
+	atomic.AddUint32(&sum, i)
 	fmt.Printf("run with %d\n", i)
 }
 
 func demoFunc() {
 	time.Sleep(10 * time.Millisecond)
-	fmt.Println("Hello World!")
+	println("Hello World")
 }
 
-func main() {
-	runTimes := int32(1000)
-	pool := itogami.NewPool(10)
-	// Use the common pool.
+func examplePool() {
 	var wg sync.WaitGroup
+	// Use the common pool
+	pool := itogami.NewPool(10)
+
 	syncCalculateSum := func() {
 		demoFunc()
 		wg.Done()
 	}
-	for i := int32(0); i < runTimes; i++ {
+	for i := uint32(0); i < runTimes; i++ {
 		wg.Add(1)
+		// Submit task to the pool
 		pool.Submit(syncCalculateSum)
 	}
 	wg.Wait()
-	fmt.Printf("finish all tasks.\n")
+	println("finished all tasks")
+}
 
-	// Use the pool with a function,
-	// set 10 to the capacity of goroutine pool and 1 second for expired duration.
-	p := itogami.NewPoolWithFunc(10, func(i int32) {
+func examplePoolWithFunc() {
+	var wg sync.WaitGroup
+	// Use the pool with a pre-defined function
+	pool := itogami.NewPoolWithFunc(10, func(i uint32) {
 		myFunc(i)
 		wg.Done()
 	})
-	// Submit tasks one by one.
-	for i := int32(0); i < runTimes; i++ {
+	for i := uint32(0); i < runTimes; i++ {
 		wg.Add(1)
-		p.Invoke(i)
+		// Invoke the function with a value
+		pool.Invoke(i)
 	}
 	wg.Wait()
 	fmt.Printf("finish all tasks, result is %d\n", sum)
 }
+
+func main() {
+	examplePool()
+	examplePoolWithFunc()
+}

go.mod

@@ -3,6 +3,8 @@ module github.com/alphadose/itogami
 go 1.18
 
 require (
-	github.com/panjf2000/ants v1.3.0 // indirect
-	github.com/panjf2000/ants/v2 v2.5.0 // indirect
+	github.com/gammazero/workerpool v1.1.2
+	github.com/panjf2000/ants/v2 v2.5.0
 )
+
+require github.com/gammazero/deque v0.1.0 // indirect

go.sum

@@ -1,4 +1,10 @@
-github.com/panjf2000/ants v1.3.0 h1:8pQ+8leaLc9lys2viEEr8md0U4RN6uOSUCE9bOYjQ9M=
-github.com/panjf2000/ants v1.3.0/go.mod h1:AaACblRPzq35m1g3enqYcxspbbiOJJYaxU2wMpm1cXY=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/gammazero/deque v0.1.0 h1:f9LnNmq66VDeuAlSAapemq/U7hJ2jpIWa4c09q8Dlik=
+github.com/gammazero/deque v0.1.0/go.mod h1:KQw7vFau1hHuM8xmI9RbgKFbAsQFWmBpqQ2KenFLk6M=
+github.com/gammazero/workerpool v1.1.2 h1:vuioDQbgrz4HoaCi2q1HLlOXdpbap5AET7xu5/qj87g=
+github.com/gammazero/workerpool v1.1.2/go.mod h1:UelbXcO0zCIGFcufcirHhq2/xtLXJdQ29qZNlXG9OjQ=
 github.com/panjf2000/ants/v2 v2.5.0 h1:1rWGWSnxCsQBga+nQbA4/iY6VMeNoOIAM0ZWh9u3q2Q=
 github.com/panjf2000/ants/v2 v2.5.0/go.mod h1:cU93usDlihJZ5CfRGNDYsiBYvoilLvBF5Qp/BT2GNRE=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/stretchr/testify v1.7.1 h1:5TQK59W5E3v0r2duFAb7P95B6hEeOyEnHRa8MjYSMTY=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v22aHH28wwpauUhK9Oo=