coma

README

coma

a tiny concurrency manager for go

coma makes sure your program doesn't get overwhelmed with goroutines and fall into a coma.

1. limits how many goroutines run at once
2. waits until all of them are done
3. is simple
4. works

install

go get github.com/zlatej/coma

usage

cm := coma.New(5) // at most 5 goroutines at a time

for _, task := range tasks {
    // blocks until a slot is free and acquires it
    if err := cm.AcquireContext(ctx); err != nil {
        // error means either the context is done or Wait has been called
        return
    } 
    go func(t Task) {
        defer cm.Release() // releases slot
        process(t)
    }(task)
}

fmt.Printf("currently running %d goroutines\n", cm.RunningCount())

cm.Wait() // blocks until all slots are released

no context? use cm.Acquire() instead

notes

• New treats a max of less than 1 as 1.
• Wait is terminal: once called, the manager cannot be reused, Acquire/AcquireContext will return ErrClosed.
• Wait can safely be called any number of times, including concurrently from multiple goroutines.
• every successful Acquire/AcquireContext must be matched by exactly one Release.

license

MIT

Documentation

Overview

Package coma limits how many goroutines run concurrently and waits for all of them to finish.

Index

• Variables
• type ConcurrencyManager
  • func New(max int) *ConcurrencyManager
  • func (c *ConcurrencyManager) Acquire() error
  • func (c *ConcurrencyManager) AcquireContext(ctx context.Context) error
  • func (c *ConcurrencyManager) Release()
  • func (c *ConcurrencyManager) RunningCount() int
  • func (c *ConcurrencyManager) Wait()

Variables

var ErrClosed = errors.New("coma: manager is shut down")

ErrClosed is returned by ConcurrencyManager.Acquire and ConcurrencyManager.AcquireContext when ConcurrencyManager.Wait has been called.

Types

type ConcurrencyManager

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

ConcurrencyManager limits how many goroutines can run concurrently.

func New

func New(max int) *ConcurrencyManager

New creates a ConcurrencyManager that allows at most max concurrently running goroutines. A max < 1 is treated as 1.

func (*ConcurrencyManager) Acquire

func (c *ConcurrencyManager) Acquire() error

Acquire blocks until a slot is available and claims it for a new goroutine. If ConcurrencyManager.Wait has been called, Acquire returns ErrClosed.

func (*ConcurrencyManager) AcquireContext

func (c *ConcurrencyManager) AcquireContext(ctx context.Context) error

AcquireContext blocks until a slot is available and claims it for a new goroutine, or returns ctx.Err() if the context is done first. If ConcurrencyManager.Wait has been called, AcquireContext returns ErrClosed.

func (*ConcurrencyManager) Release

func (c *ConcurrencyManager) Release()

Release marks a goroutine as finished and releases one slot. Every successful ConcurrencyManager.Acquire or ConcurrencyManager.AcquireContext must be matched by exactly one Release.

Release blocks only while no slot is held at all. An unmatched Release made while other goroutines hold slots takes one of theirs instead of blocking, which lets the limit be exceeded and can make ConcurrencyManager.Wait return before those goroutines finish. The Release whose slot has been taken then blocks in its place.

func (*ConcurrencyManager) RunningCount

func (c *ConcurrencyManager) RunningCount() int

RunningCount returns the number of currently held slots: those for which ConcurrencyManager.Acquire or ConcurrencyManager.AcquireContext returned nil and ConcurrencyManager.Release has not yet been called. Goroutines blocked in Acquire are not counted, so this is not necessarily the number of goroutines running.

func (*ConcurrencyManager) Wait

func (c *ConcurrencyManager) Wait()

Wait waits until all goroutines are done. Wait is terminal, meaning ConcurrencyManager cannot be reused. Wait is safe for concurrent use. A repeated call is a safe no-op.