From 2e13437a9294ad00c4a2959dfb113dc6e48e79c7 Mon Sep 17 00:00:00 2001 From: tamirms Date: Mon, 26 Oct 2026 01:42:33 +0000 Subject: [PATCH] Yield to other work before each block (WithYield) stellar-rpc rebuilds its tx-hash window index while it ingests ledgers, and the build's workers share cores, caches and memory bandwidth with ingest. On a 32-vCPU box, ingest loses about 20 to 26 ms of p99 beside the build, and fewer workers do not win it back. Ingest is bursty, and a block is about half a millisecond of one worker, so the build can run in the gaps: with a gate that the ingest loop holds while it ingests a ledger, passed as WithYield(gate.Wait), ingest comes back to within 0.3 to 4 ms of running alone, while the build runs at 16 workers and 99M keys/s. WithYield(yield) makes the goroutine about to build a block call yield first, in every build mode, inline or parallel, empty blocks included. A yield that blocks holds the build back, one that returns an error fails the build with it, and WithYield(nil) is the same as not passing the option. The workers yield in the block build they share, so a yield error is the block's result and reaches the writer like a build error; the unsorted builder's parallel finish waits on the writer while it reads partitions. A failed block's result is no longer sent once the pipeline's context is done, since a yield that returns its context's error would otherwise stand in for a failure that skipped the writer: 117 of 200 four-worker builds over a sorted file with a record out of order reported context.Canceled. Without a yield the cost is a nil check per block, and the builder benchmarks do not move. The tests cover every mode, the unsorted builder's spill to disk included. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01DjQed1VX9uGU9PWpAjBiz7 --- README.md | 1 + builder.go | 15 +++ builder_options.go | 16 +++ builder_parallel.go | 15 ++- streamhash-spec.md | 8 +- yield_test.go | 288 ++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 340 insertions(+), 3 deletions(-) create mode 100644 yield_test.go diff --git a/README.md b/README.md index dbc9a87..0ce84ae 100644 --- a/README.md +++ b/README.md @@ -178,6 +178,7 @@ rank, err := idx.QueryRank(streamhash.PreHash(originalKey)) | `WithGlobalSeed(seed)` | Hash seed (change on build failure) | fixed default | | `WithMetadata(data)` | Arbitrary metadata stored in the file | none | | `WithBytesPerSync(n)` | Start writeback of the index every `n` bytes written (Linux) | 0 (left to the kernel) | +| `WithYield(yield)` | Call `yield` before each block: one that blocks holds the build back, an error fails it | none (never yields) | ## Choosing an Algorithm diff --git a/builder.go b/builder.go index 21231bc..cb08eb2 100644 --- a/builder.go +++ b/builder.go @@ -246,9 +246,21 @@ func (b *builder) resetCurrentBuilder() { b.builder.Reset() } +// yield calls the WithYield function, if one was given. It runs before every +// block is built, empty blocks included. +func (b *builder) yield(ctx context.Context) error { + if b.cfg.yield == nil { + return nil + } + return b.cfg.yield(ctx) +} + // commitEmptyBlock writes an empty block's metadata directly to the index. // Resets the builder, builds empty metadata, and commits via pwrite. func (b *builder) commitEmptyBlock() error { + if err := b.yield(b.ctx); err != nil { + return err + } b.builder.Reset() metadataNeeded := b.estimateMetadataSize() if cap(b.metadataBuf) < metadataNeeded { @@ -309,6 +321,9 @@ func (b *builder) commitTrailingEmptyBlocksAndFinalize() error { // buildBlock builds the current block into reusable buffers and writes via pwrite. func (b *builder) buildBlock() error { + if err := b.yield(b.ctx); err != nil { + return err + } numKeys := b.currentBlockKeysAdded() entrySize := b.cfg.payloadSize + b.cfg.fingerprintSize diff --git a/builder_options.go b/builder_options.go index f78a546..9fc3e1e 100644 --- a/builder_options.go +++ b/builder_options.go @@ -1,5 +1,7 @@ package streamhash +import "context" + const ( maxPayloadSize = 8 maxFingerprintSize = 4 @@ -18,6 +20,7 @@ type buildConfig struct { unsortedTempDir string // temp directory for unsorted partition files algorithm Algorithm bytesPerSync int // start writeback of the index every this many bytes written; 0 = off + yield func(context.Context) error totalKeys uint64 // Pre-known key count for single-pass builds } @@ -89,6 +92,19 @@ func WithBytesPerSync(n int) BuildOption { } } +// WithYield makes the build yield to other work: before each block, the +// goroutine about to build it calls yield and goes on when it returns. A +// yield that blocks holds the build back, and one that returns an error +// fails the build with it. The context is the build's, done once the build +// is canceled or has failed. Nothing is held while yield blocks: a build at +// rest holds only its buffers and its open files. The default never yields, +// and WithYield(nil) never yields: it is the same as not passing the option. +func WithYield(yield func(ctx context.Context) error) BuildOption { + return func(c *buildConfig) { + c.yield = yield + } +} + // WithAlgorithm sets the block construction algorithm. // Default is AlgoBijection. func WithAlgorithm(algo Algorithm) BuildOption { diff --git a/builder_parallel.go b/builder_parallel.go index 8ce968e..79a29df 100644 --- a/builder_parallel.go +++ b/builder_parallel.go @@ -202,9 +202,13 @@ func (b *builder) loadBlock(blk blockBuilder, entries []routedEntry) { // build solves the loaded block as blockID, writes its payloads after the // keysBefore keys of the blocks before it, and returns the result for the -// writer. The metadata buffer comes from the pool; the writer returns it. +// writer. The metadata buffer comes from the pool; the writer returns it. It +// yields first, and a yield error is the block's result. func (s *blockSolver) build(blockID uint32, keysBefore uint64) blockResult { b := s.b + if err := b.yield(b.workerCtx); err != nil { + return blockResult{blockID: blockID, err: err} + } entrySize := b.cfg.payloadSize + b.cfg.fingerprintSize payloadsNeeded := s.blk.KeysAdded() * entrySize if cap(s.payloadsBuf) < payloadsNeeded { @@ -228,8 +232,15 @@ func (s *blockSolver) build(blockID uint32, keysBefore uint64) blockResult { // returning it cancels workerCtx, which releases any peer workers blocked // sending on resultChan after the writer exits on the first error -- // otherwise they (and drainParallelPipeline's workerGroup.Wait) deadlock. -// Wait then surfaces this error to the build. +// Wait then surfaces this error to the build. An error once workerCtx is +// done is not sent: it may only echo the cancellation, as a yield's does, +// and the writer must not report it in place of the failure. func (b *builder) sendResult(result blockResult) error { + if result.err != nil { + if err := b.workerCtx.Err(); err != nil { + return err + } + } select { case b.resultChan <- result: return result.err diff --git a/streamhash-spec.md b/streamhash-spec.md index 676f9ea..eba3a06 100644 --- a/streamhash-spec.md +++ b/streamhash-spec.md @@ -816,7 +816,13 @@ With `WithWorkers(n)`, both sorted and unsorted builds solve blocks concurrently Throughput scales near-linearly because the serialized step (writing metadata, folding hashes) is cheap relative to solving. The pipeline is carefully torn down on error or cancellation so a failing block, a writer-side I/O error, or a context cancel never deadlocks the pool — any internal failure cancels the worker context exactly once, releasing every parked goroutine. -### 6.4. Thread safety +### 6.4. Yielding to other work + +`WithYield(yield)` lets a build give way to other work between blocks. Before each block, empty blocks included, the goroutine about to build it calls `yield` with the build's context and goes on when it returns. With one worker that is the calling goroutine; with several, it is a worker. A block is about 3,000 keys with Bijection and 31,600 with PTRHash (§7.3), and a `yield` that starts blocking stops each worker at its next block. + +While `yield` blocks, the rest of the build stops behind the parked workers: what feeds them stops once their queue is full, and the writer once it has committed the blocks already solved. A parked build holds only its buffers and open files. A `yield` that returns an error fails the build with that error, as a block that fails to build does. The context is done once the build is canceled or has failed, so a `yield` that waits on it returns then. + +### 6.5. Thread safety - **Queries** are thread-safe and lock-free once the index is open: the data is immutable and each query reads an independent block. The RAM index must be fully loaded and visible before concurrent queries begin. - **Solvers** are single-threaded; each parallel worker has its own. diff --git a/yield_test.go b/yield_test.go new file mode 100644 index 0000000..e3b7850 --- /dev/null +++ b/yield_test.go @@ -0,0 +1,288 @@ +package streamhash + +import ( + "bytes" + "context" + "errors" + "fmt" + "os" + "path/filepath" + "sync/atomic" + "testing" + "time" +) + +// testGate is a gate a caller would hand WithYield: a yield waits until open +// is closed. It counts the yields entered. +type testGate struct { + open chan struct{} + entered atomic.Int64 +} + +func newTestGate() *testGate { return &testGate{open: make(chan struct{})} } + +func (g *testGate) yield(ctx context.Context) error { + g.entered.Add(1) + select { + case <-g.open: + return nil + case <-ctx.Done(): + return ctx.Err() + } +} + +// waitParked waits for n goroutines to park at g. It fails the test if the +// build returns on done first, and with a goroutine dump if neither happens +// within a minute. +func waitParked(t *testing.T, g *testGate, n int, done <-chan error) { + t.Helper() + err := runBuildWithWatchdog(t, time.Minute, func() error { + for g.entered.Load() < int64(n) { + select { + case err := <-done: + return fmt.Errorf("the build returned before %d goroutines parked: %v", n, err) + case <-time.After(time.Millisecond): + } + } + return nil + }) + if err != nil { + t.Fatal(err) + } +} + +// yieldBuild is one of the builds WithYield applies to. +type yieldBuild struct { + name string + workers int + build func(ctx context.Context, output string, opts ...BuildOption) error + want []byte +} + +// buildWithWatchdog runs c's build with yield, failing the test if it does +// not return. +func (c yieldBuild) buildWithWatchdog(t *testing.T, output string, yield func(context.Context) error) error { + t.Helper() + return runBuildWithWatchdog(t, time.Minute, func() error { + return c.build(context.Background(), output, WithWorkers(c.workers), WithYield(yield)) + }) +} + +// yieldBuilds returns the builds WithYield applies to over n keys, each inline +// and parallel, with the index they all build: the sorted-files build, the +// SortedBuilder, and the UnsortedBuilder through AddKey, which keeps this +// many keys in memory, and through AddKeys, whose writers spill them to disk. +func yieldBuilds(t *testing.T, dir string, n int) []yieldBuild { + t.Helper() + rng := newTestRNG(t) + recs := uniqueSortedRecords(rng, n, 3) + files := writeLayout(t, dir, rng, recs, 3, layoutOneFile) + entries := make([]entry, len(recs)) + for i, r := range recs { + entries[i] = entry{Key: recs[i].key[:], Payload: r.payload} + } + opts := []BuildOption{WithFingerprint(1), WithPayload(3)} + want := referenceIndex(t, filepath.Join(dir, "reference.idx"), recs, opts...) + fromFiles := func(ctx context.Context, output string, more ...BuildOption) error { + return buildFromSortedFiles(ctx, output, files, sortedBuildTuning{stripeKeys: 1000}, append(more, opts...)...) + } + sorted := func(ctx context.Context, output string, more ...BuildOption) error { + return buildFromEntries(ctx, output, entries, append(more, opts...)...) + } + addKey := func(ctx context.Context, output string, more ...BuildOption) error { + ub, err := NewUnsortedBuilder(ctx, output, uint64(len(entries)), dir, append(more, opts...)...) + if err != nil { + return err + } + for _, e := range entries { + if err := ub.AddKey(e.Key, e.Payload); err != nil { + ub.Close() + return err + } + } + return ub.Finish() + } + addKeys := func(ctx context.Context, output string, more ...BuildOption) error { + ub, err := NewUnsortedBuilder(ctx, output, uint64(len(entries)), dir, append(more, opts...)...) + if err != nil { + return err + } + return ub.AddKeys(1, func(_ int, add func([]byte, uint64) error) error { + for _, e := range entries { + if err := add(e.Key, e.Payload); err != nil { + return err + } + } + return nil + }) + } + return []yieldBuild{ + {"files/inline", 1, fromFiles, want}, + {"files/parallel", 4, fromFiles, want}, + {"sorted/inline", 1, sorted, want}, + {"sorted/parallel", 4, sorted, want}, + {"unsorted-addkey/inline", 1, addKey, want}, + {"unsorted-addkey/parallel", 4, addKey, want}, + {"unsorted-addkeys/inline", 1, addKeys, want}, + {"unsorted-addkeys/parallel", 4, addKeys, want}, + } +} + +// TestWithYieldHoldsTheBuild closes the gate before the build starts, checks +// that every goroutine building blocks parks at its first block, then opens +// the gate and checks the index and that every block yielded once. +func TestWithYieldHoldsTheBuild(t *testing.T) { + dir := t.TempDir() + for _, c := range yieldBuilds(t, dir, 30000) { + t.Run(c.name, func(t *testing.T) { + g := newTestGate() + output := filepath.Join(dir, "held.idx") + done := make(chan error, 1) + go func() { done <- c.build(t.Context(), output, WithWorkers(c.workers), WithYield(g.yield)) }() + waitParked(t, g, c.workers, done) + time.Sleep(50 * time.Millisecond) + if got := g.entered.Load(); got != int64(c.workers) { + t.Fatalf("%d goroutines parked at the gate, want %d", got, c.workers) + } + close(g.open) + if err := runBuildWithWatchdog(t, time.Minute, func() error { return <-done }); err != nil { + t.Fatal(err) + } + if !bytes.Equal(readFileBytes(t, output), c.want) { + t.Fatal("the index differs from the reference") + } + checkYieldPerBlock(t, output, g) + }) + } +} + +// checkYieldPerBlock checks that the build of the index at path entered g +// once per block. +func checkYieldPerBlock(t *testing.T, path string, g *testGate) { + t.Helper() + idx, err := Open(path) + if err != nil { + t.Fatal(err) + } + defer idx.Close() + if blocks := int64(idx.NumBlocks()); g.entered.Load() != blocks { + t.Fatalf("%d yields for %d blocks", g.entered.Load(), blocks) + } +} + +// TestWithYieldError checks that a yield's error fails the build with it, +// whether it is the first block's or the second's, an empty block's among +// them with one key, and that the failed build removes its output. +func TestWithYieldError(t *testing.T) { + errStop := errors.New("stop") + for _, n := range []int{1, 30000} { + dir := t.TempDir() + for _, c := range yieldBuilds(t, dir, n) { + for _, failAt := range []int64{1, 2} { + t.Run(fmt.Sprintf("%s/keys=%d/yield=%d", c.name, n, failAt), func(t *testing.T) { + var calls atomic.Int64 + yield := func(context.Context) error { + if calls.Add(1) == failAt { + return errStop + } + return nil + } + output := filepath.Join(dir, "failed.idx") + if err := c.buildWithWatchdog(t, output, yield); !errors.Is(err, errStop) { + t.Fatalf("the build returned %v, want the yield's error", err) + } + if _, err := os.Stat(output); !os.IsNotExist(err) { + t.Fatalf("the failed build left its output: %v", err) + } + }) + } + } + } +} + +// TestWithYieldCanceled cancels a build parked at the gate and checks that +// it returns the cancellation and removes its output. +func TestWithYieldCanceled(t *testing.T) { + dir := t.TempDir() + for _, c := range yieldBuilds(t, dir, 30000) { + t.Run(c.name, func(t *testing.T) { + g := newTestGate() + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + output := filepath.Join(dir, "canceled.idx") + done := make(chan error, 1) + go func() { done <- c.build(ctx, output, WithWorkers(c.workers), WithYield(g.yield)) }() + waitParked(t, g, c.workers, done) + cancel() + if err := runBuildWithWatchdog(t, time.Minute, func() error { return <-done }); !errors.Is(err, context.Canceled) { + t.Fatalf("the canceled build returned %v", err) + } + if _, err := os.Stat(output); !os.IsNotExist(err) { + t.Fatalf("the canceled build left its output: %v", err) + } + }) + } +} + +// TestWithYieldPerBlock checks that a build yields for empty blocks too: with +// no keys both blocks are empty, and with one key one of the two is. +func TestWithYieldPerBlock(t *testing.T) { + for _, n := range []int{0, 1} { + dir := t.TempDir() + for _, c := range yieldBuilds(t, dir, n) { + t.Run(fmt.Sprintf("%s/keys=%d", c.name, n), func(t *testing.T) { + g := newTestGate() + close(g.open) + output := filepath.Join(dir, "counted.idx") + if err := c.buildWithWatchdog(t, output, g.yield); err != nil { + t.Fatal(err) + } + if !bytes.Equal(readFileBytes(t, output), c.want) { + t.Fatal("the index differs from the reference") + } + checkYieldPerBlock(t, output, g) + }) + } + } +} + +// TestWithYieldNil checks that WithYield(nil) builds the index that no option +// does, with no yield to call. One key makes two blocks, one of them empty, +// which reach every place a block is built. +func TestWithYieldNil(t *testing.T) { + dir := t.TempDir() + for _, c := range yieldBuilds(t, dir, 1) { + t.Run(c.name, func(t *testing.T) { + output := filepath.Join(dir, "nil.idx") + if err := c.buildWithWatchdog(t, output, nil); err != nil { + t.Fatal(err) + } + if !bytes.Equal(readFileBytes(t, output), c.want) { + t.Fatal("the index differs from the reference") + } + }) + } +} + +// TestWithYieldEchoKeepsTheFailure fails a sorted-files build on a record out +// of order, with a yield that returns its context's error as a gate does once +// the build has failed, and checks that the build reports the record and not +// the cancellation that the yield echoes. +func TestWithYieldEchoKeepsTheFailure(t *testing.T) { + rng := newTestRNG(t) + dir := t.TempDir() + path := filepath.Join(dir, "out-of-order.sorted") + writeSortedFile(t, path, SortedFileConfig{PayloadSize: 3}, uniqueSortedRecords(rng, 30000, 3)) + data := readFileBytes(t, path) + swapRecords(data, MinKeySize+3, 777) + if err := os.WriteFile(path, data, 0o600); err != nil { + t.Fatal(err) + } + echo := func(ctx context.Context) error { return ctx.Err() } + for range 20 { + err := buildFilesWithWatchdog(t, context.Background(), filepath.Join(dir, "failed.idx"), []string{path}, sortedBuildTuning{stripeKeys: 1000}, WithWorkers(4), WithYield(echo)) + if !errors.Is(err, ErrUnsortedInput) { + t.Fatalf("the build returned %v, want ErrUnsortedInput", err) + } + } +}