Initial commit

.github/workflows/main.yaml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - 'master'
+  pull_request:
+
+jobs:
+  mod:
+    name: Mod
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Read Go version
+        run: echo "GO_VERSION=$(cat ./.go-version)" >> $GITHUB_ENV
+      - uses: actions/setup-go@v3
+        with:
+          go-version: ${{ env.GO_VERSION }}
+      - uses: actions/cache@v3
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-gomod-${{ hashFiles('**/go.sum') }}
+      - run: go mod download
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Read Go version
+        run: echo "GO_VERSION=$(cat ./.go-version)" >> $GITHUB_ENV
+      - uses: actions/setup-go@v3
+        with:
+          go-version: ${{ env.GO_VERSION }}
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v3
+        with:
+          version: latest
+          args: "--timeout 3m0s"
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: [build]
+    env:
+      GOCACHE: "/tmp/go/cache"
+    steps:
+      - uses: actions/checkout@v3
+      - name: Read Go version
+        run: echo "GO_VERSION=$(cat ./.go-version)" >> $GITHUB_ENV
+      - uses: actions/setup-go@v3
+        with:
+          go-version: ${{ env.GO_VERSION }}
+      - uses: actions/cache@v3
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-gomod-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-gomod-
+      - uses: actions/cache@v3
+        with:
+          path: /tmp/go/cache
+          key: ${{ runner.os }}-go-build-${{ github.ref }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-go-build-${{ github.ref }}-
+            ${{ runner.os }}-go-build-
+      - name: Run tests
+        run: |-
+          # Run race tests (excludes race_test.go)
+          go test ./... -race -shuffle=on
+          # Upload coverage file on non-race tests
+          go test ./... -coverprofile=coverage.txt -shuffle=on
+      - name: Upload coverage data
+        uses: codecov/codecov-action@v2
+        with:
+          files: ./coverage.txt

.gitignore

@@ -0,0 +1,4 @@
+/.idea
+/.vscode
+
+/sc

.go-version

@@ -0,0 +1 @@
+1.18.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 motoki317
+
+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

@@ -0,0 +1,31 @@
+# sc
+
+[![GitHub release](https://img.shields.io/github/release/motoki31/sc.svg)](https://github.com/motoki317/sc/releases/)
+![CI main](https://github.com/motoki317/sc/actions/workflows/main.yaml/badge.svg)
+[![codecov](https://codecov.io/gh/motoki317/sc/branch/main/graph/badge.svg)](https://codecov.io/gh/motoki317/sc)
+[![Go Reference](https://pkg.go.dev/badge/github.com/motoki317/sc.svg)](https://pkg.go.dev/github.com/motoki317/sc)
+
+sc is a simple golang in-memory caching library, with easily configurable implementations.
+
+## Notable Features
+
+- Simple to use; the only methods are Get(), GetFresh(), and Forget().
+  - There is no Set() method - this is an intentional design choice to make the use easier.
+- Supports 1.18 generics - both key and value are generic.
+  - No `interface{}` even in internal implementations.
+- Supported cache backends
+  - Built-in map (default) - lightweight, but does not evict items.
+  - LRU (`WithLRUBackend(cap)` option) - automatically evicts overflown items.
+- Prevents [cache stampede](https://en.wikipedia.org/wiki/Cache_stampede) problem idiomatically.
+- All methods are safe to be called from multiple goroutines.
+- Allows graceful cache replacement (if `freshFor` < `ttl`) - only one goroutine is launched in the background to re-fetch the value.
+- Allows strict request coalescing (`EnableStrictCoalescing()` option) - ensures that all returned values are fresh (a niche use-case).
+
+## Usage
+
+See [reference](https://pkg.go.dev/github.com/motoki317/sc).
+
+## Borrowed Ideas
+
+- [go-chi/stampede: Function and HTTP request coalescer](https://github.com/go-chi/stampede)
+- [singleflight package - golang.org/x/sync/singleflight - pkg.go.dev](https://pkg.go.dev/golang.org/x/sync/singleflight)

backend.go

@@ -0,0 +1,61 @@
+package sc
+
+import (
+	"sync"
+
+	"github.com/dboslee/lru"
+)
+
+// backend represents a cache backend.
+// Backend implementations are expected to be goroutine-safe.
+type backend[K comparable, V any] interface {
+	Get(key K) (v V, ok bool)
+	Set(key K, v V)
+	Delete(key K)
+}
+
+// Interface guard
+var (
+	_ backend[string, string] = &mapBackend[string, string]{}
+	_ backend[string, string] = lruBackend[string, string]{}
+)
+
+type mapBackend[K comparable, V any] struct {
+	mu sync.RWMutex
+	m  map[K]V
+}
+
+func (m *mapBackend[K, V]) Get(key K) (v V, ok bool) {
+	m.mu.RLock()
+	v, ok = m.m[key]
+	m.mu.RUnlock()
+	return
+}
+
+func (m *mapBackend[K, V]) Set(key K, v V) {
+	m.mu.Lock()
+	m.m[key] = v
+	m.mu.Unlock()
+}
+
+func (m *mapBackend[K, V]) Delete(key K) {
+	m.mu.Lock()
+	delete(m.m, key)
+	m.mu.Unlock()
+}
+
+type lruBackend[K comparable, V any] struct {
+	*lru.SyncCache[K, V]
+}
+
+func (l lruBackend[K, V]) Get(key K) (v V, ok bool) {
+	return l.SyncCache.Get(key)
+}
+
+func (l lruBackend[K, V]) Set(key K, v V) {
+	l.SyncCache.Set(key, v)
+}
+
+func (l lruBackend[K, V]) Delete(key K) {
+	l.SyncCache.Delete(key)
+}

benchmark_test.go

@@ -0,0 +1,71 @@
+package sc
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func BenchmarkCache_Map(b *testing.B) {
+	replaceFn := func(ctx context.Context, key string) (string, error) {
+		return "value", nil
+	}
+	cache, err := New[string, string](replaceFn, 1*time.Second, 1*time.Second, WithMapBackend())
+	if err != nil {
+		b.Error(err)
+	}
+
+	ctx := context.Background()
+	b.StartTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = cache.Get(ctx, "key")
+	}
+}
+
+func BenchmarkCache_MapStrict(b *testing.B) {
+	replaceFn := func(ctx context.Context, key string) (string, error) {
+		return "value", nil
+	}
+	cache, err := New[string, string](replaceFn, 1*time.Second, 1*time.Second, WithMapBackend(), EnableStrictCoalescing())
+	if err != nil {
+		b.Error(err)
+	}
+
+	ctx := context.Background()
+	b.StartTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = cache.Get(ctx, "key")
+	}
+}
+
+func BenchmarkCache_LRU(b *testing.B) {
+	replaceFn := func(ctx context.Context, key string) (string, error) {
+		return "value", nil
+	}
+	cache, err := New[string, string](replaceFn, 1*time.Second, 1*time.Second, WithLRUBackend(10))
+	if err != nil {
+		b.Error(err)
+	}
+
+	ctx := context.Background()
+	b.StartTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = cache.Get(ctx, "key")
+	}
+}
+
+func BenchmarkCache_LRUStrict(b *testing.B) {
+	replaceFn := func(ctx context.Context, key string) (string, error) {
+		return "value", nil
+	}
+	cache, err := New[string, string](replaceFn, 1*time.Second, 1*time.Second, WithLRUBackend(10), EnableStrictCoalescing())
+	if err != nil {
+		b.Error(err)
+	}
+
+	ctx := context.Background()
+	b.StartTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = cache.Get(ctx, "key")
+	}
+}