singleflight

Documentation

Overview

Package singleflight provides a duplicate function call suppression mechanism.

This is a Tailscale fork of Go's singleflight package which has had several homes in the past:

• https://github.com/golang/go/commit/61d3b2db6292581fc07a3767ec23ec94ad6100d1
• https://github.com/golang/groupcache/tree/master/singleflight
• https://pkg.go.dev/golang.org/x/sync/singleflight

This fork adds generics.

Index

• type Group
  • func (g *Group[K, V]) Do(key K, fn func() (V, error)) (v V, err error, shared bool)
  • func (g *Group[K, V]) DoChan(key K, fn func() (V, error)) <-chan Result[V]
  • func (g *Group[K, V]) DoChanContext(ctx context.Context, key K, fn func(context.Context) (V, error)) <-chan Result[V]
  • func (g *Group[K, V]) Forget(key K)
• type Result

Types

type Group

type Group[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Group represents a class of work and forms a namespace in which units of work can be executed with duplicate suppression.

func (*Group[K, V]) Do

func (g *Group[K, V]) Do(key K, fn func() (V, error)) (v V, err error, shared bool)

Do executes and returns the results of the given function, making sure that only one execution is in-flight for a given key at a time. If a duplicate comes in, the duplicate caller waits for the original to complete and receives the same results. The return value shared indicates whether v was given to multiple callers.

func (*Group[K, V]) DoChan

func (g *Group[K, V]) DoChan(key K, fn func() (V, error)) <-chan Result[V]

DoChan is like Do but returns a channel that will receive the results when they are ready.

The returned channel will not be closed.

func (*Group[K, V]) DoChanContext

func (g *Group[K, V]) DoChanContext(ctx context.Context, key K, fn func(context.Context) (V, error)) <-chan Result[V]

DoChanContext is like Group.DoChan, but supports context cancelation. The context passed to the fn function is a context that is canceled only when there are no callers waiting on a result (i.e. all callers have canceled their contexts).

The context that is passed to the fn function is not derived from any of the input contexts, so context values will not be propagated. If context values are needed, they must be propagated explicitly.

The returned channel will not be closed. The Result.Err field is set to the context error if the context is canceled.

func (*Group[K, V]) Forget

func (g *Group[K, V]) Forget(key K)

Forget tells the singleflight to forget about a key. Future calls to Do for this key will call the function rather than waiting for an earlier call to complete.

type Result

type Result[V any] struct {
	Val    V
	Err    error
	Shared bool
}

Result holds the results of Do, so they can be passed on a channel.