ants

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 26, 2019 License: MIT Imports: 7 Imported by: 0

README

ants

A goroutine pool for Go

Build Status codecov goreportcard for panjf2000/ants godoc for panjf2000/ants MIT Licence

中文 | Project Blog

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:

  • Automatically managing and recycling a massive number of goroutines.
  • Periodically purging overdue goroutines.
  • Friendly interfaces: submitting tasks, getting the number of running goroutines, tuning capacity of pool dynamically, closing pool.
  • Handle panic gracefully to prevent programs from crash.
  • Efficient in memory usage and it even achieves higher performance than unlimited goroutines in golang.

Tested in the following Golang versions:

  • 1.8.x
  • 1.9.x
  • 1.10.x
  • 1.11.x
  • 1.12.x

How to install

go get -u github.com/panjf2000/ants

Or, using glide:

glide get github.com/panjf2000/ants

How to use

Just take a imagination that your program starts a massive number of goroutines, from which a vast amount of memory will be consumed. 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:

package main

import (
	"fmt"
	"sync"
	"sync/atomic"
	"time"

	"github.com/panjf2000/ants"
)

var sum int32

func myFunc(i interface{}) {
	n := i.(int32)
	atomic.AddInt32(&sum, n)
	fmt.Printf("run with %d\n", n)
}

func demoFunc() {
	time.Sleep(10 * time.Millisecond)
	fmt.Println("Hello World!")
}

func main() {
	defer ants.Release()

	runTimes := 1000

	// Use the common pool.
	var wg sync.WaitGroup
	syncCalculateSum := func() {
		demoFunc()
		wg.Done()
	}
	for i := 0; i < runTimes; i++ {
		wg.Add(1)
		ants.Submit(syncCalculateSum)
	}
	wg.Wait()
	fmt.Printf("running goroutines: %d\n", ants.Running())
	fmt.Printf("finish all tasks.\n")

	// Use the pool with a function,
	// set 10 to the capacity of goroutine pool and 1 second for expired duration.
	p, _ := ants.NewPoolWithFunc(10, func(i interface{}) {
		myFunc(i)
		wg.Done()
	})
	defer p.Release()
	// Submit tasks one by one.
	for i := 0; i < runTimes; i++ {
		wg.Add(1)
		p.Invoke(int32(i))
	}
	wg.Wait()
	fmt.Printf("running goroutines: %d\n", p.Running())
	fmt.Printf("finish all tasks, result is %d\n", sum)
}

Integrate with http server

package main

import (
	"io/ioutil"
	"net/http"

	"github.com/panjf2000/ants"
)

type Request struct {
	Param  []byte
	Result chan []byte
}

func main() {
	pool, _ := ants.NewPoolWithFunc(100, func(payload interface{}) {
		request, ok := payload.(*Request)
		if !ok {
			return
		}
		reverseParam := func(s []byte) []byte {
			for i, j := 0, len(s)-1; i < j; i, j = i+1, j-1 {
				s[i], s[j] = s[j], s[i]
			}
			return s
		}(request.Param)

		request.Result <- reverseParam
	})
	defer pool.Release()

	http.HandleFunc("/reverse", func(w http.ResponseWriter, r *http.Request) {
		param, err := ioutil.ReadAll(r.Body)
		if err != nil {
			http.Error(w, "request error", http.StatusInternalServerError)
		}
		defer r.Body.Close()

		request := &Request{Param: param, Result: make(chan []byte)}

		// Throttle the requests traffic with ants pool. This process is asynchronous and
		// you can receive a result from the channel defined outside.
		if err := pool.Invoke(request); err != nil {
			http.Error(w, "throttle limit error", http.StatusInternalServerError)
		}

		w.Write(<-request.Result)
	})

	http.ListenAndServe(":8080", nil)
}

Submit tasks

Tasks can be submitted by calling ants.Submit(func())

ants.Submit(func(){})

Customize limited pool

ants also supports customizing the capacity of pool. You can invoke the NewPool function to instantiate a pool with a given capacity, as following:

// Set 10000 the size of goroutine pool
p, _ := ants.NewPool(10000)
// Submit a task
p.Submit(func(){})

Tune pool capacity in runtime

You can tune the capacity of ants pool in runtime with Tune(int):

pool.Tune(1000) // Tune its capacity to 1000
pool.Tune(100000) // Tune its capacity to 100000

Don't worry about the synchronous problems in this case, the function here is thread-safe (or should be called goroutine-safe).

Release Pool

pool.Release()

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

OS: macOS High Sierra
Processor: 2.7 GHz Intel Core i5
Memory: 8 GB 1867 MHz DDR3

Go Version: 1.9
In that benchmark-picture, 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.
  • BenchmarkGoroutine-4 represents the benchmarks with unlimited goroutines in golang.

  • BenchmarkPoolGroutine-4 represents the benchmarks with a ants pool.

The test data above is a basic benchmark and more detailed benchmarks are about to be uploaded later.

