doc.go

// Package syncx provides typed, context-aware concurrency primitives for Go.
//
// It complements the standard library's sync package with higher-level
// patterns that recur in concurrent programs: awaiting asynchronous results,
// retrying flaky operations, bounding concurrency, coordinating goroutine
// phases, and consuming channels without leaking goroutines. Every blocking
// operation accepts a context.Context, so waits can always be bounded by
// cancellation or a deadline.
//
// # Future — start work now, use the result later
//
// Future runs a task in its own goroutine and lets any number of callers
// wait for its single result. It replaces the hand-rolled channel-plus-flag
// dance used to overlap slow work (an RPC, a query) with other computation:
//
//	f := syncx.NewFuture(func() (User, error) { return fetchUser(ctx, id) })
//	// ... do other work while the fetch runs ...
//	user, err := f.Await(ctx)
//
// # Retry — absorb transient failures
//
// Retry re-invokes a task with linear backoff until it succeeds, attempts
// run out, or the context is cancelled. Use it around operations that fail
// intermittently (network calls, lock contention) instead of writing the
// same for-loop with a timer at every call site:
//
//	cfg, err := syncx.Retry(ctx, 5, 100*time.Millisecond, fetchConfig)
//
// # Semaphore — bound concurrency
//
// Semaphore limits how many goroutines run a section at once, protecting a
// scarce resource (database connections, memory-heavy work, an upstream
// API) from being overwhelmed:
//
//	sem := syncx.NewSemaphore(10)
//	if err := sem.Acquire(ctx); err != nil {
//		return err
//	}
//	defer sem.Release()
//	// at most 10 goroutines execute here concurrently
//
// # Barrier — align goroutines at a checkpoint
//
// Barrier blocks each arriving goroutine until a fixed number have arrived,
// then releases them all and resets for the next round. Use it for phased
// algorithms where no goroutine may start phase N+1 until every goroutine
// finished phase N (simulations, staged load tests, batch steps).
//
// # OrDone — consume channels without leaking
//
// OrDone wraps a receive loop so it terminates when either the source
// channel closes or the context is cancelled. It removes the repetitive
// nested-select needed to make `for v := range ch` cancellable:
//
//	for v := range syncx.OrDone(ctx, source) {
//		process(v)
//	}
//
// # Related packages
//
// Subpackages build on the same conventions: stream (channel pipelines and
// fan-in/fan-out), workerpool (typed worker pools and batching), pubsub
// (topic-based publish/subscribe), and control (throttling, circuit
// breaking, debouncing).
package syncx