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) + } + } +}