lifecycle

type CGroup interface {
	// Adds the context to this group.
	// Returns true if the underlying context is not yet done and this context was added to the active set, even briefly.
	Add(c context.Context) (ok bool)

	// Starts or retrieves the prior context for this CGroup.
	// This will be already canceled if no contexts were added.
	Start() (ctx context.Context)

	// Wait ensures this group has started, and then blocks until the [context.Context] is completed, returning its cause if not the default [context.Canceled].
	Wait() (err error)

	// Go runs the given method as part of this group.
	// It will only start after Start() has been called with valid contexts.
	// Any returned error will cancel the group's [context.Context] directly, rather than with any provided cause.
	// Returns true if the method has a chance of running.
	Go(fn func(c context.Context) (err error)) (ok bool)

	// Halt runs the given method when this group may be about to shut down.
	//
	// It is passed a channel which is closed if the group restarts.
	// The method passed here should prevent further Add() calls in your code before doing teardown work.
	// Otherwise, you risk a resume race.
	//
	// The passed method will only run after a successful Start() and then a potential shutdown.
	// Any returned error will cancel the group's [context.Context] directly, rather than with any provided cause.
	// Returns true if the method has a chance of running.
	Halt(fn func(c context.Context, resume <-chan struct{}) (err error)) (ok bool)
}

type Check[T comparable] func(ctx context.Context, token T) (err error)

type TGroup[T comparable] interface {
	// Provide provides a context tagged with a unique T.
	// Calling Provide with the same T unions the lifecycle of the context.
	Provide(token T, ctx context.Context) (ok bool)

	// Revoke revokes a prior T early, ignoring its [context.Context].
	Revoke(token T) (ok bool)

	// Access provides a derived context that is valid while any T passes the given check, and has a valid context.
	Access(parent context.Context, check Check[T]) (derived context.Context)

	// Permit performs a one-time check to determine whether any T passes the given check.
	Permit(parent context.Context, check Check[T]) (err error)
}

type WorkerFunc[E any] func(ctx context.Context, events iter.Seq[E]) (err error)

type WorkerStatus interface {
	// Ready returns a channel which is closed when this Worker's iterator has been started.
	// This may never be closed.
	Ready() (ch <-chan struct{})

	// Idle returns a unique channel which is closed when this Worker is no longer reading its iterator.
	// It yields true if Ready() was previously closed.
	Idle() (ch <-chan bool)

	// Done returns a unique channel which is closed when this Worker is finally shutdown.
	// This returns any error reason (context or direct).
	Done() (ch <-chan error)
}