Initial commit

Author: codegrapple

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_requests:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: stable
+
+      - name: Test
+        run: go test ./...

.gitignore

@@ -0,0 +1,14 @@
+# Tests
+*.test
+*.out
+
+# IDEs
+.idea
+.vscode
+
+# Emacs
+*~
+\#*\#
+
+# OS
+.DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+
+  - repo: local
+    hooks:
+      - id: go-fmt
+        name: go fmt
+        entry: gofmt -w
+        language: system
+        files: \.go$
+
+      - id: go-vet
+        name: go vet
+        entry: go vet ./...
+        language: system
+        pass_filenames: false
+
+      - id: go-test
+        name: go test
+        entry: go test ./...
+        language: system
+        pass_filenames: false

CHANGELOG

@@ -0,0 +1,8 @@
+2026-01-14  Arian Behvandnejad  <behvandnejad@gmail.com>
+
+	* reaper Deterministic bounded rewrite loop over a priority
+	structure.
+	* heapadapter Adapts container/heap.Interface with explicit
+	locking.
+	* sliceheap Minimal generic implementation of
+	container/heap.Interface backed by a slice.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arian Behvandnejad
+
+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,92 @@
+# reaper
+
+`reaper` implements a deterministic, bounded rewrite loop over a
+priority structure.
+
+It repeatedly removes a single elment from a heap, allows controlled
+reinsertion, and enforces a strict upper bound on growth per step.
+
+## Motivation
+
+Many systems require repeatedly rewriting or rescheduling items based
+on partial information. `reaper` addresses this need while enforcing
+three invariants:
+
+1. Only one element is processed at a time
+2. Reinsertion is explicitly bounded
+3. Callbacks run without holding heap locks
+
+## Core Concepts
+
+### Heap
+
+A `Heap` is a priority structure protected by explicit locking. Reaper
+does not assume ownership of synchronization, allowing it to be
+integrated into exisiting concurrent systems.
+
+### Callback
+
+A `Callback` inspects a popped element and may emit a replacements.
+
+```go
+Visit(front T, emit func(...T) error) (stop bool)
+```
+
+- `emit` buffers elements for reinsertion. It returns an error if the
+  buffer is full.
+- emission is bounded by the configured degree
+- returning `true` stops the reaping process and restores `front` to
+  the heap without reinsertion
+
+### Degree
+
+The degree defines the maximum number of elements a callback may
+emit for reinsertion per visit.
+
+- `degree > 0`: bounded rewrite system (DAG)
+- `degree == 0`: pure consumer
+
+## Usage
+
+```go
+r := reaper.New[int](2) // degree 2
+
+cb := reaper.CallbackFunc[int](func(front int, emit func(...int) error) bool {
+	if front == 1 {
+		emit(4, 5)
+	}
+
+	retur false
+})
+
+res := r.Reap(heap, cb)
+```
+
+### Results
+`Reap` returns one of:
+
+- `Exhausted`: the heap became empty
+- `Stopped`: the callback requested termination
+
+Both of which are perfectly normal outcomes.
+
+## Guarantees
+
+- No heap mutation occurs while callbacks exectue, except caused by
+  another goroutine
+- No callback can cause unbounded growth
+- The heap is always in a valid state
+
+## Heap Adapter
+
+The `heapadapter` subpackage provides adapters for using Go’s `container/heap`
+with `reaper`.
+
+```go
+h := &MyHeap{} // implements container/heap.Interface of Item
+mu := &sync.Mutex{}
+
+heap := heapadapter.New[Item](h, mu)
+r := reaper.New(0)
+_ = r.Reap(heap, cb)
+```

go.mod

@@ -0,0 +1,3 @@
+module github.com/codegrapple/reaper
+
+go 1.25.5

heapadapter/adapter.go

@@ -0,0 +1,65 @@
+// Package heapadapter provides adapters from container/heap to reaper.Heap.
+//
+// The adapter does not introduce additional semantics or synchronization
+// policies. Locking is explicit and delegated to the caller.
+package heapadapter
+
+import (
+	"container/heap"
+	"sync"
+
+	"github.com/codegrapple/reaper"
+)
+
+// Adapter wraps a container/heap.Interface and exposes it as a reaper.Heap[T].
+//
+// The underlying heap.Interface must store values of type T, violation of
+// which is a programmer error and will cause a panic.
+type Adapter[T any] struct {
+	h heap.Interface
+	l sync.Locker
+}
+
+// New constructs a new Adapter.
+//
+// The provided heap.Interface is heap-initialized during construction.
+// Locking behavior is fully controlled by the supplied sync.Locker.
+func New[T any](h heap.Interface, l sync.Locker) *Adapter[T] {
+	heap.Init(h)
+	return &Adapter[T]{h: h, l: l}
+}
+
+// Push inserts an element into the heap.
+func (a *Adapter[T]) Push(elem T) {
+	heap.Push(a.h, elem)
+}
+
+// Pop removes and returns the minimum element from the heap.
+//
+// If the underlying heap contains a value that is not of type T, Pop panics.
+func (a *Adapter[T]) Pop() T {
+	v := heap.Pop(a.h)
+	elem, ok := v.(T)
+	if !ok {
+		panic("heapadapter: unexpected element type")
+	}
+	return elem
+}
+
+// Empty reports whether the heap contains no elements.
+func (a *Adapter[T]) Empty() bool {
+	return a.h.Len() == 0
+}
+
+// Lock acquires the heap lock.
+func (a *Adapter[T]) Lock() {
+	a.l.Lock()
+}
+
+// Unlock releases the heap lock.
+func (a *Adapter[T]) Unlock() {
+	a.l.Unlock()
+}
+
+// Compile-time assertion that Adapter implements reaper.Heap.
+var _ reaper.Heap[any] = (*Adapter[any])(nil)