README
¶
simultaneous - limit the number of concurrent operations, Go
Install:
go get github.com/singlestore-labs/simultaneous
Simultaneous limits the number of concurrent operations. It supports passing proof of obtaining a limit.
Simple usage
var limit = simultaneous.New[any](10)
func unlimitedWait() {
defer limit.Forever()()
// do stuff
}
func limitedWait() error {
done, err := limit.Timeout(time.Minute)
if err != nil {
return fmt.Errorf("timeout: %w", err)
}
defer done()
// do stuff
}
Proving that operating within a limit
You can prove that you've got permission
type myLimitType struct{}
var limit = simultaneous.New[myLimitType](10)
func wantsProof(_ Enforced[myLimitType]) {
// do something
}
func providesProof() {
done := limit.Forever()
defer done()
wantsProof(done)
}
Documentation
¶
Overview ¶
Package simultaneous exists to place a limit on simultaneous actions that need a limit.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrTimeout errors.String = "could not get permission to run before timeout"
Functions ¶
This section is empty.
Types ¶
type Enforced ¶
type Enforced[T any] interface { // contains filtered or unexported methods }
Enforced is a type that exists just to signal that a simultaneous limit is being enforced. When passing a Limited as a argument, have the receiver take an Enforced instead.
type Limit ¶
type Limit[T any] struct { // contains filtered or unexported fields }
Limit implements Enforced so it can be used to fulfill the Enforced contract.
func New ¶
New takes both a type and a count. The type is so that if the limit is passed around it can be done so with type safety so that a limit of one kind of thing cannot be used as limit of another kind of thing. If you're not passing the resulting limit around, then the type argument can be anything. Like "string".
func (*Limit[T]) Forever ¶
Forever waits until there is space in the Limit for another simultaneous runner. It will wait for space in the limit, or until the context is cancelled. The Done() method must be called to release the space.
defer limit.Forever().Done()
If the context is cancelled, Forever returns regardless of space in the Limit.
func (Limit[T]) SetForeverMessaging ¶
func (l Limit[T]) SetForeverMessaging(stuckTimeout time.Duration, stuckCallback func(context.Context), unstuckCallback func(context.Context)) *Limit[T]
SetForeverMessaging returns a modified Limit that changes the behavior of Forever() so that it will call stuckCallback() (if set) after waiting for stuckTimeout duration. If past that duration, and it will call unstuckCallback() (if set) when it finally gets a limit or if the context is cancelled.
The anticipated use of the callbacks is logging. They don't return error and if they panic, it won't be caught by the simultaneous package.
func (*Limit[T]) Timeout ¶
Timeout waits for a limited time for there to be space for another simultaneous runner. In the case of a timeout, ErrTimeout is returned and the Done method is a no-op. If there is room, the Done method must be invoked to make room for another runner. If the provided context is cancelled before space becomes available or the timeout elapses, Timeout will return early with an error wrapping ctx.Err(), and the returned Limited's Done method will also be a no-op.
Source Files