Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,39 @@ sub := stream.Subscribe(ctx, &ringbuf.SubscribeOpts{
})
```

### Waking Parked Readers on Context Cancellation

A `Subscriber` parked in `Read()` sleeps until the next `Write()`/`Close()` broadcast.
Context cancellation is only observed when a broadcast wakes it up: with an idle writer,
a canceled subscriber stays parked -- its `Read()` does not return until the next `Write()`.

`WakeOnCancel` opts into a periodic wake:

```go
sub := stream.Subscribe(ctx, &ringbuf.SubscribeOpts{
WakeOnCancel: true, // Wake parked Read() when ctx is canceled
})
```

The first opted-in subscriber starts one shared reaper goroutine per `RingBuffer`, which
broadcasts every `StreamReaperInterval` (250 ms by default). A canceled reader therefore
exits within one interval, no matter how many subscribers opted in. The reaper stops when
the last opted-in subscriber is done -- either `Read()` returned a terminal error, or
`Subscriber.Close()` was called.

Measured tradeoff (Apple M4 Pro, Go 1.27, `BenchmarkSubscribe`):

| `WakeOnCancel` | ns/op | B/op | allocs/op |
|---|---|---|---|
| off (default) | ~55 | 192 | 3 |
| on | ~84 | 304 | 4 |

The cost is paid once per `Subscribe()`: `ctx.Done()` allocates its channel lazily, and the
first opted-in subscriber starts the reaper goroutine. The `Write()` hot path is unchanged
either way. Leave it off when writes are continuous -- the next broadcast observes the
cancel anyway. Turn it on when writes can be idle a long time and parked readers must exit
promptly.

### Reconnection Logic

The `Seek()` method allows subscribers to fast-forward to a specific position efficiently without locking
Expand Down
182 changes: 182 additions & 0 deletions reaper_internal_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
package ringbuf

import (
"context"
"errors"
"testing"
"time"
)

// setReaperInterval makes the WakeOnCancel reaper tick fast, so opted-in tests stay quick.
func setReaperInterval(t *testing.T, d time.Duration) {
t.Helper()
prev := StreamReaperInterval
StreamReaperInterval = d
t.Cleanup(func() { StreamReaperInterval = prev })
}

// reaperState returns the reaper's done channel, or nil when the reaper isn't running.
func reaperState[T any](rb *RingBuffer[T]) chan struct{} {
rb.reaperMu.Lock()
defer rb.reaperMu.Unlock()
return rb.reaperDone
}

// readErr runs one Read() and reports its error.
func readErr[T any](sub *Subscriber[T]) chan error {
done := make(chan error, 1)
go func() {
_, err := sub.Read(make([]T, 1))
done <- err
}()
return done
}

// The shared reaper must exit once the last opted-in subscriber is done, without an explicit Close().
func TestReaperStopsAfterLastOptedInSubscriber(t *testing.T) {
setReaperInterval(t, 5*time.Millisecond)

stream := New[int](100)

ctx1, cancel1 := context.WithCancel(context.Background())
defer cancel1()
ctx2, cancel2 := context.WithCancel(context.Background())
defer cancel2()

sub1 := stream.Subscribe(ctx1, &SubscribeOpts{WakeOnCancel: true})
sub2 := stream.Subscribe(ctx2, &SubscribeOpts{WakeOnCancel: true})

reaperDone := reaperState(stream)
if reaperDone == nil {
t.Fatal("reaper not started for opted-in subscribers")
}
if got := stream.numOptedIn.Load(); got != 2 {
t.Fatalf("numOptedIn = %d, want 2", got)
}

err1 := readErr(sub1)
err2 := readErr(sub2)
time.Sleep(20 * time.Millisecond) // Let both readers park.

cancel1()
if err := <-err1; !errors.Is(err, context.Canceled) {
t.Fatalf("sub1 Read error = %v, want context.Canceled", err)
}

select {
case <-reaperDone:
t.Fatal("reaper stopped while an opted-in subscriber was still active")
default:
}

cancel2()
if err := <-err2; !errors.Is(err, context.Canceled) {
t.Fatalf("sub2 Read error = %v, want context.Canceled", err)
}

select {
case <-reaperDone:
case <-time.After(time.Second):
t.Fatal("reaper goroutine still running after the last opted-in subscriber")
}

if got := reaperState(stream); got != nil {
t.Fatal("reaper state not cleared after the last opted-in subscriber")
}
}

// Without SubscribeOpts.WakeOnCancel, Subscribe() must not start the reaper and Close() must not disturb it.
func TestWakeOnCancelNoReaperByDefault(t *testing.T) {
setReaperInterval(t, 5*time.Millisecond)

stream := New[int](100)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
sub := stream.Subscribe(ctx, nil)

if got := reaperState(stream); got != nil {
t.Fatal("reaper started without SubscribeOpts.WakeOnCancel")
}

errDone := readErr(sub)
time.Sleep(20 * time.Millisecond) // Let the reader park.
cancel()

select {
case err := <-errDone:
t.Fatalf("Read returned %v before any Write; default Subscribe must not wake on ctx cancel", err)
case <-time.After(50 * time.Millisecond):
// Still parked, as expected.
}

if err := sub.Close(); err != nil {
t.Fatalf("Close() = %v, want nil", err)
}
if got := stream.numOptedIn.Load(); got != 0 {
t.Fatalf("numOptedIn = %d after closing a non-opted-in subscriber, want 0", got)
}

stream.Write(42) // Wake the parked reader so its goroutine doesn't leak.

select {
case err := <-errDone:
if err != nil {
t.Fatalf("expected nil error after Write, got %v", err)
}
case <-time.After(2 * time.Second):
t.Fatal("Read did not wake on Write")
}
}

// Close() must stop the reaper even when the subscriber never reached a terminal Read error.
func TestCloseStopsReaperBeforeReadEnds(t *testing.T) {
setReaperInterval(t, 5*time.Millisecond)

stream := New[int](100)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
sub := stream.Subscribe(ctx, &SubscribeOpts{WakeOnCancel: true})

reaperDone := reaperState(stream)
if reaperDone == nil {
t.Fatal("reaper not started for an opted-in subscriber")
}

errDone := readErr(sub)
time.Sleep(20 * time.Millisecond) // Let the reader park.

if err := sub.Close(); err != nil {
t.Fatalf("Close() = %v, want nil", err)
}
if err := sub.Close(); err != nil { // Idempotent.
t.Fatalf("second Close() = %v, want nil", err)
}

select {
case <-reaperDone:
case <-time.After(time.Second):
t.Fatal("reaper goroutine still running after Close()")
}

cancel()

select {
case err := <-errDone:
t.Fatalf("Read returned %v after Close(); the reaper must be the only cancel wake", err)
case <-time.After(50 * time.Millisecond):
// Still parked, as documented for Close().
}

stream.Write(1) // Any Write still wakes it.

select {
case err := <-errDone:
if err != nil {
t.Fatalf("expected nil error after Write, got %v", err)
}
case <-time.After(2 * time.Second):
t.Fatal("Read did not wake on Write")
}
}
98 changes: 95 additions & 3 deletions ringbuf.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,16 @@ import (
"context"
"sync"
"sync/atomic"
"time"
)

// StreamReaperInterval is how often the WakeOnCancel reaper broadcasts, waking parked
// subscribers so they can observe context cancellation while the writer is idle.
//
// It bounds how long a canceled subscriber can stay parked. The tick runs only while at
// least one subscriber opted into SubscribeOpts.WakeOnCancel. Values <= 0 disable the ticks.
var StreamReaperInterval = 250 * time.Millisecond

// New creates a ring buffer for items of type T with the given buffer size.
//
// Pick a size large enough to absorb write bursts. A subscriber's MaxLag is capped
Expand Down Expand Up @@ -50,6 +58,13 @@ type RingBuffer[T any] struct {
// Synchronization primitives for waking up subscribers waiting for new data.
mu sync.Mutex
cond *sync.Cond

// Shared WakeOnCancel reaper: one goroutine per ring buffer, running only while at least
// one subscriber opted into SubscribeOpts.WakeOnCancel.
reaperMu sync.Mutex
reaperCancel chan struct{} // Closed to stop the reaper goroutine. nil when not running.
reaperDone chan struct{} // Closed by the reaper goroutine when it exits.
numOptedIn atomic.Int64 // Opted-in subscribers that have not released the reaper yet.
}

// SubscribeOpts is a set of options for subscribing to a ring buffer.
Expand Down Expand Up @@ -85,6 +100,13 @@ type SubscribeOpts struct {

// Number of items the Iter() iterator will batch read. If 0, the default value is 64.
IterBatchSize uint

// WakeOnCancel wakes a parked Read() when the subscriber context is canceled.
// Off by default: it starts one shared reaper goroutine per ring buffer that wakes
// parked readers every StreamReaperInterval (measured ~84 ns vs ~55 ns; see README).
// Only needed when writes can be idle a long time; otherwise the next Write()
// broadcast wakes canceled readers anyway.
WakeOnCancel bool
}

// Subscribe creates a new reader starting from the given position.
Expand All @@ -105,21 +127,86 @@ func (rb *RingBuffer[T]) Subscribe(ctx context.Context, opts *SubscribeOpts) *Su
startPos = 0
}

return &Subscriber[T]{
sub := &Subscriber[T]{
Name: opts.Name,
rb: rb,
pos: startPos,
ctx: ctx,
maxLag: maxBehind,
iterBatchSize: iterBatchSize,
}

if opts.WakeOnCancel && ctx.Done() != nil {
// Count the subscriber before starting the reaper, so a concurrent release can't
// stop a reaper that the subscriber still depends on.
sub.optedIn = true
rb.numOptedIn.Add(1)
rb.startReaper()
}

return sub
}

// startReaper starts the shared WakeOnCancel reaper goroutine if it isn't running.
func (rb *RingBuffer[T]) startReaper() {
rb.reaperMu.Lock()
defer rb.reaperMu.Unlock()

if rb.reaperCancel != nil {
return
}

rb.reaperCancel = make(chan struct{})
rb.reaperDone = make(chan struct{})
go rb.reap(rb.reaperCancel, rb.reaperDone)
}

// stopReaper stops the reaper goroutine if no opted-in subscriber is left.
func (rb *RingBuffer[T]) stopReaper() {
rb.reaperMu.Lock()
cancel, done := rb.reaperCancel, rb.reaperDone
if cancel == nil || rb.numOptedIn.Load() > 0 {
rb.reaperMu.Unlock()
return
}
rb.reaperCancel, rb.reaperDone = nil, nil
rb.reaperMu.Unlock()

close(cancel)
<-done
}

// reap wakes parked readers on a ticker, so canceled ones observe ctx.Done() during writer idle.
func (rb *RingBuffer[T]) reap(cancel, done chan struct{}) {
defer close(done)

if StreamReaperInterval <= 0 {
<-cancel
return
}

ticker := time.NewTicker(StreamReaperInterval)
defer ticker.Stop()

for {
select {
case <-cancel:
return
case <-ticker.C:
rb.mu.Lock()
rb.cond.Broadcast()
rb.mu.Unlock()
}
}
}

// Write inserts items into the ring buffer and wakes up all waiting subscribers to read them.
// This method is not concurrent safe, the caller must synchronize calls to Write() and Close().
//
// Subscribers can block waiting for new data. If the writer is idle, call Write() with zero items
// to wake subscribers so they can observe context cancellation.
// Subscribers can block waiting for new data. Unless SubscribeOpts.WakeOnCancel is set, a
// canceled reader only observes cancellation on the next broadcast, so an idle writer should
// occasionally call Write() with zero items to drop canceled subscribers. Opted-in readers are
// woken by the shared reaper instead, so this applies to the default path only.
//
// NOTE: A large write batch can make subscribers fall behind; if it pushes a subscriber past
// MaxLag, it will be dropped with ErrTooSlow on the next Read() call. Keep the batch reasonable
Expand All @@ -135,10 +222,13 @@ func (rb *RingBuffer[T]) Write(items ...T) {
// writePos overflowed, increment the epoch.
rb.writeEpoch.Add(1)
}
rb.mu.Lock()
rb.writePos.Store(writePos)

// Wake up all subscribers.
// Hold mu so a broadcast can't land between a reader's check and its park.
rb.cond.Broadcast()
rb.mu.Unlock()
}

// Close signals the end of the stream and wakes up all waiting subscribers.
Expand All @@ -151,8 +241,10 @@ func (rb *RingBuffer[T]) Write(items ...T) {
// the writer must stop producing new data. Writing new data later results in
// undefined behavior. Calling Close() twice will result in a panic.
func (rb *RingBuffer[T]) Close() {
rb.mu.Lock()
close(rb.closed)
rb.cond.Broadcast()
rb.mu.Unlock()
}

func (rb *RingBuffer[T]) Size() uint64 {
Expand Down
Loading
Loading