publish v0.0.1

.github/workflows/go.yml

@@ -0,0 +1,37 @@
+# This workflow will build a golang project
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
+
+name: Go
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+
+  test:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ ubuntu-20.04, ubuntu-22.04, windows-latest,  macos-latest ]
+        go: [ '1.12', '1.16', '1.18', '1.19', '1.21' ]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ matrix.go }}
+
+      - name: unittest
+        run: go test -v --tags=nobench ./...
+
+      - name: Benchmark
+        run: go test -v -run Bench
+
+      - name: Profiling
+        run: echo "adaptive pprof"; go tool pprof -text adaptive_cpu.pprof; echo "default pprof"; go tool pprof -text default_cpu.pprof;

.gitignore

@@ -0,0 +1,24 @@
+### Go template
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+
+*_cpu.pprof

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 fangwentong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,26 +1,110 @@
-# GOGCTuner
+# gogctuner: GC Tuner for Go Applications
 
-idea is from this article [How We Saved 70K Cores Across 30 Mission-Critical Services (Large-Scale, Semi-Automated Go GC Tuning @Uber) ](https://eng.uber.com/how-we-saved-70k-cores-across-30-mission-critical-services/)
+`gogctuner` is a Go library designed to automatically adjust the garbage collection (GC) parameters to optimize CPU
+usage based on the target memory usage percentage.
 
-## How to use this lib?
+## How it works
 
-just call NewTuner when initializing app :
+- **Pre Go1.19 Versions**: Utilizes a tuning strategy inspired
+  by [Uber's article](https://www.uber.com/blog/how-we-saved-70k-cores-across-30-mission-critical-services/), which
+  adjusts the `GOGC` parameter based on the live heap size and target memory limit.
+- **Go1.19 and Later**: Takes advantage of
+  the [soft memory limit feature](https://github.com/golang/proposal/blob/master/design/48409-soft-memory-limit.md)
+  introduced in Go 1.19, offering more granular control over GC behavior.
+
+## Features
+
+- **Memory Usage Based Tuning**: Automatically adjusts GC parameters to maintain a specified percentage of memory usage.
+- **Cross-Version Compatibility**: Compatible with Go versions below 1.19 and leverages the `SetMemoryLimit` features in
+  Go 1.19 and above.
+- **cgroups Support**: Works seamlessly with both cgroups and cgroupsv2 for enhanced resource management.
+- **Cross-OS Compatibility**: Ensures functionality across multiple operating systems.
+
+## Usage
+
+### Static Configuration
+
+Use static configuration by setting the `MaxRAMPercentage` at the initialization of your application:
+
+```go
+package main
+
+import (
+	"github.com/fangwentong/gogctuner"
+)
+
+func main() {
+	gogctuner.EnableGCTuner(
+		gogctuner.WithStaticConfig(gogctuner.Config{MaxRAMPercentage: 90}),
+	)
+}
+```
+
+### Dynamic Configuration
+
+For dynamic configuration that allows runtime updates, you can use a configurator:
 
 ```go
-func initProcess() {
-	var (
-		inCgroup = true
-		percent = 70
+package main
+
+import (
+	"github.com/fangwentong/gogctuner"
+	"sync/atomic"
+)
+
+func main() {
+	configurator := newConfigurator()
+
+	// Integrate with your dynamic config implementation here:
+	// conf := readFromYourConfigCenter("some_config_key")
+	// configurator.Set(conf)
+	// registerConfigUpdateCallback("some_config_key", func(conf *gogctuner.Config) {
+	//     configurator.Set(conf)
+	// })
+
+	gogctuner.EnableGCTuner(
+		gogctuner.WithConfigurator(configurator),
 	)
-	go NewTuner(inCgroup, percent)
+}
+
+func newConfigurator() *exampleDynamicConfigurator {
+	return &exampleDynamicConfigurator{
+		updateCh: make(chan interface{}, 1),
+	}
+}
+
+type exampleDynamicConfigurator struct {
+	conf     atomic.Value
+	updateCh chan interface{}
+}
+
+func (e *exampleDynamicConfigurator) GetConfig() (gogctuner.Config, error) {
+	val, _ := e.conf.Load().(gogctuner.Config)
+	return val, nil
+}
+
+func (e *exampleDynamicConfigurator) Updates() <-chan interface{} {
+	return e.updateCh
+}
+
+func (e *exampleDynamicConfigurator) Set(conf gogctuner.Config) {
+	e.conf.Store(conf)
+	select {
+	case e.updateCh <- struct{}{}: // Notify the config change
+	default:
+	}
 }
 ```
 
-## Current Status
+### Reference
 
-Go 1.19 adds a [soft memory limit](https://github.com/golang/proposal/blob/master/design/48409-soft-memory-limit.md) which changes its pacer algorithm and scvg behavior, we'll see what go team will provide in the new version. Maybe this lib can be deprecated in Go 1.19.
+- Golang GC Guide: https://tip.golang.org/doc/gc-guide
+- How We Saved 70K Cores Across 30 Mission-Critical Services (Large-Scale, Semi-Automated Go GC Tuning
+  @Uber): https://www.uber.com/blog/how-we-saved-70k-cores-across-30-mission-critical-services/
+- https://github.com/cch123/gogctuner
+- https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/lib/cgroup
 
-official guide for gogc and memory limit params:
+### License
 
-https://tip.golang.org/doc/gc-guide
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.