sema

README

Semaphore (for GoLang)

This package provides a fast implementation of a powerful computing technique called the semaphore. These allow you to control the quantity of computation, disk I/O, network I/O, etc related load on your application.

Installation

go get -u github.com/andreimerlescu/sema

Usage

Integrating sema into your project is easy.

package main

import (
	`fmt`
	`sync`
	`sync/atomic`
	`time`

	"github.com/andreimerlescu/sema"
)

func main() {
	workers := 10 // 10 workers
	mySemaphore := sema.New(workers)
	var wg sync.WaitGroup
	var delaySeconds atomic.Int32
	for i := 0; i < workers*2; i++ {
		wg.Add(1)
		mySemaphore.Acquire()
		go func(i int, wg *sync.WaitGroup) {
			defer wg.Done()
			defer mySemaphore.Release()
			delay := delaySeconds.Add(1)
			time.Sleep(time.Duration(delay)*time.Second)
			fmt.Printf("worker %d finished after %d seconds\n", i, delaySeconds.Load())
		}(i, &wg)
	}
	wg.Wait()
	fmt.Printf("wait group released with %d workers left in the semaphore\n", mySemaphore.Len())
}

This code has been included in the sema_test.go file and is part of the build verification of this package. A sync.WaitGroup is needed to ensure that the main process does not quit until all of the workers have completed their task. The sync.WaitGroup effectively demonstrates through the ; i < workers*2 ; middle segment from the for loop that only workers := 10 will be able to even start running their go routine.

License

This is open source under the Apache 2.0 license.

Documentation

Overview

Package sema provides a simple semaphore implementation to control concurrency in Go programs. A semaphore is a synchronization primitive that limits the number of goroutines that can run concurrently, ensuring that resources (e.g., CPU, memory, I/O) are not overwhelmed by too many simultaneous tasks. This package is useful for scenarios like parallel file processing, API rate limiting, or managing worker pools.

Index

• type Semaphore
  • func New(maxConcurrency int) Semaphore

Types

type Semaphore

type Semaphore interface {
	// Acquire takes a slot in the semaphore, blocking if no slots are available until one is freed.
	// This method should be called before starting a concurrent task.
	Acquire()

	// Release frees a slot in the semaphore, allowing another goroutine to acquire it.
	// This method should be called when a concurrent task is complete.
	Release()

	// Len returns the current number of occupied slots in the semaphore.
	// It indicates how many goroutines are currently active.
	Len() int

	// IsEmpty returns true if no slots are occupied (i.e., no goroutines are active).
	IsEmpty() bool
}

Semaphore defines the interface for a semaphore that controls concurrent access. It provides methods to acquire and release slots, check the current usage, and determine if the semaphore is empty.

func New

func New(maxConcurrency int) Semaphore

New creates a new Semaphore with the specified maximum concurrency. The maxConcurrency parameter determines how many goroutines can run concurrently before blocking. If maxConcurrency is invalid (e.g., -1 or 0), it is adjusted by the safe function.