diff --git a/README.md b/README.md index a9b375b..25c66d3 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # common [![GoDoc](https://godoc.org/git.tcp.direct/kayos/common?status.svg)](https://pkg.go.dev/git.tcp.direct/kayos/common) [![codecov](https://codecov.io/gh/yunginnanet/common/branch/master/graph/badge.svg?token=vk5frSGqhq)](https://codecov.io/gh/yunginnanet/common) - Welcome to things. Here are some of the aforementioned: +* [common](https://pkg.go.dev/git.tcp.direct/kayos/common) + * [hash](https://pkg.go.dev/git.tcp.direct/kayos/common/hash) * [linux](https://pkg.go.dev/git.tcp.direct/kayos/common/linux) @@ -12,36 +13,10 @@ Welcome to things. Here are some of the aforementioned: * [entropy](https://pkg.go.dev/git.tcp.direct/kayos/common/entropy) -## base - -`import "git.tcp.direct/kayos/common"` - -## Base Module - -#### func Abs - -```go -func Abs(n int) int -``` -Abs will give you the positive version of a negative integer, quickly. - -#### func BytesToFloat64 - -```go -func BytesToFloat64(bytes []byte) float64 -``` -BytesToFloat64 will take a slice of bytes and convert it to a float64 type. - -#### func Float64ToBytes +* [pool](https://pkg.go.dev/git.tcp.direct/kayos/common/pool) -```go -func Float64ToBytes(f float64) []byte -``` -Float64ToBytes will take a float64 type and convert it to a slice of bytes. +--- -#### func Fprint +### Dependencies -```go -func Fprint(w io.Writer, s string) -``` -Fprint is fmt.Fprint with error handling. +[skeeto](https://github.com/skeeto)'s amazing [RNG](https://github.com/skeeto/rng-go) for optimized [entropy](https://pkg.go.dev/git.tcp.direct/kayos/common/entropy) is the sole dependency save for stdlib++. diff --git a/pool/README.md b/pool/README.md new file mode 100644 index 0000000..6cba704 --- /dev/null +++ b/pool/README.md @@ -0,0 +1,98 @@ +# pool + +`import git.tcp.direct/kayos/common/pool` + +## Overview + +pool contains two components, both of which are forms of buffer pools. + + ### *BufferFactory* + + BufferFactory is a potentially safer sync.Pool of [bytes.Buffer](https://pkg.go.dev/bytes#Buffer) types that will not allow you to accidentally re-use buffers after you return them to the pool. + + - `func NewBufferFactory() BufferFactory` + - `func NewSizedBufferFactory(size int) BufferFactory` + - `func (cf BufferFactory) Get() *Buffer` + - `func (cf BufferFactory) MustPut(buf *Buffer)` + - `func (cf BufferFactory) Put(buf *Buffer) error` + + ### *StringFactory* + + StringFactory is very much like BufferFactory, except for it's a pool of [strings.Builder](https://pkg.go.dev/strings#Builder) types instead. + + - `func NewStringFactory() StringFactory` + - `func (sf StringFactory) Get() *String` + - `func (sf StringFactory) MustPut(buf *String)` + - `func (sf StringFactory) Put(buf *String) error` + +## Benchmarks + +#### foreword + +In some usecases, this package will actually allocate slightly more than if one were not using it. That is because each Buffer or String type has the additional header of a [sync.Once](https://pkg.go.dev/sync#Once). The overhead of this is minimal, and in the benchmarks I've put together that attempt to emulate a more realistic use case, the benefits are easy to see. This is comparing it to use without buffer pools at all. Using [sync.Pool](https://pkg.go.dev/sync#Pool) alone without this package will always be ever-so-slightly more efficient, but the consequences of mis-using it could be catastrophic. That is the trade-off we make. + +_Note: "bytes" here refers to the size of buffer pre-allocation. Either with NewSizedBufferFactory or bytes.NewBuffer_ + +--- + +### Using this package + +``` +BenchmarkBufferFactory/SingleProc-64-bytes-24 410792 3467 ns/op 24685 B/op 5 allocs/op +BenchmarkBufferFactory/SingleProc-1024-bytes-24 376539 3668 ns/op 24687 B/op 5 allocs/op +BenchmarkBufferFactory/SingleProc-4096-bytes-24 281402 3599 ns/op 24688 B/op 5 allocs/op +BenchmarkBufferFactory/SingleProc-65536-bytes-24 340872 3591 ns/op 24830 B/op 5 allocs/op +``` + +``` +BenchmarkBufferFactory/Concurrent-x2-64-bytes-24 498634 2076 ns/op 24678 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x2-1024-bytes-24 569001 2128 ns/op 24684 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x2-4096-bytes-24 602946 2131 ns/op 24688 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x2-65536-bytes-24 779770 1522 ns/op 24747 B/op 5 allocs/op +``` + +``` +BenchmarkBufferFactory/Concurrent-x4-64-bytes-24 319677 3271 ns/op 24695 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x4-1024-bytes-24 597859 2005 ns/op 24677 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x4-4096-bytes-24 586940 2092 ns/op 24685 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x4-65536-bytes-24 861326 1420 ns/op 24719 B/op 5 allocs/op +``` + +``` +BenchmarkBufferFactory/Concurrent-x8-64-bytes-24 621253 1893 ns/op 24672 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x8-1024-bytes-24 626067 2155 ns/op 24678 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x8-4096-bytes-24 644078 2030 ns/op 24682 B/op 5 allocs/op +BenchmarkBufferFactory/Concurrent-x8-65536-bytes-24 878794 1382 ns/op 24718 B/op 5 allocs/op +``` + +--- + +### Allocating new bytes.Buffers + +``` +BenchmarkNotUsingPackage/SingleProc-64-bytes-24 121978 9401 ns/op 52000 B/op 5 allocs/op +BenchmarkNotUsingPackage/SingleProc-1024-bytes-24 129132 9004 ns/op 52000 B/op 5 allocs/op +BenchmarkNotUsingPackage/SingleProc-4096-bytes-24 138590 8894 ns/op 52000 B/op 5 allocs/op +BenchmarkNotUsingPackage/SingleProc-65536-bytes-24 134730 8891 ns/op 52000 B/op 5 allocs/op +``` + +``` +BenchmarkNotUsingPackage/Concurrent-x2-64-bytes-24 150890 8488 ns/op 52225 B/op 8 allocs/op +BenchmarkNotUsingPackage/Concurrent-x2-1024-bytes-24 174734 8924 ns/op 55937 B/op 7 allocs/op +BenchmarkNotUsingPackage/Concurrent-x2-4096-bytes-24 101695 11032 ns/op 65537 B/op 6 allocs/op +BenchmarkNotUsingPackage/Concurrent-x2-65536-bytes-24 43708 28977 ns/op 286724 B/op 5 allocs/op +``` + +``` +BenchmarkNotUsingPackage/Concurrent-x4-64-bytes-24 189124 6314 ns/op 52224 B/op 8 allocs/op +BenchmarkNotUsingPackage/Concurrent-x4-1024-bytes-24 144324 7010 ns/op 55937 B/op 7 allocs/op +BenchmarkNotUsingPackage/Concurrent-x4-4096-bytes-24 129194 9325 ns/op 65537 B/op 6 allocs/op +BenchmarkNotUsingPackage/Concurrent-x4-65536-bytes-24 43641 28730 ns/op 286723 B/op 5 allocs/op +``` + +``` +BenchmarkNotUsingPackage/Concurrent-x8-64-bytes-24 184123 5911 ns/op 52224 B/op 8 allocs/op +BenchmarkNotUsingPackage/Concurrent-x8-1024-bytes-24 172016 6602 ns/op 55937 B/op 7 allocs/op +BenchmarkNotUsingPackage/Concurrent-x8-4096-bytes-24 129916 9030 ns/op 65537 B/op 6 allocs/op +BenchmarkNotUsingPackage/Concurrent-x8-65536-bytes-24 45729 26344 ns/op 286723 B/op 5 allocs/op +```