semaphore

README

semaphore

The semaphore resiliency pattern for golang.

Creating a semaphore takes two parameters:

• ticket count (how many tickets to give out at once)
• timeout (how long to wait for a ticket if none are currently available)

sem := semaphore.New(3, 1*time.Second)

if err := sem.Acquire(); err != nil {
	// could not acquire semaphore
	return err
}
defer sem.Release()

Documentation

Overview

Package semaphore implements the semaphore resiliency pattern for Go.

Index

• Variables
• type Semaphore
  • func New(tickets int, timeout time.Duration) *Semaphore
  • func (s *Semaphore) Acquire() error
  • func (s *Semaphore) IsEmpty() bool
  • func (s *Semaphore) Release()

Examples

• Semaphore

Variables

var ErrNoTickets = errors.New("could not acquire semaphore ticket")

ErrNoTickets is the error returned by Acquire when it could not acquire a ticket from the semaphore within the configured timeout.

Types

type Semaphore

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

Semaphore implements the semaphore resiliency pattern

Example

sem := New(3, 1*time.Second)

for i := 0; i < 10; i++ {
	go func() {
		if err := sem.Acquire(); err != nil {
			return //could not acquire semaphore
		}
		defer sem.Release()

		// do something semaphore-guarded
	}()
}

func New

func New(tickets int, timeout time.Duration) *Semaphore

New constructs a new Semaphore with the given ticket-count and timeout.

func (*Semaphore) Acquire

func (s *Semaphore) Acquire() error

Acquire tries to acquire a ticket from the semaphore. If it can, it returns nil. If it cannot after "timeout" amount of time, it returns ErrNoTickets. It is safe to call Acquire concurrently on a single Semaphore.

func (*Semaphore) IsEmpty

func (s *Semaphore) IsEmpty() bool

IsEmpty will return true if no tickets are being held at that instant. It is safe to call concurrently with Acquire and Release, though do note that the result may then be unpredictable.

func (*Semaphore) Release

func (s *Semaphore) Release()

Release releases an acquired ticket back to the semaphore. It is safe to call Release concurrently on a single Semaphore. It is an error to call Release on a Semaphore from which you have not first acquired a ticket.