semaphore

README

semaphore

Fast resizable golang semaphore based on CAS

• allows weighted acquire/release;
• supports cancellation via context;
• allows change semaphore limit after creation;
• faster than channel based semaphores.

Usage

Initiate

import "github.com/marusama/semaphore"
...
sem := semaphore.New(5) // new semaphore with limit = 5

Acquire

sem.Acquire(ctx, n)     // acquire n with context
sem.TryAcquire(n)       // try acquire n without blocking 
...
ctx := context.WithTimeout(context.Background(), time.Second)
sem.Acquire(ctx, n)     // acquire n with timeout

Release

sem.Release(n)          // release n

Change semaphore limit

sem.SetLimit(new_limit) // set new semaphore limit

Some benchmarks

Run on MacBook Pro (2017) with 3,1GHz Core i5 cpu and 8GB DDR3 ram, macOS High Sierra, go version go1.11.4 darwin/amd64:

// this semaphore:
BenchmarkSemaphore_Acquire_Release_under_limit_simple-4                   	20000000	        98.6 ns/op	      96 B/op	       1 allocs/op
BenchmarkSemaphore_Acquire_Release_under_limit-4                          	 1000000	      1593 ns/op	     960 B/op	      10 allocs/op
BenchmarkSemaphore_Acquire_Release_over_limit-4                           	  100000	     20760 ns/op	    9600 B/op	     100 allocs/op


// some other implementations:

// golang.org/x/sync/semaphore:
BenchmarkXSyncSemaphore_Acquire_Release_under_limit_simple-4              	50000000	        34.9 ns/op	       0 B/op	       0 allocs/op
BenchmarkXSyncSemaphore_Acquire_Release_under_limit-4                     	 1000000	      1103 ns/op	       0 B/op	       0 allocs/op
BenchmarkXSyncSemaphore_Acquire_Release_over_limit-4                      	   30000	     65927 ns/op	   15985 B/op	     299 allocs/op

// github.com/abiosoft/semaphore:
BenchmarkAbiosoftSemaphore_Acquire_Release_under_limit_simple-4           	10000000	       208 ns/op	       0 B/op	       0 allocs/op
BenchmarkAbiosoftSemaphore_Acquire_Release_under_limit-4                  	  500000	      3147 ns/op	       0 B/op	       0 allocs/op
BenchmarkAbiosoftSemaphore_Acquire_Release_over_limit-4                   	   50000	     37148 ns/op	       0 B/op	       0 allocs/op

// github.com/dropbox/godropbox
BenchmarkDropboxBoundedSemaphore_Acquire_Release_under_limit_simple-4     	20000000	        75.9 ns/op	       0 B/op	       0 allocs/op
BenchmarkDropboxBoundedSemaphore_Acquire_Release_under_limit-4            	 2000000	       629 ns/op	       0 B/op	       0 allocs/op
BenchmarkDropboxBoundedSemaphore_Acquire_Release_over_limit-4             	  200000	     27308 ns/op	       0 B/op	       0 allocs/op
BenchmarkDropboxUnboundedSemaphore_Acquire_Release_under_limit_simple-4   	50000000	        39.7 ns/op	       0 B/op	       0 allocs/op
BenchmarkDropboxUnboundedSemaphore_Acquire_Release_under_limit-4          	 1000000	      1170 ns/op	       0 B/op	       0 allocs/op
BenchmarkDropboxUnboundedSemaphore_Acquire_Release_over_limit-4           	  100000	     21013 ns/op	       0 B/op	       0 allocs/op

// github.com/kamilsk/semaphore
BenchmarkKamilskSemaphore_Acquire_Release_under_limit_simple-4            	20000000	       110 ns/op	      16 B/op	       1 allocs/op
BenchmarkKamilskSemaphore_Acquire_Release_under_limit-4                   	 1000000	      1520 ns/op	     160 B/op	      10 allocs/op
BenchmarkKamilskSemaphore_Acquire_Release_over_limit-4                    	   50000	     42693 ns/op	    1600 B/op	     100 allocs/op

// github.com/pivotal-golang/semaphore
BenchmarkPivotalGolangSemaphore_Acquire_Release_under_limit_simple-4      	 3000000	       558 ns/op	     136 B/op	       2 allocs/op
BenchmarkPivotalGolangSemaphore_Acquire_Release_under_limit-4             	  200000	      9530 ns/op	    1280 B/op	      20 allocs/op
BenchmarkPivotalGolangSemaphore_Acquire_Release_over_limit-4              	   10000	    111264 ns/op	   12801 B/op	     200 allocs/op

You can rerun these benchmarks, just checkout benchmarks branch and run go test -bench=. -benchmem ./bench/...

Documentation

Overview

Package semaphore provides an implementation of counting semaphore primitive with possibility to change limit after creation. This implementation is based on Compare-and-Swap primitive that in general case works faster than other golang channel-based semaphore implementations.

Index

• type Semaphore
  • func New(limit int) Semaphore

Types

type Semaphore

type Semaphore interface {
	// Acquire enters the semaphore a specified number of times, blocking only until ctx is done.
	// This operation can be cancelled via passed context (but it's allowed to pass ctx='nil').
	// Method returns context error (ctx.Err()) if the passed context is cancelled,
	// but this behavior is not guaranteed and sometimes semaphore will still be acquired.
	Acquire(ctx context.Context, n int) error

	// TryAcquire acquires the semaphore without blocking.
	// On success, returns true. On failure, returns false and leaves the semaphore unchanged.
	TryAcquire(n int) bool

	// Release exits the semaphore a specified number of times and returns the previous count.
	Release(n int) int

	// SetLimit changes current semaphore limit in concurrent way.
	// It is allowed to change limit many times and it's safe to set limit higher or lower.
	SetLimit(limit int)

	// GetLimit returns current semaphore limit.
	GetLimit() int

	// GetCount returns current number of occupied entries in semaphore.
	GetCount() int
}

Semaphore counting resizable semaphore synchronization primitive. Use the Semaphore to control access to a pool of resources. There is no guaranteed order, such as FIFO or LIFO, in which blocked goroutines enter the semaphore. A goroutine can enter the semaphore multiple times, by calling the Acquire or TryAcquire methods repeatedly. To release some or all of these entries, the goroutine can call the Release method that specifies the number of entries to be released. Change Semaphore capacity to lower or higher by SetLimit.

func New

func New(limit int) Semaphore

New initializes a new instance of the Semaphore, specifying the maximum number of concurrent entries.