Sharded Singleflight

https://pkg.go.dev/github.com/tarndt/shardedsingleflight
Admin
Sharded Singleflight is a sharded wrapper for Go's sync/singleflight designed for high concurrency...
Tokens:1,661
Snippets:21
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Implementing Thundering Herd Protection with singleflight

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Demonstrates wrapping a function with singleflight to de-duplicate concurrent operations. The first example is vulnerable to the thundering herd problem, while the second uses a Group to ensure only one execution occurs per key.

```go
//Not thundering herd safe!
func readFile(filepath string) (string, error) {
	data, err := os.ReadFile(filepath)
	return string(data), err
}

var g singeflight.Group //normally a field in a struct

//Safe from the herd!
func ReadFile(filepath string) (string, error) {
	result, err, _ := g.Do(filepath, func() (interface{}, error) {
		return readFile(filepath)
	})
	return result.(string), err
}
```

--------------------------------

### Benchmarking shardedsingleflight Performance

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Displays benchmark results comparing standard singleflight against various sharded implementations on a 24-core machine. Shows performance gains achieved by reducing mutex contention.

```bash
go test -test.bench=.*
goos: linux
goarch: amd64
pkg: github.com/tarndt/shardedsingleflight
cpu: AMD Ryzen 9 3900X 12-Core Processor
BenchmarkDo/noshard-24     		    	 2070744	       583.30 ns/op	      94 B/op	       0 allocs/op
BenchmarkDo/shard-hash-fnv64-24         	18465124	        65.65 ns/op	     119 B/op	       2 allocs/op
BenchmarkDo/shard-hash-fnv64a-24        	16838563	        69.95 ns/op	     119 B/op	       2 allocs/op
BenchmarkDo/shard-hash-crc-iso-24       	15008778	        77.21 ns/op	     127 B/op	       2 allocs/op
BenchmarkDo/shard-hash-crc-ecma-24      	14828358	        79.10 ns/op	     127 B/op	       2 allocs/op
BenchmarkDo/shard-hash-maphash-24       	 9129664	       133.1 ns/op	     272 B/op	       3 allocs/op
PASS
ok  	github.com/tarndt/shardedsingleflight	3.162s
```

--------------------------------

### NewShardedGroup Constructor

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Initializes a new ShardedGroup with optional configurations.

```go
func NewShardedGroup(opts ...GroupOptions) *ShardedGroup
```

--------------------------------

### WithHashFunc Option

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Option to override the default hash.Hash64 constructor.

```go
type WithHashFunc NewHash
```

--------------------------------

### Default Shard Count

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Heuristically determined default shard count based on the number of CPU cores.

```go
var DefShardCount = nextPrime(uint64(runtime.NumCPU() * 7))
```

--------------------------------

### ShardedGroup DoChan Method

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Executes a function for a given key and returns a channel for the result.

```go
func (sg *ShardedGroup) DoChan(key string, fn func() (interface{}, error)) <-chan singleflight.Result
```

--------------------------------

### Define Hash Function Variables

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Commonly used hash.Hash64 constructors available for configuring the sharded group.

```go
var (
	DefHashFunc = FNV64a
	FNV64a      = fnv.New64a
	FNV64       = fnv.New64
	CRCISO      = func() hash.Hash64 { return crc64.New(crc64.MakeTable(crc64.ISO)) }
	CRCECMA     = func() hash.Hash64 { return crc64.New(crc64.MakeTable(crc64.ECMA)) }
	MapHash     = func() hash.Hash64 { return new(maphash.Hash) }
)
```

--------------------------------

### ShardedGroup Do Method

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Executes a function for a given key within the appropriate shard.

```go
func (sg *ShardedGroup) Do(key string, fn func() (interface{}, error)) (v interface{}, err error, shared bool)
```

--------------------------------

### GroupOptions Interface

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Interface for options provided to the ShardedGroup constructor.

```go
type GroupOptions interface {
	// contains filtered or unexported methods
}
```

--------------------------------

### ShardedGroup.DoChan

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Executes a function for a given key asynchronously, returning a channel that receives the result.

```APIDOC
## func (sg *ShardedGroup) DoChan(key string, fn func() (interface{}, error)) <-chan singleflight.Result

### Description
Maps the key to a shard and initiates the function execution. Returns a channel that will receive the singleflight.Result once the operation completes.

### Parameters
- **key** (string) - Required - The unique identifier for the operation.
- **fn** (func() (interface{}, error)) - Required - The function to execute.
```

--------------------------------

### WithShardCount Option

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Option to override the default shard count with an explicit value.

```go
type WithShardCount uint64
```

--------------------------------

### NewShardedGroup

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Constructs a new sharded singleflight group. Accepts optional GroupOptions to configure the group.

```APIDOC
## func NewShardedGroup(opts ...GroupOptions) *ShardedGroup

### Description
Creates and returns a new instance of a ShardedGroup. Optional configuration parameters can be passed to customize the group behavior.

### Parameters
- **opts** (...GroupOptions) - Optional - A variadic list of configuration options (e.g., WithHashFunc, WithShardCount).
```

--------------------------------

### NewHash Type Definition

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Function type for constructors of hash.Hash64 instances.

```go
type NewHash func() hash.Hash64
```

--------------------------------

### ShardedGroup Forget Method

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Removes a key from the singleflight tracking for its assigned shard.

```go
func (sg *ShardedGroup) Forget(key string)
```

--------------------------------

### ShardedGroup Struct

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

The primary structure representing a sharded singleflight group.

```go
type ShardedGroup struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### ShardedGroup.Do

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Executes a function for a given key within the appropriate shard, suppressing duplicate concurrent calls.

```APIDOC
## func (sg *ShardedGroup) Do(key string, fn func() (interface{}, error)) (v interface{}, err error, shared bool)

### Description
Maps the provided key to a specific shard and executes the function fn. If multiple calls are made with the same key, only one execution occurs, and the result is shared among callers.

### Parameters
- **key** (string) - Required - The unique identifier for the operation.
- **fn** (func() (interface{}, error)) - Required - The function to execute if no other call is currently in progress for this key.
```

--------------------------------

### ShardedGroup.Forget

Source: https://pkg.go.dev/github.com/tarndt/shardedsingleflight

Removes the result associated with the given key from the shard.

```APIDOC
## func (sg *ShardedGroup) Forget(key string)

### Description
Maps the key to a shard and removes the entry for that key, ensuring subsequent calls will trigger a new execution.

### Parameters
- **key** (string) - Required - The key to remove from the shard.
```
Tokens:
Raw