limitx

package
v0.41.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package limitx bounds concurrency. Its one type, Keyed, caps how much work runs at once per key rather than in total, which is what keeps one slow tenant, customer or partner from consuming a shared worker pool.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Keyed

type Keyed[K comparable] struct {
	// contains filtered or unexported fields
}

Keyed caps concurrent operations per key.

A global worker pool is fair only while every unit of work costs about the same. Once the work talks to something the key controls — a customer's SMTP server, a partner's API, a tenant's database — one slow endpoint holds every worker it is given, and a pool of N is starved by a single key. Capping per key converts that outage into a queue for the key at fault.

limiter := limitx.NewKeyed[uuid.UUID](2)

release, err := limiter.Acquire(ctx, tenantID)
if err != nil {
    return err // the caller's context ended while queueing
}
defer release()

Keyed holds no state for an idle key, so the number of distinct keys it has seen does not accumulate: entries appear on first use and are dropped when the last holder releases. The zero value is not usable; call NewKeyed. It is safe for concurrent use.

func NewKeyed

func NewKeyed[K comparable](perKey int) *Keyed[K]

NewKeyed returns a limiter allowing perKey concurrent operations per key. A perKey below 1 is raised to 1, since a limiter that admits nothing would deadlock every caller rather than report a misconfiguration.

func (*Keyed[K]) Acquire

func (l *Keyed[K]) Acquire(ctx context.Context, key K) (func(), error)

Acquire blocks until the key has a free slot or ctx ends, and returns the function that gives the slot back.

The returned release is safe to call more than once and must be called exactly once on the success path — defer it. On error it is nil and nothing was acquired.

Waiting is not ordered: a caller can be overtaken. Where a slow key must not make callers wait at all, give ctx a deadline and treat the error as a signal to shed the work rather than queue for it.

func (*Keyed[K]) Keys

func (l *Keyed[K]) Keys() int

Keys reports how many keys currently hold or await a slot. It is meant for tests and metrics; a caller cannot act on it without racing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL