Documentation
¶
Overview ¶
Package worker provides a Worker interface and WorkerGroup for managing concurrent background workers with graceful lifecycle control.
Package worker provides a Worker interface and WorkerGroup for managing concurrent background workers.
ref: zeromicro/go-zero core/service/servicegroup.go — ServiceGroup pattern Adopted: parallel Start/Stop, goroutine-per-worker, sync.Once for stop. Deviated: context-based lifecycle (Start/Stop take ctx) instead of bare Start()/Stop(); error returns for diagnostics.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LazyWorker ¶
type LazyWorker struct {
// contains filtered or unexported fields
}
LazyWorker is a Worker whose concrete delegate is resolved at runtime (via Set) after it's already wired into a WorkerGroup. Used when a Worker is produced during Bootstrap.Run after WithWorkers already captured this placeholder.
ref: docs/plans/202604191515-auth-federated-whistle.md — S37 WORKER-LAZY-HOIST
Thread safety: Set (writer) and Start/Stop (readers) synchronize via atomic.Pointer. Semantics: nil delegate → Start/Stop are no-op success (preserves lazyBootstrapWorker contract where adminExists==true yields no cleaner).
func (*LazyWorker) Set ¶
func (l *LazyWorker) Set(w Worker) (stored bool)
Set atomically assigns the delegate Worker. First call wins: subsequent calls are ignored and return false. Passing nil is rejected and returns false. The single-producer bootstrap sink contract is preserved.
type PeriodicWorker ¶
type PeriodicWorker struct {
// contains filtered or unexported fields
}
PeriodicWorker runs a function at a fixed interval. Panics in the function are isolated and logged, not propagated.
func NewPeriodicWorker ¶
func NewPeriodicWorker(clk clock.Clock, interval time.Duration, fn func(ctx context.Context)) *PeriodicWorker
NewPeriodicWorker creates a PeriodicWorker that runs fn every interval.
type Worker ¶
Worker is a type alias for the kernel Worker interface. The authoritative definition lives in kernel/worker; this alias lets the runtime/worker implementations (WorkerGroup, LazyWorker, PeriodicWorker) type-check against Worker without importing kernel/worker from every call site.
This is not a migration shim — runtime/worker is the canonical package for Worker implementations, and the alias is how implementations declare they satisfy the kernel contract.
Guidance for new consumers: code outside runtime/worker (e.g., adapters/, cells/) SHOULD import kernel/worker directly and reference worker.Worker (the kernel contract). This alias exists for historical compatibility and for runtime/worker's own implementations (WorkerGroup, LazyWorker, PeriodicWorker) to satisfy the kernel contract without importing the kernel package from every local file.
ref: kernel/worker/worker.go — authoritative Worker interface definition.
type WorkerGroup ¶
type WorkerGroup struct {
// contains filtered or unexported fields
}
WorkerGroup manages multiple workers, starting them concurrently and stopping them when requested.
func (*WorkerGroup) Add ¶
func (g *WorkerGroup) Add(w Worker)
Add registers a worker with the group.
func (*WorkerGroup) Start ¶
func (g *WorkerGroup) Start(ctx context.Context) error
Start launches all workers concurrently. It blocks until all workers return. If any worker returns a non-context error, all sibling workers are canceled via a shared context. The first error encountered is returned.
Early-exit handling: a worker that returns nil while the group context is still live has terminated its long-running loop without signaling failure — historically that produced a silent firstErr=nil. The group now records kworker.ErrWorkerExitedEarly so callers can errors.Is-detect the abnormal signal. Returns from a Stop or context cancellation propagate untouched (errors.Is(err, context.Canceled) is honored).
Source Files