semaphore

README

semaphore

Package semaphore is a Go library that implements a semaphore for controlling the concurrency of workloads. Using a buffered channel, this package provides a safe way for multiple goroutines to request and return semaphore permits.

For those not familiar with the concept of a semaphore, it allows you to control the access to a particular resource (or particular number of resources). A common use case is to limit the number of concurrent threads permitted to process work, to avoid overcomitting the resources of a system. More details (historical and applied) about semaphores can be found here.

License

This package is licensed under the permissive MIT License.

Contributions

Contributions back to this project are more than welcomed. To request a change please issue a pull request from a fork of this repo, and be sure to include details about the change in your commit message.

Installation

Until go dep is in wider utilization:

go get -u github.com/theckman/semaphore

Usage

The package uses three method for working with semaphores: Acquire(), Release(), and Close(). Detailed usage information can be discovered via GoDoc.

Here is a quick overview of using this package:

import "github.com/theckman/semaphore"

/* ... */

sema, err := semaphore.New(2)
if err != nil {
	// handle error  
}

for i := 0; i < 10; i++ {
	// blocks until semaphore permit is given
	// or until semaphore has Close() called
	err := sema.Acquire()
	if err != nil {
		// lock acquistion failed (i.e., semaphore is no longer usable)
		panic("semaphore in unexpected state")
	}
    
	// lock acquired, spin-off work
	go func() {
		time.Sleep(time.Second * 3)
		sema.Release()
	}()
}

/* wait for work to finish... */

sema.Close()

Documentation

Overview

Package semaphore is a Go library that implements a semaphore for controlling the concurrency of workloads. Using a buffered channel, this package provides a safe way for multiple goroutines to request and return semaphore permits.

For those not familiar with the concept of a semaphore, it allows you to control the access to a particular resource (or particular number of resources). A common use case is to limit the number of concurrent threads permitted to process work, to avoid overcomitting the resources of a system. More details (historical and applied) about semaphores can be found here: https://en.wikipedia.org/wiki/Semaphore_(programming).

The package uses three method for working with semaphores: Acquire(), Release(), and Close(). Here is a quick overview of using this package:

import "github.com/theckman/semaphore"

/* ... */

sema, err := semaphore.New(2)
if err != nil {
	// handle error
}

for i := 0; i < 10; i++ {
	// blocks until semaphore permit is given
	// or until semaphore has Close() called
	err := sema.Acquire()
	if err != nil {
		// lock acquistion failed (i.e., semaphore is no longer usable)
		panic("semaphore in unexpected state")
	}

	// lock acquired, spin-off work
	go func() {
		time.Sleep(time.Second * 3)
		sema.Release()
	}()
}

/* wait for work to finish... */

sema.Close()

Index

• Variables
• type Acquirer
• type Closer
• type Releaser
• type Semaphore
  • func New(size int) (Semaphore, error)

Variables

var ErrAlreadyClosed = errors.New("the semaphore has already had the Close() method called")

ErrAlreadyClosed is the error returned from the Close() function if the semaphore has already been shut down. This error should be treated as an advisory and NOT a failure.

var ErrUnusable = errors.New("semaphore not suitable for use, please create one with New()")

ErrUnusable is the error returned if the semaphore isn't suitable for use, meaning something called the Close() method. If this error is returned, the semaphore can no longer issue permits and the New() function must be used to allocate a new one.

Types

type Acquirer

type Acquirer interface {
	// Acquire is a blocking function to take a permit from the semaphore. If the
	// error returned is nil, the semaphore permit has been acquired and the work
	// can start.
	//
	// If an error is returned, the permit was not given and the work MUST NOT
	// start. This returns ErrUnusable if Close() has been called on the semaphore.
	// In this case you'd need to use New() to obtain a new usable semaphore.
	Acquire() error
}

Acquirer is the interface for taking permits from a semaphore.

type Closer

type Closer interface {
	// Close is a non-blocking function that shuts the semaphore down and
	// prevents it from issuing further permits. Consumers would need to create
	// a completely new semaphore, using New(), after calling Close() if they
	// wanted to request another permit.
	//
	// Close terminates the semaphore in a way that ensures any consumer with a
	// permit is able to release that permit without fatal error or deadlock.
	//
	// This function should return an ErrAlreadyClosed error if the semaphore
	// has already been closed, but consumers should treat that as an advisory
	// and not a fatal error.
	io.Closer
}

Closer is the interface for closing an interface to mark it as no longer in use.

type Releaser

type Releaser interface {
	// Release is a non-blocking function to release the semaphore. If an error is returned
	// from this function, the release was successful but the semaphore cannot be
	// used to acquire another permit.
	//
	// In other words, if this returns an error it should not be treated as a
	// failure. For example, if Close() is called, followed by Release(), this
	// function would return an ErrUnusable error. In this case you'd need to
	// use New() to obtain a new usable semaphore.
	Release() error
}

Releaser is the interface for releasing permits back to a semaphore.

type Semaphore

type Semaphore interface {
	// Acquirer is for taking a semaphore permit. See its comments for more
	// details.
	Acquirer

	// Releaser is for releasing a semaphore permit. See its comments for more
	// details.
	Releaser

	// Closer is for closing the semaphore. See its comments for more details.
	Closer
}

Semaphore is the interface needed to implement a functioning semaphore. One function to take permit, one to give back a permit, and a final function to tell the semaphore to stop issuing permits.

func New

func New(size int) (Semaphore, error)

New returns a new Semaphore and it takes a size argument to define how many concurrent permits the semaphore will issue. The size argument must be greater than 0 or an error will be returned.