sync

README

x-sync - experimental x-sync utilities

x-sync is likely not what you're looking for. This project exists to mainly have a reference for things one may think are great optimizations of standard go things but did not turn out to be the case.

General Notes

1. the built-in append function is really fast as it is but if there's a need for controlling the slice scaling process, this package has an AppendScale function which may be useful
2. working with sync.Pool is a very specific task, usually unique to each project's needs, however if there's a need for a generic and convenient sync.Pool that doesn't need boilerplate, take at look at this package's Pool type and the NewStringBuilderPool convenience function
3. some benchmarks have been added and they basically demonstrate that the standard Go append function is really tough to beat, though admittedly the case scenario being benchmarked may not be the best implementation for comparative benchmarking purposes
4. don't optimize too early in the development cycle, just get things done until it's obviously working and then consider this package for testing really simply optimizations before delving into the more appropriate project-specific minimum viable product performance tuning

Installation

> go get github.com/go-corelibs/x-sync@latest

Go-CoreLibs

Go-CoreLibs is a repository of shared code between the Go-Curses and Go-Enjin projects.

License

Copyright 2024 The Go-CoreLibs Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use file except in compliance with the License.
You may obtain a copy of the license at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Overview

Package sync provides experimental sync-related utilities

Index

• func Append[V interface{}](slice []V, data ...V) []V
• func AppendScaled[V interface{}](scale float64, slice []V, data ...V) []V
• type Pool
  • func NewPool[V interface{}](scale int, maker func() V, hooks ...PoolHookFn[V]) Pool[V]
  • func NewStringBuilderPool(scale int) (pool Pool[*strings.Builder])
• type PoolHookFn

Functions

func Append

func Append[V interface{}](slice []V, data ...V) []V

Append is an experiment in appending to slices without using the standard Go append function

func AppendScaled

func AppendScaled[V interface{}](scale float64, slice []V, data ...V) []V

AppendScaled is like Append but includes the scale argument for specifying the cap growth multiplier. The scale value is capped at a minimum of 1.5 and for reference, the Append function uses a hard-coded scale of 2

Types

type Pool

type Pool[V interface{}] interface {
	// Scale returns the amount of instances to Seed this sync.Pool when drained
	Scale() int
	// Ready returns the best-guess number of instances still in the sync.Pool
	Ready() int
	// Seed adds a count of new instances to this sync.Pool
	Seed(count int)
	// Get retrieves a typed instance from this sync.Pool, and if the pool is
	// drained, uses Seed with Scale to expand this sync.Pool
	Get() V
	// Put recycles an existing instance, ignores nil instances
	Put(v V)
}

Pool is a convenience interface for working with the standard sync.Pool.

Pool instances can have up to two hooks provided, the first is always the "getter" PoolHookFn and the second is always the "setter" PoolHookFn.

The "getter" function is used to modify the instance before returning it during Get calls

The "setter" function is used to modify the instance before putting it into the sync.Pool

func NewPool

func NewPool[V interface{}](scale int, maker func() V, hooks ...PoolHookFn[V]) Pool[V]

NewPool constructs a new Pool instance with the given scale, maker function and the two optional PoolHookFn functions

Passing nil for the hooks is valid, for example to create a Pool without a getter hook but with a setter, pass a nil for the first hooks argument

Scale values less than or equal to zero are clamped to a minimum scale of 1

func NewStringBuilderPool

func NewStringBuilderPool(scale int) (pool Pool[*strings.Builder])

NewStringBuilderPool is a convenience wrapper around NewPool, configured for the *strings.Builder type (all Pool values must be pointers), and includes both getter and setter PoolHookFn implementations. The getter function resets the buffer before returning it and the setter function won't allow recycling buffers that are larger than 65k

type PoolHookFn

type PoolHookFn[V interface{}] func(v V) V

PoolHookFn is the function signature used with NewPool