package process
Import Path
go.pact.im/x/process (on go.dev)
Dependency Relation
imports 6 packages, and imported by 2 packages
Involved Source Files
chain.go
parallel.go
Package process provides primitives for managing processes, an abstraction
for stateful goroutines.
runnable.go
task.go
Package-Level Type Names (total 12, in which 5 are exported)
Callback is a type alias for the function passed to Runnable’s Run method.
See Runnable 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 Runnable 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.Error
parent context.Context
proc Runnable
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, proc Runnable) *Process
Runnable defines a blocking long-running process that that should be
considered running and ready for use when the Run’s method callback is
called.
Runnable 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.
RunnableFunc
*go.pact.im/x/supervisor.Supervisor
*chainRunnable
*chainState
*groupRunnable
*leafRunnable
*namedRunnable
*nopRunnable
*startStopRunnable
func Chain(deps ...Runnable) Runnable
func Leaf(runInForeground, gracefulStop func(ctx context.Context) error) Runnable
func Named(name string, p Runnable) Runnable
func Nop() Runnable
func Parallel(deps ...Runnable) Runnable
func Sequential(deps ...Runnable) Runnable
func StartStop(startInBackground, gracefulStop func(ctx context.Context) error) Runnable
func go.pact.im/x/grpcprocess.Server(srv *grpc.Server, lis net.Listener) Runnable
func Chain(deps ...Runnable) Runnable
func Named(name string, p Runnable) Runnable
func NewProcess(ctx context.Context, proc Runnable) *Process
func Parallel(deps ...Runnable) Runnable
func Sequential(deps ...Runnable) Runnable
RunnableFunc is a function that implements the Runnable interface.
Run implements the Runnable interface.
RunnableFunc : Runnable
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 Runnable 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 runnable process function that accepts
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 Runnable 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/grpcprocess] package for gRPC.
Named returns a process that returns an error prefixed with name on failure.
NewProcess returns a new stateful process instance for the given Runnable
type parameter that would run with the ctx context.
Nop returns a Runnable instance that performs no operations and returns when
the callback does.
Parallel returns a Runnable instance that starts and runs processes in
parallel. If no processes are given, it returns Nop instance.
The resulting Runnable 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.
Sequential returns a Runnable instance with the same guarantees as the
Parallel function, but starts and stops processes in sequential order.
StartStop returns a Runnable 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 Runnable 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.4.9. (GOOS=linux GOARCH=amd64)