feat!: ship v1 release with simplified APIs

Author: KimMachineGun

README.md

@@ -10,11 +10,16 @@ See more details about `GOMEMLIMIT` [here](https://tip.golang.org/doc/gc-guide#M
 
 ## Notice
 
-Version `v0.5.0` introduces a fallback to system memory limits as an experimental feature when cgroup limits are unavailable. Activate this by setting `AUTOMEMLIMIT_EXPERIMENT=system`.
-You can also use system memory limits via `memlimit.FromSystem` provider directly.
+Version `v1.0.0` introduces breaking changes to improve usability by simplifying multiple functions into a single `memlimit.Set()` function with options, and to provide more consistent and predictable behavior.
 
-This feature is under evaluation and might become a default or be removed based on user feedback.
-If you have any feedback about this feature, please open an issue.
+Key changes from v0.x:
+- `SetGoMemLimitWithOpts`, `SetGoMemLimit`, `SetGoMemLimitWithProvider`, `SetGoMemLimitWithEnv` removed; use `Set` instead
+- `FromCgroupV1`, `FromCgroupV2`, `FromCgroupHybrid` removed; use `FromCgroup` instead
+- `import _ "github.com/KimMachineGun/automemlimit"` now automatically falls back to system memory when cgroup is unavailable or limit is not set (ErrNoLimit)
+- When `ErrNoLimit` is returned from the provider, GOMEMLIMIT is set to `math.MaxInt64` (unlimited) and returned as a successful result
+- `Set` now returns the previous GOMEMLIMIT value instead of 0 when skipping (e.g., `GOMEMLIMIT` already set or `AUTOMEMLIMIT=off`) or when an error occurs
+- `WithRefreshInterval(ctx, duration)` now requires a `context.Context` to control the refresh goroutine
+- New `WithMin(bytes)` option to set a minimum memory limit
 
 ## Installation
 
@@ -27,41 +32,39 @@ go get github.com/KimMachineGun/automemlimit@latest
 ```go
 package main
 
-// By default, it sets `GOMEMLIMIT` to 90% of cgroup's memory limit.
-// This is equivalent to `memlimit.SetGoMemLimitWithOpts(memlimit.WithLogger(slog.Default()))`
-// To disable logging, use `memlimit.SetGoMemLimitWithOpts` directly.
+// Sets GOMEMLIMIT to 90% of cgroup's memory limit.
+// Falls back to system memory if cgroup is unavailable or limit is not set (ErrNoLimit).
 import _ "github.com/KimMachineGun/automemlimit"
 ```
 
-or
+> **Note:** `memlimit.Set()` defaults to `memlimit.FromCgroup` only. Use `memlimit.ApplyFallback(memlimit.FromCgroup, memlimit.FromSystem)` explicitly if you need system memory fallback.
+
+For more control, use `memlimit.Set()` directly:
 
 ```go
 package main
 
-import "github.com/KimMachineGun/automemlimit/memlimit"
+import (
+	"context"
+	"log/slog"
+	"time"
 
-func init() {
-	memlimit.SetGoMemLimitWithOpts(
-		memlimit.WithRatio(0.9),
-		memlimit.WithProvider(memlimit.FromCgroup),
-		memlimit.WithLogger(slog.Default()),
-		memlimit.WithRefreshInterval(1*time.Minute),
-	)
-	memlimit.SetGoMemLimitWithOpts(
-		memlimit.WithRatio(0.9),
+	"github.com/KimMachineGun/automemlimit/memlimit"
+)
+
+func main() {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	memlimit.Set(
+		// Fallback to system memory if cgroup is unavailable or limit is not set (ErrNoLimit).
 		memlimit.WithProvider(
-			memlimit.ApplyFallback(
-				memlimit.FromCgroup,
-				memlimit.FromSystem,
-			),
+			memlimit.ApplyFallback(memlimit.FromCgroup, memlimit.FromSystem),
 		),
-		memlimit.WithRefreshInterval(1*time.Minute),
+		memlimit.WithRatio(0.9),               // Use 90% of the limit (default)
+		memlimit.WithMin(512 * 1024 * 1024),   // At least 512MB
+		memlimit.WithRefreshInterval(ctx, time.Minute), // Refresh every minute
+		memlimit.WithLogger(slog.Default()),
 	)
-	memlimit.SetGoMemLimit(0.9)
-	memlimit.SetGoMemLimitWithProvider(memlimit.Limit(1024*1024), 0.9)
-	memlimit.SetGoMemLimitWithProvider(memlimit.FromCgroup, 0.9)
-	memlimit.SetGoMemLimitWithProvider(memlimit.FromCgroupV1, 0.9)
-	memlimit.SetGoMemLimitWithProvider(memlimit.FromCgroupHybrid, 0.9)
-	memlimit.SetGoMemLimitWithProvider(memlimit.FromCgroupV2, 0.9)
 }
 ```

automemlimit.go

@@ -1,3 +1,11 @@
+// Package automemlimit provides automatic GOMEMLIMIT configuration.
+//
+// Importing this package automatically sets GOMEMLIMIT based on cgroup memory limits,
+// falling back to system memory if cgroup is unavailable or limit is not set ([memlimit.ErrNoLimit]).
+//
+//	import _ "github.com/KimMachineGun/automemlimit"
+//
+// For more control, use the memlimit package directly.
 package automemlimit
 
 import (
@@ -7,7 +15,13 @@ import (
 )
 
 func init() {
-	memlimit.SetGoMemLimitWithOpts(
+	memlimit.Set(
+		memlimit.WithProvider(
+			memlimit.ApplyFallback(
+				memlimit.FromCgroup,
+				memlimit.FromSystem,
+			),
+		),
 		memlimit.WithLogger(slog.Default()),
 	)
 }

examples/dynamic/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"bytes"
+	"context"
 	"errors"
 	"log/slog"
 	"os"
@@ -15,11 +16,12 @@ import (
 func init() {
 	slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stderr, nil)))
 
-	memlimit.SetGoMemLimitWithOpts(
+	refreshCtx := context.Background()
+	memlimit.Set(
 		memlimit.WithProvider(
 			FileProvider("limit.txt"),
 		),
-		memlimit.WithRefreshInterval(5*time.Second),
+		memlimit.WithRefreshInterval(refreshCtx, 5*time.Second),
 		memlimit.WithLogger(slog.Default()),
 	)
 }
@@ -37,7 +39,7 @@ func FileProvider(path string) memlimit.Provider {
 		b, err := os.ReadFile(path)
 		if err != nil {
 			if errors.Is(err, os.ErrNotExist) {
-				return memlimit.ApplyFallback(memlimit.FromCgroup, memlimit.FromSystem)()
+				return memlimit.FromCgroup()
 			}
 			return 0, err
 		}

examples/logger/main.go

@@ -8,10 +8,7 @@ import (
 )
 
 func init() {
-	memlimit.SetGoMemLimitWithOpts(
-		memlimit.WithProvider(
-			memlimit.Limit(1024*1024*1024),
-		),
+	memlimit.Set(
 		memlimit.WithLogger(slog.New(slog.NewJSONHandler(os.Stderr, nil))),
 	)
 }

examples/system/main.go

@@ -1,11 +1,9 @@
 package main
 
-import (
-	"github.com/KimMachineGun/automemlimit/memlimit"
-)
+import "github.com/KimMachineGun/automemlimit/memlimit"
 
 func init() {
-	memlimit.SetGoMemLimitWithOpts(
+	memlimit.Set(
 		memlimit.WithProvider(
 			memlimit.ApplyFallback(
 				memlimit.FromCgroup,

memlimit/cgroups.go

@@ -214,15 +214,11 @@ func readMemoryLimitV1FromPath(cgroupPath string) (uint64, error) {
 	}
 
 	// read memory.limit_in_bytes file.
-	b, err := os.ReadFile(filepath.Join(cgroupPath, "memory.limit_in_bytes"))
+	lib, err := readMemoryLimitInBytes(filepath.Join(cgroupPath, "memory.limit_in_bytes"))
 	if err != nil && !errors.Is(err, os.ErrNotExist) {
 		return 0, fmt.Errorf("failed to read memory.limit_in_bytes: %w", err)
-	}
-	lib, err := strconv.ParseUint(strings.TrimSpace(string(b)), 10, 64)
-	if err != nil {
-		return 0, fmt.Errorf("failed to parse memory.limit_in_bytes value: %w", err)
 	} else if lib == 0 {
-		hml = math.MaxUint64
+		lib = math.MaxUint64
 	}
 
 	// use the minimum value between hierarchical_memory_limit and memory.limit_in_bytes.
@@ -267,6 +263,16 @@ func readHierarchicalMemoryLimit(path string) (uint64, error) {
 	return 0, nil
 }
 
+// readMemoryLimitInBytes reads the memory.limit_in_bytes file.
+// this function expects the path to be memory.limit_in_bytes file.
+func readMemoryLimitInBytes(path string) (uint64, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return 0, err
+	}
+	return strconv.ParseUint(strings.TrimSpace(string(b)), 10, 64)
+}
+
 // https://www.man7.org/linux/man-pages/man5/proc_pid_mountinfo.5.html
 // 731 771 0:59 /sysrq-trigger /proc/sysrq-trigger ro,nosuid,nodev,noexec,relatime - proc proc rw
 //

memlimit/cgroups_linux.go

@@ -7,26 +7,3 @@ package memlimit
 func FromCgroup() (uint64, error) {
 	return fromCgroup(detectCgroupVersion)
 }
-
-// FromCgroupV1 retrieves the memory limit from the cgroup v1 controller.
-// After v1.0.0, this function could be removed and FromCgroup should be used instead.
-func FromCgroupV1() (uint64, error) {
-	return fromCgroup(func(_ []mountInfo) (bool, bool) {
-		return true, false
-	})
-}
-
-// FromCgroupHybrid retrieves the memory limit from the cgroup v2 and v1 controller sequentially,
-// basically, it is equivalent to FromCgroup.
-// After v1.0.0, this function could be removed and FromCgroup should be used instead.
-func FromCgroupHybrid() (uint64, error) {
-	return FromCgroup()
-}
-
-// FromCgroupV2 retrieves the memory limit from the cgroup v2 controller.
-// After v1.0.0, this function could be removed and FromCgroup should be used instead.
-func FromCgroupV2() (uint64, error) {
-	return fromCgroup(func(_ []mountInfo) (bool, bool) {
-		return false, true
-	})
-}

memlimit/cgroups_linux_test.go

@@ -4,6 +4,7 @@
 package memlimit
 
 import (
+	"errors"
 	"testing"
 )
 
@@ -13,58 +14,16 @@ func TestFromCgroup(t *testing.T) {
 	}
 
 	limit, err := FromCgroup()
-	if cgVersion == 0 && err != ErrNoCgroup {
-		t.Fatalf("FromCgroup() error = %v, wantErr %v", err, ErrNoCgroup)
+	if cgVersion == 0 {
+		if !errors.Is(err, ErrNoCgroup) {
+			t.Errorf("FromCgroup() error = %v, wantErr %v", err, ErrNoCgroup)
+		}
+		return
 	}
-
 	if err != nil {
 		t.Fatalf("FromCgroup() error = %v, wantErr %v", err, nil)
 	}
 	if limit != expected {
 		t.Fatalf("FromCgroup() got = %v, want %v", limit, expected)
 	}
 }
-
-func TestFromCgroupHybrid(t *testing.T) {
-	if expected == 0 {
-		t.Skip()
-	}
-
-	limit, err := FromCgroupHybrid()
-	if cgVersion == 0 && err != ErrNoCgroup {
-		t.Fatalf("FromCgroupHybrid() error = %v, wantErr %v", err, ErrNoCgroup)
-	}
-
-	if err != nil {
-		t.Fatalf("FromCgroupHybrid() error = %v, wantErr %v", err, nil)
-	}
-	if limit != expected {
-		t.Fatalf("FromCgroupHybrid() got = %v, want %v", limit, expected)
-	}
-}
-
-func TestFromCgroupV1(t *testing.T) {
-	if expected == 0 || cgVersion != 1 {
-		t.Skip()
-	}
-	limit, err := FromCgroupV1()
-	if err != nil {
-		t.Fatalf("FromCgroupV1() error = %v, wantErr %v", err, nil)
-	}
-	if limit != expected {
-		t.Fatalf("FromCgroupV1() got = %v, want %v", limit, expected)
-	}
-}
-
-func TestFromCgroupV2(t *testing.T) {
-	if expected == 0 || cgVersion != 2 {
-		t.Skip()
-	}
-	limit, err := FromCgroupV2()
-	if err != nil {
-		t.Fatalf("FromCgroupV2() error = %v, wantErr %v", err, nil)
-	}
-	if limit != expected {
-		t.Fatalf("FromCgroupV2() got = %v, want %v", limit, expected)
-	}
-}