package process
Import Path
go.pact.im/x/process (on go.dev)
Dependency Relation
imports 6 packages, and imported by 3 packages
Involved Source Files
chain.go
parallel.go
Package process provides primitives for managing processes, an abstraction
for stateful goroutines.
runner.go
task.go
Package-Level Type Names (total 12, in which 5 are exported)
Callback is a type alias for the function passed to Runner’s Run method. See
[Runner] documentation for more details.
Process represents a stateful process that is running in the background.
It exposes Start and Stop methods that use an underlying state machine to
prevent operations in invalid states. Process is safe for concurrent use.
Unlike some implementations of the underlying [Runner] interface that allow
multiple consecutive Run invocations on the same instance, a Process may not
be reset and started after being stopped.
cancel context.CancelFunc
done chan struct{}
err atomic.Value
parent context.Context
runner Runner
state State
stateMu sync.Mutex
stop chan struct{}
Done returns a channel that is closed when process terminates.
Err returns the error from running the process.
Start starts the process or cancels the underlying process context on error.
The startup deadline may be set using the given ctx context. Note that the
context would not be used by process directly so the associated values are
not propagated.
It returns [ErrProcessInvalidState] if the process is not in the initial
state.
State returns the current process state.
Stop stops the process by returning from the Run method callback and waiting
for the termination.
The shutdown deadline may be set using the given ctx context. If the deadline
is exceeded, underlying context is canceled, signaling a forced shutdown to
the process.
It returns [ErrProcessInvalidState] if the process was not started or has
already been stopped.
transition advances to the next process state. It returns false if there is
not transition from the current to the given next state.
func NewProcess(ctx context.Context, runner Runner) *Process
Runner defines an entrypoint for the process that should be considered
running and ready for use when the Run’s method callback is called.
Runner performs graceful shutdown when the callback returns. In this case,
the context is not canceled and the process may access external resources,
e.g. perform some network requests and persist state to database. Otherwise
a context cancellation is used to force shutdown.
Run executes the process. Callback function is called when the
process has been initialized and began execution. The process is
interrupted if the callback returns or the given context expires.
On termination the context passed to the callback is canceled.
To make debugging easier, callback runs in the same goroutine where
Run was invoked. Note though that this behavior currently is not
supported by all existing Run implementations.
It is safe to assume that callback is called at most once per Run
invocation.
RunnerFunc
*go.pact.im/x/supervisor.Supervisor[...]
*chainRunner
*chainState
*groupRunner
*leafRunner
*nopRunner
*prefixedErrorRunner
*startStopRunner
func Chain(deps ...Runner) Runner
func Leaf(runInForeground, gracefulStop func(ctx context.Context) error) Runner
func Nop() Runner
func Parallel(deps ...Runner) Runner
func PrefixedError(prefix string, runner Runner) Runner
func Sequential(deps ...Runner) Runner
func StartStop(startInBackground, gracefulStop func(ctx context.Context) error) Runner
func go.pact.im/x/grpcprocess.Server(srv *grpc.Server, lis net.Listener) Runner
func go.pact.im/x/httpprocess.Server(srv *http.Server, lis net.Listener) Runner
func Chain(deps ...Runner) Runner
func NewProcess(ctx context.Context, runner Runner) *Process
func Parallel(deps ...Runner) Runner
func PrefixedError(prefix string, runner Runner) Runner
func Sequential(deps ...Runner) Runner
RunnerFunc is a function that implements the Runner interface.
Run implements the Runner interface.
RunnerFunc : Runner
State represents the current state of the process.
func (*Process).State() State
func (*Process).transition(next State, advance func()) bool
const StateInitial
const StateRunning
const StateStarting
const StateStopped
Package-Level Functions (total 8, all are exported)
Chain returns a [Runner] instance that starts and runs processes by nesting
them in callbacks. If no processes are given, it returns [Nop] instance.
Leaf converts a “leaf” function to a process entrypoint with callback. It
accepts an optional gracefulStop function to perform graceful shutdown. If
the function is nil, the process will be terminated by context cancellation
instead.
The resulting [Runner] returns first non-nil error from functions in the
following order: callback, gracefulStop, runInForeground. That is, if both
callback and gracefulStop return a non-nil error, the latter is ignored.
Example (HTTP):
var lis net.Listener
var srv *http.Server
process.Leaf(
func(_ context.Context) error {
err := srv.Serve(lis)
if errors.Is(err, http.ErrServerClosed) {
return nil
}
return err
},
func(ctx context.Context) error {
err := srv.Shutdown(ctx)
if err != nil {
return srv.Close()
}
return nil
},
)
Example (gRPC):
var lis net.Listener
var srv *grpc.Server
process.Leaf(
func(_ context.Context) error {
return srv.Serve(lis)
},
func(ctx context.Context) error {
done := make(chan struct{})
go func() {
srv.GracefulStop()
close(done)
}()
select {
case <-ctx.Done():
srv.Stop()
<-done
case <-done:
}
return nil
},
)
Alternatively, use [go.pact.im/x/httpprocess] package for HTTP and
[go.pact.im/x/grpcprocess] for gRPC.
NewProcess returns a new stateful process instance for the given [Runner]
type parameter that would run with the ctx context.
Nop returns a Runner instance that performs no operations and returns when
the callback does.
Parallel returns a [Runner] instance that starts and runs processes in
parallel. If no processes are given, it returns Nop instance.
The resulting [Runner] calls callback after all process dependencies are
successfully started. If any dependecy fails to start, processes that have
already started are gracefully stopped. If any dependency fails before the
main callback returns, the context passed to callback is canceled and all
processes are gracefully stopped (unless the parent context has expired).
The callbacks of dependencies return after the callback of the resulting
dependent process. Run returns callback error if it is not nil, otherwise it
returns combined errors from dependencies.
PrefixedError returns a process that returns an error prefixed with the given
prefix string on failure.
Sequential returns a [Runner] instance with the same guarantees as the
Parallel function, but starts and stops processes in sequential order.
StartStop returns a [Runner] instance for the pair of start/stop functions.
The stop function should perform a graceful shutdown until a context expires,
then proceed with a forced shutdown.
The resulting [Runner] returns either start error or the first non-nil error
from callback and stop functions. If both callback and stop return a non-nil
error, the latter is ignored.
Package-Level Variables (only one, which is exported)
ErrProcessInvalidState is an error that is returned if the process
is not in the valid state for the operation.
Package-Level Constants (total 4, all are exported)
StateInitial is the initial state of the process. If Stop is called
in initial state, it prevents subsequent Start calls from succeeding,
thus entering StateStopped. Otherwise the transition on Start call
is to the StateStarting.
StateRunning is the state process enters after a successful startup.
The only possible transition is to the StateStopped if either Stop
is called or a process terminates.
StateStarting is the starting state that process enters when Start
is called from initial state. It transitions to either StateRunning
on success or StateStopped on failure (or premature shutdown observed
during startup).
StateStopped is the final state of the process. There are no
transitions from this state.
The pages are generated with Golds v0.7.6. (GOOS=linux GOARCH=amd64)