Benchmarks with Pool

In above benchmark picture, 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.

As you can see, ants can up to 2x faster than goroutines without pool (10M tasks) and it only consumes half the memory comparing with goroutines without pool. (both 1M and 10M tasks)

Benchmarks with PoolWithFunc

Throughput (it is suitable for scenarios where asynchronous tasks are submitted despite of the final results)
100K tasks

1M tasks

10M tasks

Performance Summary

In conclusion, ants can up to 2x~6x faster than goroutines without a pool and the memory consumption is reduced by 10 to 20 times.

Documentation

Index

Constants

View Source
const (
	// DEFAULT_ANTS_POOL_SIZE is the default capacity for a default goroutine pool.
	DEFAULT_ANTS_POOL_SIZE = math.MaxInt32

	// DEFAULT_CLEAN_INTERVAL_TIME is the interval time to clean up goroutines.
	DEFAULT_CLEAN_INTERVAL_TIME = 1

	// CLOSED represents that the pool is closed.
	CLOSED = 1
)

Variables

View Source
var (

	// ErrInvalidPoolSize will be returned when setting a negative number as pool capacity.
	ErrInvalidPoolSize = errors.New("invalid size for pool")

	// ErrInvalidPoolExpiry will be returned when setting a negative number as the periodic duration to purge goroutines.
	ErrInvalidPoolExpiry = errors.New("invalid expiry for pool")

	// ErrPoolClosed will be returned when submitting task to a closed pool.
	ErrPoolClosed = errors.New("this pool has been closed")
)

Functions

func Cap

func Cap() int

Cap returns the capacity of this default pool.

func Free

func Free() int

Free returns the available goroutines to work.

func Release

func Release()

Release Closes the default pool.

func Running

func Running() int

Running returns the number of the currently running goroutines.

func Submit

func Submit(task func()) error

Submit submits a task to pool.

Types

type Pool

type Pool struct {

	// PanicHandler is used to handle panics from each worker goroutine.
	// if nil, panics will be thrown out again from worker goroutines.
	PanicHandler func(interface{})
	// contains filtered or unexported fields
}

Pool accept the tasks from client,it limits the total of goroutines to a given number by recycling goroutines.

func NewPool

func NewPool(size int) (*Pool, error)

NewPool generates an instance of ants pool.

func NewTimingPool

func NewTimingPool(size, expiry int) (*Pool, error)

NewTimingPool generates an instance of ants pool with a custom timed task.

func (*Pool) Cap

func (p *Pool) Cap() int

Cap returns the capacity of this pool.

func (*Pool) Free

func (p *Pool) Free() int

Free returns the available goroutines to work.

func (*Pool) Release

func (p *Pool) Release() error

Release Closes this pool.

func (*Pool) Running

func (p *Pool) Running() int

Running returns the number of the currently running goroutines.

func (*Pool) Submit

func (p *Pool) Submit(task func()) error

Submit submits a task to this pool.

func (*Pool) Tune

func (p *Pool) Tune(size int)

Tune changes the capacity of this pool.

type PoolWithFunc

type PoolWithFunc struct {

	// PanicHandler is used to handle panics from each worker goroutine.
	// if nil, panics will be thrown out again from worker goroutines.
	PanicHandler func(interface{})
	// contains filtered or unexported fields
}

PoolWithFunc accept the tasks from client,it limits the total of goroutines to a given number by recycling goroutines.

func NewPoolWithFunc

func NewPoolWithFunc(size int, pf func(interface{})) (*PoolWithFunc, error)

NewPoolWithFunc generates an instance of ants pool with a specific function.

func NewTimingPoolWithFunc

func NewTimingPoolWithFunc(size, expiry int, pf func(interface{})) (*PoolWithFunc, error)

NewTimingPoolWithFunc generates an instance of ants pool with a specific function and a custom timed task.

func (*PoolWithFunc) Cap

func (p *PoolWithFunc) Cap() int

Cap returns the capacity of this pool.

func (*PoolWithFunc) Free

func (p *PoolWithFunc) Free() int

Free returns a available goroutines to work.

func (*PoolWithFunc) Invoke

func (p *PoolWithFunc) Invoke(args interface{}) error

Invoke submits a task to pool.

func (*PoolWithFunc) Release

func (p *PoolWithFunc) Release() error

Release Closed this pool.

func (*PoolWithFunc) Running

func (p *PoolWithFunc) Running() int

Running returns the number of the currently running goroutines.

func (*PoolWithFunc) Tune

func (p *PoolWithFunc) Tune(size int)

Tune change the capacity of this pool.

type Worker

type Worker struct {
	// contains filtered or unexported fields
}

Worker is the actual executor who runs the tasks, it starts a goroutine that accepts tasks and performs function calls.

type WorkerWithFunc

type WorkerWithFunc struct {
	// contains filtered or unexported fields
}

WorkerWithFunc is the actual executor who runs the tasks, it starts a goroutine that accepts tasks and performs function calls.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL