🚦 semaphore

Semaphore pattern implementation with timeout of lock/unlock operations.

💡 Idea

The semaphore provides API to control access to a shared resource by multiple goroutines or limit throughput.

releaser, err := semaphore.Acquire(breaker.BreakByTimeout(time.Second))
if err != nil {
	// timeout exceeded
}
defer releaser.Release()

Full description of the idea is available here.

🏆 Motivation

...

🤼‍♂️ How to

Quick start

limiter := semaphore.New(1000)

http.HandleFunc("/", func(rw http.ResponseWriter, req *http.Request) {
	if _, err := limiter.Acquire(
		breaker.BreakByContext(
			context.WithTimeout(req.Context(), time.Second),
		),
	); err != nil {
		http.Error(rw, http.StatusText(http.StatusTooManyRequests), http.StatusTooManyRequests)
		return
	}
	defer limiter.Release()

	// handle request
})

log.Fatal(http.ListenAndServe(":80", http.DefaultServeMux))

🧩 Integration

The library uses SemVer for versioning, and it is not BC-safe through major releases. You can use go modules or dep to manage its version.

The master is a feature frozen branch for versions 4.3.x and no longer maintained.

$ dep ensure -add github.com/kamilsk/semaphore@4.3.1

The v4 branch is a continuation of the master branch for versions v4.4.x to better integration with go modules.

$ go get -u github.com/kamilsk/semaphore/v4@v4.3.1

The v5 branch is an actual development branch.

$ go get -u github.com/kamilsk/semaphore    # inside GOPATH and for old Go versions

$ go get -u github.com/kamilsk/semaphore/v5 # inside Go module, works well since Go 1.11

$ dep ensure -add github.com/kamilsk/semaphore@v5.0.0-rc1

Version v5 focused on integration with the 🚧 breaker package.

🤲 Outcomes

Console tool for command execution in parallel

This example shows how to execute many console commands in parallel.

$ semaphore create 2
$ semaphore add -- docker build
$ semaphore add -- vagrant up
$ semaphore add -- ansible-playbook
$ semaphore wait --timeout=1m --notify

See more details here.

---

made with ❤️ for everyone