Initial implementation

Author: floatdrop

.github/workflows/ci.yaml

@@ -0,0 +1,21 @@
+name: CI
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'
+      - name: Install dependencies
+        run: go get .
+      - name: Build
+        run: go build -v ./...
+      - name: Test with the Go CLI
+        run: go test
+        

README.md

@@ -0,0 +1,61 @@
+# RingChan
+
+[![CI](https://github.com/floatdrop/ringchan/actions/workflows/ci.yaml/badge.svg)](https://github.com/floatdrop/ringchan/actions/workflows/ci.yaml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/floatdrop/ringchan)](https://goreportcard.com/report/github.com/floatdrop/ringchan)
+[![Go Reference](https://pkg.go.dev/badge/github.com/floatdrop/ringchan.svg)](https://pkg.go.dev/github.com/floatdrop/ringchan/v2)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**RingChan** is a thread-safe, fixed-capacity ring buffer implemented as a channel in Go. It mimics Go's channel behavior while providing ring-buffer semantics — meaning **new items overwrite the oldest when full**.
+
+## Features
+
+- Fixed-size buffer with overwrite behavior
+- Range-friendly: can be iterated using `for ... range`
+- Safe for concurrent producers and consumers
+- Supports graceful shutdown via `Close()`
+
+## Installation
+
+```bash
+go get github.com/floatdrop/ringchan
+```
+
+## Usage
+
+```go
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/floatdrop/ringchan"
+)
+
+func main() {
+	rc := ringchan.New[string](3)
+
+	go func() {
+		inputs := []string{"A", "B", "C", "D", "E"}
+		for _, v := range inputs {
+			rc.In <- v
+		}
+		rc.Close()
+	}()
+
+	time.Sleep(50 * time.Millisecond)
+
+	for v := range rc.Out() {
+		fmt.Println("Got:", v)
+	}
+
+	// Output:
+	// Got: C
+	// Got: D
+	// Got: E
+}
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

example_test.go

@@ -0,0 +1,31 @@
+package ringchan_test
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/floatdrop/ringchan"
+)
+
+func ExampleNew() {
+	rc := ringchan.New[string](3)
+
+	go func() {
+		inputs := []string{"A", "B", "C", "D", "E"}
+		for _, v := range inputs {
+			rc.In <- v
+		}
+		rc.Close()
+	}()
+
+	time.Sleep(50 * time.Millisecond)
+
+	for v := range rc.Out {
+		fmt.Println("Got:", v)
+	}
+
+	// Output:
+	// Got: C
+	// Got: D
+	// Got: E
+}

go.mod

@@ -0,0 +1,3 @@
+module github.com/floatdrop/ringchan
+
+go 1.23

ringchan.go

@@ -0,0 +1,57 @@
+package ringchan
+
+type Ring[T any] struct {
+	in  chan T
+	out chan T
+
+	// In is the channel to send values to.
+	In chan<- T
+	// Out is the channel to receive values from.
+	Out <-chan T
+}
+
+// New creates a ring-buffered channel with fixed capacity.
+// When full, new inserts will drop the oldest items to make space.
+func New[T any](capacity int) *Ring[T] {
+	in := make(chan T, capacity)
+	out := make(chan T, capacity)
+
+	rc := &Ring[T]{
+		in:  in,
+		out: out,
+		In:  in,
+		Out: out,
+	}
+
+	go rc.run()
+	return rc
+}
+
+func (rc *Ring[T]) run() {
+	defer close(rc.out)
+
+	for v := range rc.in {
+		select {
+		case rc.out <- v:
+		default:
+			// Do non-blocking receive to drop the oldest item
+			// if the buffer is full. This avoids blocking in case of an empty buffer.
+			select {
+			case <-rc.out:
+				rc.out <- v
+			default:
+				rc.out <- v
+			}
+		}
+	}
+}
+
+// Len returns the number of items currently in the ring buffer.
+func (rc *Ring[T]) Len() int {
+	return len(rc.out)
+}
+
+// Close closes the input channel, ending the ring.
+func (rc *Ring[T]) Close() {
+	close(rc.in)
+}

ringchan_test.go

@@ -0,0 +1,72 @@
+package ringchan
+
+import (
+	"testing"
+	"time"
+)
+
+func TestRingChanBasic(t *testing.T) {
+	rc := New[int](3)
+
+	go func() {
+		for i := 1; i <= 5; i++ {
+			rc.In <- i
+		}
+		rc.Close()
+	}()
+
+	time.Sleep(50 * time.Millisecond)
+
+	l := rc.Len()
+	if l != 3 {
+		t.Fatalf("expected Len()=%v, got %v", 3, l)
+	}
+
+	var got []int
+	for v := range rc.Out {
+		got = append(got, v)
+	}
+
+	// Only last 3 values should be kept due to overwrite
+	want := []int{3, 4, 5}
+	if len(got) != len(want) {
+		t.Fatalf("expected %v values, got %v", len(want), len(got))
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("expected %v at index %d, got %v", want[i], i, got[i])
+		}
+	}
+}
+
+func TestRingChanBlockingReceive(t *testing.T) {
+	rc := New[int](1)
+
+	go func() {
+		time.Sleep(100 * time.Millisecond)
+		rc.In <- 42
+		rc.Close()
+	}()
+
+	val := <-rc.Out
+	if val != 42 {
+		t.Errorf("expected 42, got %v", val)
+	}
+}
+
+func TestRingChanRangeAfterClose(t *testing.T) {
+	rc := New[string](2)
+
+	rc.In <- "foo"
+	rc.In <- "bar"
+	rc.Close()
+
+	var results []string
+	for v := range rc.Out {
+		results = append(results, v)
+	}
+
+	if len(results) != 2 || results[0] != "foo" || results[1] != "bar" {
+		t.Errorf("unexpected results: %v", results)
+	}
+}