Documentation
¶
Overview ¶
Package goro provides utilities for spawning and subsequently managing the liftime(s) of one or more goroutines. This package relies heavily on the context package to provide consistent cancellation semantics for long-lived goroutines. The goal of this package is to provide a unified way to cancel and wait on running goroutines as is often seen in "service" or "daemon" types with Start()/Stop() lifecycle functions and to unify the multiplicity of approaches that have been adopted over time.
Note: If you're looking for a short-lived (e.g. request-scoped) group of
transient goroutines, you probably want `errgroup.Group` from
https://golang.org/x/sync/errgroup.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Group ¶ added in v1.13.0
type Group struct {
// contains filtered or unexported fields
}
Group manages a set of long-running goroutines. Goroutines are spawned individually with Group.Go and after that interrupted and waited-on as a single unit. The expected use-case for this type is as a member field of a background process type that spawns one or more goroutines in its Start() function and then stops those same goroutines in its Stop() function. The zero-value of this type is valid. A Group must not be copied after first use.
Example ¶
Output: starting backgroundLoop1 starting backgroundLoop2 stopping backgroundLoop1 stopping backgroundLoop2
func (*Group) Cancel ¶ added in v1.13.0
func (g *Group) Cancel()
Cancel cancels the `context.Context` that was passed to all goroutines spawned via `Go` on this `Group`.
func (*Group) Go ¶ added in v1.13.0
func (g *Group) Go(f func(ctx context.Context) error)
Go spawns a goroutine whose lifecycle will be managed via this Group object. All functions passed to Go on the same instance of Group will be given the same `context.Context` object, which will be used to indicate cancellation. If the supplied func does not abide by `ctx.Done()` of the provided `context.Context` then `Wait()` on this `Group` will hang until all functions exit on their own (possibly never). NOTE: Errors returned by the supplied function are ignored.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle is a threadsafe and multi-stop safe handle to a single running goroutine.
func NewHandle ¶ added in v1.17.3
func NewHandle(ctx context.Context) *Handle
NewHandle creates a *Handle that serves as a handle to a goroutine. The caller should call Go exactly once on the returned value. NewHandle and Go are separate function so that the *Handle can be stored into a field before the goroutine starts, which makes it possible for the goroutine to call Done() on itself (maybe indirectly) without a race condition.
func (*Handle) Cancel ¶
func (h *Handle) Cancel()
Cancel requests that this goroutine stop by cancelling the associated context object. This function is threadsafe and idempotent. Note that this function _requests_ termination, it does not forcefully kill the goroutine.
func (*Handle) Done ¶
func (h *Handle) Done() <-chan struct{}
Done exposes a channel that allows outside goroutines to block on this goroutine's completion. Whatever time passes between a call to Cancel() and the Done() channel closing is the time taken by the goroutine to shut itself down.
Source Files