From 69a6d6efaed17e20b22dd3e165fab6234a5a8f26 Mon Sep 17 00:00:00 2001
From: alitto <alitto@gmail.com>
Date: Sun, 29 Mar 2020 12:34:45 -0300
Subject: [PATCH] Add more examples

---
 README.md                              | 85 ++++++++++++++++++++++++--
 examples/{basic.go => dynamic_size.go} |  3 +-
 examples/fixed_size.go                 | 25 ++++++++
 examples/task_group.go                 | 28 +++++++++
 4 files changed, 134 insertions(+), 7 deletions(-)
 rename examples/{basic.go => dynamic_size.go} (72%)
 create mode 100644 examples/fixed_size.go
 create mode 100644 examples/task_group.go

diff --git a/README.md b/README.md
index 39d651d..bd7dd86 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,20 @@ pond: Minimalistic and High-performance goroutine worker pool written in Go
 
 ## Features:
 
-- Managing and recycling a massive number of goroutines automatically
-- Purging overdue goroutines periodically
-- Minimalistic API for submitting tasks, getting the number of running goroutines, stopping the pool and more.
 - Zero dependencies
-- Handle task panics gracefully
+- Creating goroutine pools with fixed or dynamic size
+- Worker goroutines are only created when needed (backpressure detection) and automatically purged after being idle for some time (configurable)
+- Minimalistic APIs for:
+  - Creating a worker pool
+  - Submitting tasks to a pool in a fire-and-forget fashion
+  - Submitting tasks to a pool and waiting for them to complete
+  - Submitting tasks to a pool with a deadline
+  - Submitting a group of related tasks and waiting for them to complete
+  - Getting the number of running workers (goroutines)
+  - Stopping a worker pool
+- Task panics are handled gracefully (configurable panic handler)
+- Supports Blocking and Non-blocking task submission modes
 - Efficient memory usage
-- Blocking and Nonblocking modes supported
 
 ## How to install
 
@@ -24,6 +31,8 @@ go get -u github.com/alitto/pond
 
 ## How to use
 
+### Worker pool with dynamic size
+
 ``` go
 package main
 
@@ -35,7 +44,8 @@ import (
 
 func main() {
 
-	// Create a pool with 100 workers
+	// Create a buffered (non-blocking) pool that can scale up to 100 workers
+	// and has a buffer capacity of 1000 tasks
 	pool := pond.New(100, 1000)
 
 	// Submit 1000 tasks
@@ -49,4 +59,67 @@ func main() {
 	// Stop the pool and wait for all submitted tasks to complete
 	pool.StopAndWait()
 }
+```
+
+### Worker pool with fixed size
+
+``` go
+package main
+
+import (
+	"fmt"
+
+	"github.com/alitto/pond"
+)
+
+func main() {
+
+	// Create an unbuffered (blocking) pool with a fixed 
+	// number of workers
+	pool := pond.New(10, 0, pond.MinWorkers(10))
+
+	// Submit 1000 tasks
+	for i := 0; i < 1000; i++ {
+		n := i
+		pool.Submit(func() {
+			fmt.Printf("Running task #%d\n", n)
+		})
+	}
+
+	// Stop the pool and wait for all submitted tasks to complete
+	pool.StopAndWait()
+}
+```
+
+### Submitting groups of related tasks
+
+``` go
+package main
+
+import (
+	"fmt"
+
+	"github.com/alitto/pond"
+)
+
+func main() {
+
+	// Create a pool
+	pool := pond.New(10, 1000)
+	defer pool.StopAndWait()
+
+	// Create a task group
+	group := pool.Group()
+
+	// Submit a group of related tasks
+	for i := 0; i < 20; i++ {
+		n := i
+		group.Submit(func() {
+			fmt.Printf("Running group task #%d\n", n)
+		})
+	}
+
+	// Wait for all tasks in the group to complete
+	group.Wait()
+}
 ```
\ No newline at end of file
diff --git a/examples/basic.go b/examples/dynamic_size.go
similarity index 72%
rename from examples/basic.go
rename to examples/dynamic_size.go
index 17efba2..041565b 100644
--- a/examples/basic.go
+++ b/examples/dynamic_size.go
@@ -8,7 +8,8 @@ import (
 
 func main() {
 
-	// Create a pool with 100 workers
+	// Create a buffered (non-blocking) pool that can scale up to 100 workers
+	// and has a buffer capacity of 1000 tasks
 	pool := pond.New(100, 1000)
 
 	// Submit 1000 tasks
diff --git a/examples/fixed_size.go b/examples/fixed_size.go
new file mode 100644
index 0000000..ffe1263
--- /dev/null
+++ b/examples/fixed_size.go
@@ -0,0 +1,25 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/alitto/pond"
+)
+
+func main() {
+
+	// Create an unbuffered (blocking) pool with a fixed
+	// number of workers
+	pool := pond.New(10, 0, pond.MinWorkers(10))
+
+	// Submit 1000 tasks
+	for i := 0; i < 1000; i++ {
+		n := i
+		pool.Submit(func() {
+			fmt.Printf("Running task #%d\n", n)
+		})
+	}
+
+	// Stop the pool and wait for all submitted tasks to complete
+	pool.StopAndWait()
+}
diff --git a/examples/task_group.go b/examples/task_group.go
new file mode 100644
index 0000000..7193a5f
--- /dev/null
+++ b/examples/task_group.go
@@ -0,0 +1,28 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/alitto/pond"
+)
+
+func main() {
+
+	// Create a pool
+	pool := pond.New(10, 1000)
+	defer pool.StopAndWait()
+
+	// Create a task group
+	group := pool.Group()
+
+	// Submit a group of related tasks
+	for i := 0; i < 20; i++ {
+		n := i
+		group.Submit(func() {
+			fmt.Printf("Running group task #%d\n", n)
+		})
+	}
+
+	// Wait for all tasks in the group to complete
+	group.Wait()
+}